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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: billing at 1 calculation unit per bond, a 50-bond per call limit, OAS model assumptions when a curve exists, and the annual-basis EUR spread convention. It omits auth requirements and settlement-date defaulting, keeping it short of a 5.

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?

Dense but nearly every clause carries load: conventions, limits, billing, and the EUR carve-out are all decision-relevant. The opening sentence about OAS output is slightly redundant given an output schema exists, and the action statement ('Run what-if bond analytics...') would be stronger front-loaded, but nothing is padding.

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 calculation tool with an output schema and full annotations, the description covers conventions, cardinality limits, cost, and the one-of-four input rule. The only material omission is the settlement date parameter's behavior, including what happens when it is omitted.

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?

Despite low schema description coverage, the description supplies the semantics that matter: YTM is percent S.A. for every bond, spreads are basis points on the same basis with a documented EUR exception, and prices are per 100 face. The mutually-exclusive 'exactly one input' constraint is stated here and nowhere in the schema. The settlement parameter is left unexplained, which is the main gap.

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 specific verb and resource: run what-if bond analytics computing yield or price from one of four supplied inputs per bond. This is clearly distinct from the sibling retrieval tools (search_bonds, get_history, treasury_curve) which fetch rather than calculate. An agent can pick this tool without inspecting the schema.

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 gives the key selection rule: supply exactly one of price, YTM, G-spread, or Z-spread per bond. It also sets the 50-bond cap and explains the EUR/Bund spread basis exception. It does not explicitly name when to prefer a sibling retrieval tool, but the calculate-vs-fetch split is unambiguous.

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