A descrição da ferramenta é o contrato

Eu queria que os agentes citassem dados reais em vez de chutar. O movimento óbvio é entregar uma API para cada agente. Também é o movimento errado, porque um agente não lê a referência da sua API. Ele lê a superfície da ferramenta. Então a spec não é um documento ao lado da ferramenta. A spec é a descrição da ferramenta.

A descrição carrega o contrato inteiro

Não existe enum que se possa impor na fronteira. O modelo pode mandar o que quiser. Então a descrição tem que carregar o contrato inteiro: os valores canônicos, o casing, as regras de obrigatório-quando, os defaults inteligentes. Se a fonte tem uma regra, a ferramenta a codifica. Concretamente, a ferramenta de analytics que escrevi exige uma chave de ordenação sempre que a consulta agrupa por vídeo, porque a fonte não volta ordenada. Essa regra mora na descrição, não numa wiki que ninguém lê.

Constantes de single-tenant ficam fixas na URL, não expostas como argumentos:

Report: YouTube channel analytics.
  property: FIXED (single channel, baked into the URL)
  dimensions: one of [day, month, video, trafficSource]   # canonical, exact casing
  sort: REQUIRED when dimensions = video                   # the source is unordered
  dateRange: optional, defaults to the last 28 days

Uma chamada sem argumentos agora faz a coisa certa, e toda restrição que o agente poderia errar está escrita onde o agente de fato está olhando.

A ferramenta devolve fonte, nunca análise

A tentação forte é embutir a análise na ferramenta, para ajudar. Resista. O trabalho da ferramenta é ser uma fonte limpa e honesta. O trabalho do agente é a síntese. Pré-cozinhar a análise acopla os dois, esconde o sinal cru e deixa o agente mais burro, porque ele não enxerga mais sobre o que está raciocinando. Uma ferramenta que devolve a fonte crua e uma boa descrição vale mais do que uma que devolve uma opinião.

Lição

Trate a descrição da ferramenta como spec, não como documentação. É o único contrato que o agente de fato lê, então todo valor canônico, default e obrigatório-quando pertence a ela. Mantenha a ferramenta como fonte, nunca como opinião, e deixe o agente pensar, que é para isso que ele está ali.