O que torna uma lista de ferramentas legível para um agente

Um agente nunca vê a sua documentação. Ele vê uma lista de nomes de ferramentas, descrições de uma linha e um schema JSON de parâmetros. Esse é o briefing inteiro. Se daí não dá para saber qual é a ferramenta certa, o agente escolhe a errada — ou faz ao usuário uma pergunta que nem precisaria existir.

Avaliamos e pontuamos cada superfície de ferramentas legível do catálogo. Depois de ler milhares, as falhas se agrupam.

1. Ferramentas que se sobrepõem

Duas ferramentas que poderiam atender ao mesmo pedido são o erro mais caro, porque o agente não tem critério de desempate. Se você tem search_docs e find_document, uma delas precisa dizer o que faz que a outra não faz.

2. Parâmetros sem significado

Um parâmetro chamado query, do tipo string, não diz nada ao agente. O que vai ali — uma palavra-chave, uma pergunta, um ID? Diferencia maiúsculas? O que acontece se vier vazio? O lugar disso é o schema, não o README.

3. Sem exemplos nas ambíguas

A maioria das ferramentas não precisa de exemplo. A que aceita um objeto livre, uma expressão de filtro ou um identificador específico do domínio precisa com certeza. Nas nossas avaliações, "faltam exemplos de uso" é uma das fraquezas mais frequentes — e quase sempre sobre uma ferramenta específica, não sobre o servidor todo.

4. Restrições silenciosas

Limites de taxa, número máximo de resultados, timeouts de execução, se a chamada custa dinheiro. Um agente que não sabe o limite vai esbarrar nele. Os servidores com melhor pontuação são os que escrevem isso claramente na descrição.

A versão curta

• Nomes distintos que sugiram trabalhos distintos.
• Cada parâmetro descrito pelo que se coloca dentro dele.
• Exemplos nas ferramentas sobre as quais um humano perguntaria.
• Limites escritos onde o agente realmente vai ler.

Nada disso exige mais ferramentas. Quase tudo exige menos, mais bem descritas.