La descripción de la herramienta es el contrato

Quería que los agentes citaran datos reales en vez de adivinarlos. El movimiento obvio es darle una API a cada agente. También es el movimiento equivocado, porque un agente no lee la referencia de tu API. Lee la superficie de la herramienta. Así que la spec no es un documento que vive al lado de la herramienta. La spec es la descripción de la herramienta.

La descripción carga todo el contrato

No hay un enum que se pueda imponer en la frontera. El modelo puede mandar lo que quiera. Así que la descripción tiene que cargar todo el contrato: los valores canónicos, el casing, las reglas de obligatorio-cuando, los defaults inteligentes. Si la fuente tiene una regla, la herramienta la codifica. En concreto, la herramienta de analytics que escribí exige una clave de orden cada vez que la consulta agrupa por video, porque la fuente no vuelve ordenada. Esa regla vive en la descripción, no en una wiki que nadie lee.

Las constantes de single-tenant quedan fijas en la URL, no expuestas 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

Una llamada sin argumentos ahora hace lo correcto, y cada restricción en la que el agente podría equivocarse está escrita donde el agente realmente está mirando.

La herramienta devuelve fuente, nunca análisis

La tentación fuerte es meter el análisis en la herramienta, para ayudar. Resiste. El trabajo de la herramienta es ser una fuente limpia y honesta. El trabajo del agente es la síntesis. Precocinar el análisis acopla ambos, esconde la señal cruda y vuelve más tonto al agente, porque ya no ve sobre qué está razonando. Una herramienta que devuelve la fuente cruda y una buena descripción vale más que una que devuelve una opinión.

Lección

Trata la descripción de la herramienta como spec, no como documentación. Es el único contrato que el agente realmente lee, así que cada valor canónico, default y obligatorio-cuando va dentro de ella. Mantén la herramienta como fuente, nunca como opinión, y deja que el agente piense, que para eso está.