Guia de Design de Tools

Uma MCP Tool não é uma chamada de função. É um contrato. Descreve o que o sistema pode fazer, quem pode invocá-la, o que acontece durante a execução, e o que pode dar errado. Esse contrato deve ser legível por máquina, tipado e completo antes de um agente ou usuário invocar a tool.

O Padrão Tool Contract

Cada MCP Tool é descrita segundo um schema uniforme. O schema abrange não apenas tipos de entrada e saída, mas também nível de risco, permissões, side effects, audit events e possíveis casos de falha. Apenas quem conhece todos os campos pode usar uma tool com segurança, seja por um agente, uma webapp ou um workflow automatizado.

Os campos em resumo:

• Name, identificador único e legível por máquina no formato domain.verb
• Description, descrição em linguagem natural do propósito para agentes e desenvolvedores
• Category, classificação de negócio (ex.: communication, files, billing)
• Risk Level, classificação segundo o modelo de risco (Low a Forbidden)
• Autonomous Execution, se um agente pode invocar a tool sem aprovação humana
• Confirmation, se uma confirmação explícita do usuário é necessária
• Step-up Auth, se uma autenticação adicional é necessária e quando
• Input Schema, parâmetros tipados incluindo campos opcionais
• Output Schema, valores de retorno tipados incluindo códigos de status
• Permissions, quais permissões a tool exige
• Side Effects, todas as mudanças de estado fora do valor de retorno
• Audit Event, qual evento é registrado no Audit Log
• Failure Modes, lista completa de todos os códigos de erro possíveis

O exemplo a seguir mostra o contrato completo para emails.send_external, uma tool com risco crítico que dispara comunicação externa:

Cada campo tem uma função no sistema: permissions controla a Policy Engine, sideEffects informa a UI de confirmação, failureModes são avaliados no tratamento de erros, auditEvent é registrado no Audit Log. O contrato, portanto, não é apenas documentação , é parte do tempo de execução.

O modelo de risco

O MCP-first classifica cada tool em um de cinco níveis de risco. O nível determina se um agente pode invocar a tool de forma autônoma, se uma confirmação é necessária e se o Step-up Auth é exigido. A classificação não é opcional, é parte do contrato.

Low

Tools deste nível são puramente de leitura ou não produzem efeitos permanentes. Elas podem ser executadas autonomamente por agentes, sem confirmação ou Step-up Auth. São típicas consultas de lista, pesquisas e recursos de ajuda.

Medium

Tools deste nível criam dados ou estados, mas em um escopo estreitamente limitado sem efeito externo. Podem ser executadas autonomamente quando o escopo e o contexto emergem inequivocamente do workflow. Com contexto incerto, a confirmação é aconselhável.

High

Tools deste nível alteram estados relevantes do sistema ou afetam outros usuários e recursos externos. Geralmente exigem confirmação explícita. Um agente não pode executá-las silenciosamente.

Critical

Tools deste nível disparam comunicação externa, pagamentos, exclusões de dados ou alterações de permissões. Sempre exigem confirmação explícita e frequentemente Step-up Auth. Execução autônoma não é permitida.

Forbidden for AI

Tools deste nível não podem ser lidas nem executadas por um agente de IA. Elas estão completamente ocultas da Tool Discovery para agentes. A classificação é um limite rígido, não uma decisão de policy.

Idempotência

Muitas tools são invocadas várias vezes em workflows de agentes, por retries, execução paralela ou planejamento defeituoso. O MCP-first recomenda tornar as tools idempotentes sempre que possível: o mesmo input produz o mesmo resultado em múltiplas invocações, sem gerar duplicatas ou efeitos colaterais indesejados.

A tool create_download_link é um bom exemplo. Se já existir um link válido para um arquivo com o mesmo fileId e o mesmo expiresAt, a tool retorna esse link em vez de criar um segundo:

create_download_link(fileId: "f_abc123", expiresAt: "2025-12-31T23:59:00Z")

→ Primeira invocação: cria novo link, retorna linkId + url
→ Segunda invocação (mesmos parâmetros, link ainda válido): retorna o mesmo link
→ Terceira invocação (link expirado): cria novo link

A idempotência deve ser implementada explicitamente, ela não surge automaticamente. O campo sideEffects do Tool Contract deve descrever o comportamento em caso de repetição, para que agentes e clientes possam planejar corretamente.

Dry Run

Tools arriscadas, especialmente aquelas com efeitos em massa, devem oferecer um modo Dry Run. O Dry Run executa todas as validações e verificações, mas não gera side effects reais. O resultado mostra o que aconteceria, sem que nada realmente aconteça.

emails.bulk_send com dryRun: true retorna uma prévia completa:

// Request
{
  "tool": "emails.bulk_send",
  "params": {
    "templateId": "tmpl_newsletter_q3",
    "segmentId": "seg_active_customers",
    "dryRun": true
  }
}

// Response
{
  "dryRun": true,
  "recipientCount": 4821,
  "sampleMessages": [
    {
      "to": "[email protected]",
      "subject": "Ihr Q3-Update ist da",
      "previewText": "Liebe Anna, im dritten Quartal haben wir…"
    },
    {
      "to": "[email protected]",
      "subject": "Ihr Q3-Update ist da",
      "previewText": "Lieber Max, im dritten Quartal haben wir…"
    }
  ],
  "warnings": [
    "43 Empfänger haben keinen Vornamen, Fallback 'Hallo' wird verwendet.",
    "12 E-Mail-Adressen sind als unzustellbar markiert und werden übersprungen."
  ],
  "missingPermissions": [],
  "expectedSideEffects": [
    "4821 externe E-Mails werden versendet.",
    "4821 Audit-Events vom Typ email.external.sent werden erzeugt.",
    "Kampagnen-Status wird auf 'sent' gesetzt."
  ],
  "estimatedDurationMs": 18400
}

Somente após a revisão do resultado do Dry Run e a confirmação explícita pelo usuário é que a invocação real ocorre sem dryRun. O agente não pode pular o Dry Run quando a tool o declara como obrigatório.