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

With no annotations, the description bears the full burden of behavioral disclosure. It discloses ranking by match_score/match_reasons, inclusion of observed-price and how_to_connect, filter/sort behavior (max_monthly_usd handling of unpriced providers), and that unknown query keys are never silently ignored. It also mentions rate-limit benefits from report_outcome. It doesn't explicitly state if the operation is read-only, but that's implied. Slightly more could be said about output volume or pagination, but it's quite transparent.

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 a single paragraph but front-loaded with purpose and usage guidance. It efficiently covers when to use, what results include, related tools, and provides at least one parameter hint (billing, sort). It's not overly verbose and each sentence adds value. Slightly long but appropriate given the tool's complexity.

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?

Given 8 parameters with nested objects and no output schema, the description covers the essential context: how results are ranked, what fields they contain (match_score, match_reasons, observed-price, how_to_connect), how to filter/sort for value, and pointers to more detailed tools. It addresses the complexity well and leaves little ambiguity about what the tool does and how to use it effectively.

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 baseline is 3. The description adds value beyond schema: it explains the purpose of sort (price_asc for value shopping), the behavior of max_monthly_usd with unpriced providers, mentions query aliases (q, text), and clarifies that unknown keys are not silently ignored. It also ties parameters to usage outcomes (e.g., filtering by billing, requiring public price). This adds meaningful context.

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 clearly states this is a 'Targeted provider search' for when you roughly know what you want, and explicitly distinguishes it from research_capability for new tasks and get_provider_profile for full details. The verb 'search' plus resource 'providers' is specific, and it differentiates from sibling tools by pointing to research_capability when the market is unknown.

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?

Provides explicit when-to-use: 'when you already know roughly what you want', and when-not-to: 'for a NEW task where the market isn't known yet, call research_capability first'. It also recommends get_provider_profile for a full version and report_outcome after usage, giving clear decision guidance and alternatives.

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