The tool description is the contract

I wanted the agents to cite real data instead of guessing at it. The obvious move is to hand each agent an API. It is also the wrong move, because an agent does not read your API reference. It reads the tool surface. So the spec is not a document sitting next to the tool. The spec is the tool description.

The description carries the whole contract

There is no enforceable enum at the boundary. The model can send whatever it wants. So the description has to carry the whole contract: the canonical values, the casing, the required-when rules, the smart defaults. If the source has a rule, the tool encodes it. Concretely, the analytics tool I wrote requires a sort key whenever the query groups by video, because the source does not come back ordered. That rule lives in the description, not in a wiki nobody reads.

Single-tenant constants get fixed in the URL, not exposed as arguments:

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

A zero-argument call now does the right thing, and every constraint the agent could get wrong is stated where the agent is actually looking.

The tool returns source, never analysis

The strong temptation is to pre-bake the analysis into the tool, to be helpful. Resist it. The tool’s job is to be a clean, honest source. The agent’s job is synthesis. Pre-cooking the analysis couples the two, hides the raw signal, and makes the agent dumber because it can no longer see what it is reasoning over. A tool that hands back the raw source and a good description is worth more than a tool that hands back an opinion.

Takeaway

Treat the tool description as a spec, not as documentation. It is the only contract the agent actually reads, so every canonical value, default, and required-when belongs inside it. Keep the tool a source, never an opinion, and let the agent do the thinking it is there to do.