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

Although no annotations are provided (bar is high), the description excellently discloses a critical behavioral trait: it can only truly compare if prior_year data is loaded, and returns total_matched=0 (never fabricated) otherwise. It also clarifies pricing ($0.1/call). These are exactly the kind of behavioral disclosures beyond what schema/annotations provide.

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 dense but efficient—two sentences accomplish a lot: purpose, semantics, defaults, filters, data caveat, pricing. It's front-loaded with the core semantic point before details. Slightly long but every clause earns its place; no wasted words.

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 filtered search tool with no output schema and no annotations, this description is remarkably complete: it states purpose, semantic distinction, filter behavior with defaults, comparison-year handling, data-availability caveat, and price. Despite 8 parameters, the agent has enough to invoke correctly in almost any scenario.

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 75%, which raises baseline to 3. The description adds meaningful semantics by clarifying the semantics of min_increase_usd/min_pct_change as AND-type thresholds (defaults 10k/10%) that apply to the per-manufacturer delta. However, it doesn't add detail for year vs prior_year beyond what the schema provides. Strong value but one step below full compensation.

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 is highly specific: verb 'search' + resource 'Manufacturers/GPOs', and crucially clarifies the semantics ('genuinely increased year-over-year' = per-manufacturer delta, not magnitude threshold). This distinguishes it clearly from the sibling manufacturers_openPayments and openPayments_recipients_yoyIncrease_search tools. Specifies filtering dimensions and defaults.

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 states the default year pair (2023→2024), what filters exist (specialty, state, min_increase_usd, min_pct_change), and importantly warns about the data caveat (op_manufacturer_payments holds only PY2024 today). This is explicit when/context guidance plus a critical data-availability warning that helps the agent decide when this tool will return empty results.

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