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

Goes well past the read-only annotations by disclosing result semantics: fit labels with named mismatches, price status vocabulary with the key caveat that 'unknown is never free', and that thin coverage yields no_match rather than padding. It also states that requirements in the query are checked per result and unverified ones marked unknown. Minor gap: no statement of result volume or whether repeated calls are deterministic.

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 and trigger before moving to output semantics and routing. It is dense but nearly every clause carries distinct information; the single run-on sentence structure makes it slightly harder to scan than it could be.

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?

A 10-parameter tool with nested filters is fully covered: purpose, trigger, result-field semantics, empty-result behavior, and sibling routing are all present. With an output schema available, the description still adds the interpretive context an agent needs to trust the returned fit and price labels.

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 100%, so the baseline is 3; the description earns above that by explaining cross-parameter semantics the schema does not, such as the price-status taxonomy and the rule that unknown pricing is never treated as free. It does not add guidance on sort, limit, or request_ref beyond what the schema already says.

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 specific verb and resource ('Finds products ... that do a task') and defines the output shape ('ranked shortlist'). It also explicitly delimits scope against siblings by pointing cost questions to price_benchmark, find_market, and get_group_fair_price, and overview questions to research_capability.

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?

Gives an explicit entry-point instruction ('start here to choose a product') plus a concrete trigger example ('MCP server to reply to Zendesk tickets'). It names both downstream steps (get_provider_profile, compare_providers) and the four sibling tools to use instead for cost or overview questions.

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