Tools (Ferramentas)

Ferramentas são funções que seus agentes podem executar via MCP Servers.

Scopes e permissões (allowlist)

Ao conectar um MCP a um agente, você escolhe quais ferramentas (scopes) o agente pode usar. Cada tool corresponde a um scope no formato tool:<nome-da-tool>.

O Supersquad descobre os scopes disponíveis via protocolo MCP (PRM — Protected Resource Metadata). Na criação da integração:

1. O sistema lista as tools e scopes suportados pelo servidor
2. Você marca apenas as ferramentas desejadas
3. Em runtime, o agente só enxerga e pode chamar as tools autorizadas — o servidor MCP filtra quando suporta enforcement; o VoltAgent reforça o subset via allowedToolNames em todas as connections com scopes definidos.

Para MCPs com OAuth, os scopes selecionados são enviados no fluxo de autorização.

Se o servidor não publicar PRM completo, o sistema pode entrar em modo degradado (scopes derivados da lista de tools) — um aviso será exibido na interface.

Definindo ferramentas

typescript
const tool = {
  name: 'search_products',
  description: 'Busca produtos no catálogo por nome ou categoria',
  parameters: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: 'Termo de busca'
      },
      category: {
        type: 'string',
        description: 'Categoria do produto',
        enum: ['electronics', 'clothing', 'food']
      },
      minPrice: {
        type: 'number',
        description: 'Preço mínimo'
      },
      maxPrice: {
        type: 'number',
        description: 'Preço máximo'
      }
    },
    required: ['query']
  }
};

Tipos de parâmetros

Validação

Use enum para valores específicos:

typescript
{
  type: 'string',
  enum: ['low', 'medium', 'high'],
  description: 'Prioridade do ticket'
}

Ferramentas comuns

Busca em banco de dados

typescript
{
  name: 'search_database',
  description: 'Busca registros no banco de dados',
  parameters: {
    type: 'object',
    properties: {
      table: { type: 'string' },
      filters: { type: 'object' },
      limit: { type: 'number', default: 10 }
    }
  }
}

Envio de email

typescript
{
  name: 'send_email',
  description: 'Envia um email',
  parameters: {
    type: 'object',
    properties: {
      to: { type: 'string' },
      subject: { type: 'string' },
      body: { type: 'string' }
    },
    required: ['to', 'subject', 'body']
  }
}

Criar registro

typescript
{
  name: 'create_lead',
  description: 'Cria um novo lead no CRM',
  parameters: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      email: { type: 'string' },
      phone: { type: 'string' },
      source: { type: 'string' }
    },
    required: ['name']
  }
}

Boas práticas

1. Nomes descritivos - Use verbos de ação (search_, get_, create_)
2. Descrições claras - O agente usa isso para decidir quando usar
3. Parâmetros opcionais - Use required apenas quando necessário
4. Validação - Use enum para valores pré-definidos