price_yoy_inflation_cap_floor

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

No annotations are supplied, so the description carries the full behavioral burden. It does disclose useful behavior beyond the schema: the vol spec 'the tool adds with the preset's conventions', the conditional role of cap_rate vs floor_rate, and the data-provenance contract. But it says nothing about compute cost, error behavior, or mutation/state effects, leaving real gaps for a pricing tool with zero annotation coverage.

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?

Front-loaded with purpose, then the two param-critical notes, then the provenance contract. Efficient prose overall, though the market_data_source paragraph is long and could be tightened by listing the four enum values against their meanings more compactly.

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?

With an output schema present, the description does not need to explain return values. It supplies the crucial inputs and the invocation constraint for this 23-parameter tool, leaving only the obvious scalar fields implicit.

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 largely does for the non-obvious parameters: it documents fixings (required, format per price_yoy_inflation_swap), the vol object shape and enum values, the surface-id alternative, and the cap_rate/floor_rate conditioning. The many self-explanatory params (notional, spread, gearing, dates, curves) are left to their names, which is acceptable.

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?

Opens with a specific verb (Price), a specific resource (year-on-year inflation cap / floor / collar), and the underlying endpoint. It also distinguishes itself from the sibling price_yoy_inflation_swap by naming the instrument difference and referencing the sibling for the shared fixings format.

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?

Gives a clear exclusion ('If you would have to invent numbers, do not call this tool: ask the user') and detailed provenance guidance for market_data_source, including when engine_example is allowed ('only when the user explicitly asked to run an example'). It does not, however, explicitly route between this tool and price_cap_floor or price_yoy_inflation_swap, so the alternatives comparison is only partial.

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