Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavior: drafts are filtered out, and an answer whose benchmark has no defensible leader says so in `answer` rather than naming a winner. It also discloses the per-row shape. It stops short of noting pagination/volume, which keeps it off a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then usage guidance, then the return shape. The row-shape block earns its space because there is no output schema. Slightly long, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so: it enumerates the row fields and explains citation intent (`url` vs `benchmarkUrl`). Combined with the explicit when-to-use and follow-up routing, an agent has everything needed to select and invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single optional `benchmark` slug filter is fully documented in the schema, so the baseline is 3. The description references the `benchmark` field only as a returned value, not as an input filter, so it adds no semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and resource ('Returns every published answer page') and enumerates the payload semantics: a plain question, the answering sentence from live data, and the source benchmark. This is clearly differentiated from sibling get_benchmark, which is described as the 'full ranking behind it.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to call it ('when the user asks a question in words rather than by benchmark name') and supplies two concrete example questions. It also names the follow-up tool and the field to pass ('call get_benchmark with the returned benchmark slug'), removing all routing ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.