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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so 'Nothing is executed or stored' largely restates them. The description does add real behavioral context beyond the annotations: the data source is five-minute ticks either side of the trade with an archive starting 27 Oct 2026, prices are re-derived after network fees, and the shortfall is measured at the least-favourable reading — all of which materially affect interpretation of results.

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 the question that defines the tool, then inputs, then method, then returns — a logical order with no filler sentences. A few clauses are dense ('at the reading least favourable to that') and could be tightened, but nothing is redundant.

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 no output schema, the description must carry the return contract, and it does: best venue, shortfall in basis points, and the venue-choice vs fill breakdown when venue is supplied. The remaining ambiguity is the exact shape/units of the returned object, which is a minor gap for a read-only analytical tool whose parameters are fully documented.

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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: accepted time formats in context, that venue is optional and changes the shape of the answer (gap decomposition), and that amounts are 'amount sold'/'amount received' as reported from the actual fill rather than quoted figures.

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 names a specific verb and resource — re-pricing an executed trade across every Canton venue at the time it ran — and states the exact inputs that define it (token sold/bought, amounts, time, optional venue). It also distinguishes itself from the sibling quote() by saying it runs 'by the same code as quote()' but on historical ticks, so an agent can tell the two apart without opening the schemas.

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?

Usage is clear from the opening question 'Was a trade well executed?' — this is a post-trade execution-quality check, not a pre-trade price lookup. It also explains what the optional venue parameter buys you (decomposing the gap into venue choice vs fill). It does not explicitly say when not to use it (e.g. for a live quote, use quote()), so it stops short of full alternative routing.

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