price_zc_inflation_swap

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

With no annotations, the description carries the behavioral burden and does so fairly well: it states the market must carry the inflation index plus a ZeroInflation curve, that fixings are mandatory because the server has no market-data source, and that the tool mutates the index and reports this in notes. It omits error/failure behavior and any auth or rate-limit context, but for a stateless pricing call this is solid disclosure.

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 purpose is front-loaded and the remainder is organized as a tight Args block with no filler. A few lines are dense but every sentence contributes actionable detail rather than restating the name.

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 values needn't be described, and the description covers the genuinely tricky provenance/required-fixings logic well. Yet for an 18-parameter tool the unexplained required curve params (discounting_curve, inflation_curve) and trade-shaping params leave the agent partially unequipped to construct a valid call.

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 does for the high-risk params: market_data_source's four enum values are spelled out, and the fixings shape/semantics are given as an example. However, two REQUIRED params (discounting_curve, inflation_curve) receive no explanation at all, along with market, additional_trades, calendar_overrides, include_flows, and request_id, leaving substantial gaps.

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 opens with a specific verb+resource ('Price a zero-coupon inflation swap') and even gives the backing endpoint. The 'zero-coupon' qualifier cleanly separates it from sibling tools like price_yoy_inflation_swap without the agent needing to open a 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?

The market_data_source paragraph gives explicit when/when-not guidance, including the strong exclusion: 'If you would have to invent numbers, do not call this tool: ask the user for the data.' It also flags fixings as REQUIRED and explains why. It stops short of routing to named alternatives (e.g. the YoY or multi-trade siblings).

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