price_fixed_rate_bond

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: default effective_date = issue_date, the 'spot' resolution for issue_date, engine-resolved tenor, and the data-provenance policy. It omits error/side-effect behavior, but the compute-only nature and rich defaults make this solidly above average.

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?

Purpose is front-loaded, then a compact Args list where nearly every line carries semantic value (formats, defaults, constraints). It is dense rather than padded, though the market_data_source paragraph is long relative to the rest.

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 an 18-parameter tool with nested objects and an existing output schema (so returns need not be explained), the description covers the critical inputs and even summarizes summary.bonds. Remaining gaps (as_of, additional_trades, calendar_overrides semantics) are minor but present.

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%, so the description must compensate, and it documents ~13 of 18 parameters (market_data_source, preset, face_amount>0, coupon_rate as annual decimal, date formats, discounting_curve, overrides, yield_overrides, include_* flags). It leaves as_of, top-level tenor, request_id, additional_trades, and calendar_overrides unexplained, and defers market format to price_vanilla_swap.

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 first line gives a precise verb+resource ("Price a fixed-rate bond") plus the backing endpoint, which cleanly separates it from siblings like price_floating_rate_bond or price_zero_coupon_bond. It never explicitly states what it is not, so it stops short of a 5.

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 market_data_source block supplies real when-to-use/when-not guidance, including the hard exclusion "If you would have to invent numbers, do not call this tool: ask the user for the data" and the restriction of engine_example to explicit user requests. It does not, however, help the agent choose between the many price_* siblings.

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