quote_cost

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds meaningful behavior beyond that: it walks the order book (mechanism), returns average fill price/slippage/notional/levels consumed (output contract), and conditions the fee-schedule portion on venue publication ('where it publishes one'). Nothing contradicts the annotations.

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?

Three sentences, each earning its place: purpose contrast, return contract, and usage timing. The core differentiator is front-loaded in the first clause, and there is no filler or repetition of what the schema already shows.

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 compensates by enumerating return values (average fill price, slippage, notional, levels consumed, conditional fee schedule), and the annotations carry the safety profile. Remaining gaps — what happens when size exceeds book depth and exact parameter value formats — are not disclosed, though they are partially inferable from sibling tools like get_market and get_orderbook.

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 four parameters carry only names and types. The description partially compensates: 'size' is clarified as the hypothetical order size, and 'both legs before acting on a cross-venue gap' implies venue/market_id identify each leg. However, it never specifies side values (buy/sell) or the expected formats of venue/market_id, leaving the compensation incomplete.

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 lead clause 'What a given size would ACTUALLY cost, by walking the order book rather than reading the top level' names a specific verb (estimate true cost), a resource (order book depth), and an execution method. The explicit 'rather than reading the top level' contrast differentiates it from siblings like get_orderbook or watch_book, so an agent can tell it apart without opening any 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?

Two explicit directives are given: 'Call this before sizing any trade, and on both legs before acting on a cross-venue gap.' This is clear, concrete when-to-use context tied to real workflows. It stops short of naming the specific alternative tool for top-level reads or stating a when-not condition, so it earns a 4 rather than a 5.

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