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

Annotations already mark this readOnly=true and openWorld=true, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: every value is 'provenanced,' computed indicator values are derived from plan data, and there are 'no synthetic scores' — this tells the agent how much to trust the data and what kind of output to expect.

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?

The description is two sentences with no filler: purpose and content in the first, derivation guarantee and usage pointer in the second. It front-loads the core definition and packs useful caveats ('where call-volume applies', 'no synthetic scores') without redundancy.

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?

For a read-only record-fetching tool, the description covers what data is returned, where the `section` slug comes from, and the provenance/no-synthetic guarantee. It does not mention failure behavior for unknown slugs or output formatting, but given no output schema and read-only annotations, the key operational context is present.

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 coverage is 50%: `section` has a rich description and the tool description reinforces its source (list_sections). However, `slug` has no schema description and the description only indirectly implies it is the vendor slug; it does not explain the format or how to discover valid slug values. Baseline for partially covered params is 3.

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?

The description names a specific resource ('Per-vendor benchmark card by slug') and a specific theme scope ('within any theme'), then lists exactly what the card contains: provenanced record, entry price, normalized costs at 100/500 calls, billing model, free tier, and integration breadth. This clearly distinguishes it from generic search tools like search_vendors. The 'no synthetic scores' statement further sharpens the purpose.

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?

It explicitly instructs the agent to set `section` to a theme slug from list_sections, which is actionable usage guidance. It does not explicitly name sibling tools as alternatives or give when-to-use vs when-not-to-use criteria, but the scoping instruction and 'do not assume the slug' warning provide clear context.

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