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

Annotations already cover read-only, idempotent, non-destructive behavior, but the description adds substantial operational context: billing is 1 read unit per row with a minimum of 1, page size is capped at 500, and basic keys are limited to 50 rows per page. It also warns that oas is a deprecated alias with the same value as gSpread, not an option-adjusted spread. It stops short of describing auth requirements or error behavior, so it is strong but not complete.

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 front-loaded with the core purpose and then packs in high-value operational details. It is dense and semicolon-heavy, but every sentence contributes something useful for calling or interpreting the tool.

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 annotations and existing output schema reduce the burden, and the description covers billing, pagination caps, and key output-field conventions. However, for a complex screening tool with a large undocumented filter object, the description leaves important filter semantics and sibling-tool selection guidance unaddressed.

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%, and the tool has a large nested filter surface. The description adds useful units for yield and spread interpretation (YTM in percent S.A., spreads in basis points, EUR spread exception over Bund) and restates the page-size cap, but it does not explain most filter parameters such as ratingMin/Max, hideStaleBonds, includeMatured, duration bounds, or outstanding balance filters.

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 gives a specific verb and resource: search and screen bonds by free text and REST-compatible filters, with optional facets. It is clear on its face, but it does not explicitly distinguish itself from sibling tools such as bondterminal_get_bonds or bondterminal_request_bond.

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?

Usage is implied by 'search and screen bonds by free text and REST-compatible filters,' and the optional facets flag is noted. However, there is no explicit when-to-use versus alternatives guidance, no exclusion conditions, and no routing to get_bonds for direct identifier lookup.

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