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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety behavior. It adds that discovery returns a list rather than a comparison and mentions stable IDs and URLs, but it does not cover rate limits, authentication, or pagination, leaving moderate gaps beyond what annotations already say.

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 long, dense block with a front-loaded core action followed by a scope exclusion list. It is appropriately sized for a search tool but the exclusion enumeration is heavy and some sentences could be folded without losing meaning.

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?

An output schema exists, so return-shape detail is not required, and the description helpfully notes it returns stable IDs, titles, and URLs. However, with one parameter at 0% schema coverage and no sibling differentiation, the definition is adequate but missing enough query semantics and routing guidance to be fully complete.

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 0% for the single query parameter, so the description must compensate. It describes what kinds of filters are possible (product, institution, term, maturity) and notes the 1-300 character limit indirectly, but does not explain syntax, free-text versus structured query, or field separators, leaving meaningful ambiguity.

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 states a broad verb (find/list) and resource (rate records) with some scoping detail, but the single-token name 'search' does not distinguish it from siblings like fetch or compare_rates. The description explains what it returns (stable IDs, titles, URLs), yet the core retrieval purpose is not crisply separated from other tools in the set.

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 implicitly signals use when no exact stable record ID is supplied, which is useful, but it does not explicitly name alternatives like compare_rates or fetch or state when not to use this tool. The exclusion list clarifies scope but does not guide tool selection among siblings.

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