fair_rate

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 non-obvious behavior: results are passed through from the engine, nothing is solved locally, and when the response lacks fair_rate/fair_spread the provided_by_engine flag is false with an explanatory message. It does not spell out read-only status, required engine/session prerequisites, or any rate/permission constraints.

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 core purpose is front-loaded in the first sentence, followed by Args and Result sections that are easy to scan. The market_data_source enumeration is verbose but each entry carries decision-relevant meaning, so little is wasted.

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 6-parameter tool with nested objects and an output schema, the description covers the one parameter the schema leaves opaque (market_data_source) and the pass-through/failure behavior an agent would otherwise guess wrong. The remaining gap is that trade/market/as_of semantics are delegated to swap_dv01 rather than restated. Since an output schema exists, not describing return fields is acceptable.

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?

Top-level schema coverage is 0%, so the description must compensate. It explains market_data_source thoroughly (all four provenances plus what has no valid value), but market, trade, and as_of are dismissed with 'as in swap_dv01', deferring to another tool rather than adding semantics here. The nested SwapSpec $defs do carry some documentation, so coverage is partial rather than absent.

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?

States a specific resource and action: the fair (par) rate of a swap, read from the engine's pricing response. It also cross-references swap_dv01 for the argument shape, which orients the agent within the family. It stops short of distinguishing when fair_rate is preferred over the sibling pricers (price_vanilla_swap, price_ois_swap), so it is clear but not fully differentiated.

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 enumeration effectively encodes when-to-use conditions (user_pasted / user_file / engine_example / session), and the explicit exclusion 'If you would have to invent numbers, do not call this tool: ask the user for the data' is a clear when-not-to-use rule. No alternative sibling tool is named as a substitute, so it falls short of an explicit routing statement.

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