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

Um agente nunca vê a sua documentação. Vê uma lista de nomes de ferramentas, descrições de uma linha e um esquema JSON de parâmetros. É esse o briefing completo. Se daí não se perceber qual é a ferramenta certa, o agente escolhe a errada — ou faz ao utilizador uma pergunta que não deveria ter sido precisa.

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

1. Ferramentas que se sobrepõem

Duas ferramentas que possam responder ao mesmo pedido são o erro mais caro, porque o agente não tem critério de desempate. Se tem search_docs e find_document, uma delas tem de dizer para que serve que a outra não serve.

2. Parâmetros sem significado

Um parâmetro chamado query, do tipo string, não diz nada ao agente. O que entra ali — uma palavra-chave, uma pergunta, um identificador? Distingue maiúsculas? O que acontece se ficar vazio? O lugar disso é o esquema, 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 próprio do domínio precisa de certeza. Nas nossas avaliações, "faltam exemplos de utilização" é uma das fraquezas mais frequentes — e quase sempre sobre uma ferramenta específica, não sobre o servidor inteiro.

4. Restrições silenciosas

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

A versão curta

• Nomes distintos que impliquem trabalhos distintos.
• Cada parâmetro descrito em função do que lá se coloca.
• Exemplos nas ferramentas sobre as quais um humano perguntaria.
• Limites escritos onde o agente os vai mesmo ler.

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