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

With NO annotations provided, the description carries the full burden of behavioral disclosure. It does well: states what defines a 'real' increase (per-NPI delta, both-year payment requirement, dual thresholds), defaults, and public data provenance. It also discloses pricing. Minor gap: it doesn't disclose pagination behavior or whether results are sorted, but the tool's core behavioral contract (inclusion/exclusion criteria) is well specified.

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 dense paragraph that packs substantial value: purpose, delta semantics, defaults, filters, inclusion criteria, data provenance, and pricing. It's well front-loaded with the key differentiator ('real per-NPI delta'). Slightly long but every sentence earns its place — the only minor inefficiency is some repetition of the increase-threshold concepts.

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?

The tool has 8 params, no output schema, and zero annotations. The description provides strong coverage: purpose, threshold semantics, defaults, filters, inclusion/exclusion criteria, data source, and price. For a query tool with a moderately complex two-threshold comparison logic, this is well covered. The main omission is return-format/pagination details and sorting, but for a filtered list query the description is adequate.

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 75%, so the schema documents most parameters. The description adds meaning by explaining how min_increase_usd and min_pct_change interact (both must be cleared) and clarifies year/prior_year pairing semantics. It doesn't describe every param, but the ones not covered by the schema are addressed in prose or leave the schema to carry the load. Adds value 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?

The description clearly identifies the tool's purpose: finding physicians whose TOTAL CMS Open Payments industry payments increased year-over-year, distinguishing real per-NPI deltas from magnitude thresholds. It names the specific resource (CMS Open Payments physician data) and the operation (yoy increase search), and explicitly differentiates from a generic magnitude threshold filter. It also clarifies sibling distinction — this is the recipients variant among openPayments and manufacturers_yoyIncrease tools.

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?

The description provides explicit when-to-use guidance: defaults to 2023→2024 but any year pair is selectable, and it states filters (specialty, state, min_increase_usd, min_pct_change) and the inclusion criterion (paid in BOTH years with a real rise clearing both thresholds). It even disclaims it's not a consumer report, which guides appropriate use. This clearly distinguishes from siblings like openPayments_recipients_search and the manufacturers variants.

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