O problema
O Model Context Protocol (MCP), criado pela Anthropic, se tornou o padrão de facto para conectar agentes de IA a ferramentas externas. Mas à medida que mais desenvolvedores constroem servidores MCP, um padrão preocupante emerge: ferramentas mal projetadas que confundem o agente em vez de ajudá-lo.
Este guia, publicado pela AWS, mostra onde o design de ferramentas MCP dá errado e como corrigi-lo com abordagens práticas de engenharia de contexto.
Tradeoffs fundamentais no design de ferramentas MCP
1. Granularidade: ferramentas genéricas vs específicas
Ferramentas muito genéricas (ex: “execute qualquer SQL”) dão flexibilidade mas forçam o agente a tomar decisões complexas sobre sintaxe e schema. Ferramentas muito específicas (ex: “listar_usuarios_ativos”) são fáceis de usar mas exigem dezenas de ferramentas para cobrir todos os casos.
Recomendação: comece com ferramentas específicas para os casos de uso mais comuns (80/20) e adicione uma ferramenta genérica de fallback para consultas menos frequentes.
2. Schema de parâmetros: validação rigorosa vs flexibilidade
O schema JSON dos parâmetros é o contrato entre o agente e sua ferramenta. Um schema muito restritivo bloqueia o agente; um schema muito permissivo permite chamadas inválidas que falham em runtime.
Recomendação: use enum para valores fixos, forneça default para parâmetros opcionais com valores sensíveis, e inclua description significativos em cada campo — o agente usa essas descrições para decidir o que preencher.
3. Formato de retorno: estruturado vs texto livre
Retornar JSON permite que o agente faça parsing e tome decisões baseadas nos dados. Retornar texto livre é mais legível para humanos mas mais difícil para o agente processar.
Recomendação: retorne JSON estruturado com um campo summary legível por humanos e campos de dados tipados. Inclua metadados como total_results e truncated para que o agente saiba se precisa paginar.
4. Tratamento de erros: exceções vs mensagens de erro contextualizadas
Lançar exceções interrompe o fluxo do agente. Retornar erros como parte da resposta normal permite que o agente tente corrigir e chamar novamente.
Recomendação: nunca lance exceções para erros esperados (dados não encontrados, parâmetros inválidos). Retorne um JSON com {"error": true, "message": "...", "suggestion": "..."} que o agente possa interpretar e agir.
Padrão de engenharia de contexto
O insight central do artigo é que a descrição da ferramenta é tão importante quanto sua implementação. O agente decide qual ferramenta usar e com quais parâmetros baseado exclusivamente no texto da descrição. Algumas práticas recomendadas:
- Inclua exemplos de uso na descrição da ferramenta — o agente aprende por exemplos
- Use linguagem orientada a intenção: “Use esta ferramenta quando precisar…” em vez de descrever a implementação
- Especifique limitações explicitamente: “Esta ferramenta retorna no máximo 100 resultados”
- Documente efeitos colaterais: “Esta ferramenta envia um email real, não apenas simula”
Aplicação prática
Se você está construindo servidores MCP para conectar agentes a bancos de dados, APIs, sistemas de arquivos ou qualquer outra fonte de dados, o design da interface é o fator determinante entre um agente que funciona e um que alucina chamadas de ferramenta.
O artigo completo da AWS inclui exemplos de código em Python e TypeScript para implementar cada um desses padrões.
Descubra mais sobre noticiAI
Assine para receber nossas notícias mais recentes por e-mail.
