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

Annotations already declare readOnlyHint, idempotentHint and closed-world, and the description reinforces this with 'a pure calculation with no network calls'. It goes beyond annotations by stating the modeling assumptions behind the check (full fills at quoted prices, correctly specified relation), which is genuinely useful context an agent cannot get elsewhere. It does not, however, discuss failure modes or edge handling such as missing quotes beyond noting they are returned.

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 core purpose and the sibling routing in the first two sentences, which is exactly the ordering an agent needs. The return-value enumeration is somewhat long given an output schema exists, but it is not padded with filler.

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 need not enumerate return values, yet it briefly does while also covering prerequisites, the offline constraint, the sibling alternative, and modeling assumptions. Nothing an agent needs to invoke it correctly is missing.

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 100%, including enum semantics for relation and detailed QuoteInput field docs, so the schema carries the parameter burden; baseline 3 applies. The prose adds no parameter syntax or format guidance beyond what the schema already provides.

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 verb and resource ('check offline whether prices you supply violate a no-arbitrage relation') plus a secondary capability ('price the cheapest exploiting basket after fees'). It explicitly contrasts itself with the sibling check_constraint_live, so an agent can distinguish them without opening either 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?

Gives an explicit when-to-use rule ('hypothetical or historical prices') and names the alternative plus the condition that selects it ('use check_constraint_live to fetch current quotes instead'). The same sentence also clarifies the offline/no-network constraint that bounds usage.

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

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

Annotations declare readOnlyHint and openWorldHint; the description reinforces this by stating it calls public APIs and places no orders, and it discloses the return payload (violated, profitable_after_fees, best basket, quotes used). It does not discuss rate limits or failure modes, but it adds solid behavioral context.

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-loads the action, then the workflow, then the return/simulation note. Slightly verbose, but every sentence carries routing or behavioral information rather than filler.

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 annotations covering safety and an output schema covering returns, the description still adds the call-order workflow and simulation next step. Nothing an agent needs to invoke it correctly is missing.

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% and the enums/field descriptions are thorough; the description reinforces the ordering requirement (two for implication, every outcome for exclusivity) which the schema also states. Baseline 3 is appropriate since the schema carries the parameter detail.

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 specific verbs and resources: fetches live quotes/fee schedules and checks a no-arbitrage relation after fees. It is clearly distinguished from the sibling check_constraint (static) by the 'live' framing and by naming the surrounding workflow tools.

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?

Explicitly routes the agent: find related contracts with search_markets, confirm with get_market, then call this, and use paper_order to simulate each leg of the best basket. This covers when to use it and the prerequisites/alternatives.

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

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

Annotations already declare readOnly, idempotent and non-open-world, so the safety profile is covered. The description goes beyond them by disclosing that it is a pure computation with no network calls, that the default lambda is a pooled/illustrative estimate with a cited source, and what the return payload contains.

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 core purpose, then the formula, then usage, then the caveat and return fields. The formula and provenance sentence are justified, though the description runs a touch long for a two-parameter pure calculation.

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 stateless two-parameter calculation with an output schema present, the description covers purpose, usage context, the key parameter's provenance caveat, and the returned fields. Nothing an agent needs to invoke it correctly is missing.

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 baseline would be 3. The description adds provenance and interpretation for lam (pooled real-money/play-money estimate from Yang 2026, to be treated as illustrative) that the schema does not carry, and frames market_price as the quoted price being de-biased.

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 verb and transformation: 'Convert a market price into the probability it implies under the Wang transform,' plus the accompanying premium. The math (solving p_mkt = Phi(Phi^-1(p) + lam)) and the pure-calculation framing distinguish it immediately from live-data siblings like get_quote and get_orderbook.

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 clear when-to-use guidance: strip the favourite-longshot premium from a quoted price before comparing it with your own forecast. It stops short of explicitly naming alternative tools or stating when not to use it, so it is strong context rather than a full routing rule.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds value beyond that: it discloses the no-API-key/public-data auth posture, the venue-dependent payload shapes (Kalshi rules fields vs Polymarket outcomes/token ids/neg-risk/fees), and a workflow caveat about trusting relations. It does not cover rate limits or error behavior, but for a single-item read that is a minor gap.

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 core purpose, then venue-specific detail, then exclusions and alternatives. Every sentence carries distinct information; nothing is redundant padding.

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?

Output schema exists, so return values need not be explained, yet the description still surfaces the venue-dependent keys an agent must reason about. Combined with the routing guidance and auth note, an agent has everything needed to select and call it correctly.

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 both parameters are already documented, making 3 the baseline. The description goes further by explaining what the venue choice actually changes in the response (Kalshi vs Polymarket result shapes), which is meaning the enum label alone does not convey.

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 verb (get) and resource (one market's details) and enumerates the returned fields: title, best bid/ask, volume, closing date. It further differentiates behavior by venue, so an agent can distinguish it from get_quote, get_orderbook and search_markets without opening 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?

Explicitly routes the agent: get_quote for prices plus fee terms, get_orderbook for depth, and check_constraint_live for relations with the prerequisite that rules must be read first. When-to-use and when-to-use-something-else are both stated.

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

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

Annotations declare readOnlyHint and openWorldHint, but the description adds behavior the annotations cannot convey: Kalshi publishes bids only so asks are derived from the other side's bids (with the 1 - p formula), plus 'public data, no API key' authentication context and price/size units. This is substantive domain-specific 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?

Three tight sentences, front-loaded with purpose and output format, then usage routing, then pricing/data-source caveats. Every sentence adds distinct information with no padding.

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, return values need not be re-explained, and the description still supplies the venue-specific quoting quirk, units, and auth status. An agent has everything needed to call and interpret this correctly.

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 unit semantics the schema omits: prices are dollars per contract and sizes are contracts, and level ordering is best-first. It does not restate the depth range or venue enum, which the schema already covers.

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 first sentence names a specific verb and resource ('Get the displayed order book for YES and NO') and specifies the output shape ('[price, size] levels, best first'), which immediately separates it from siblings like get_quote and get_market.

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?

It states the concrete use case ('see how much of a basket can fill near the quoted price before paper_order') and names the alternative with its selecting condition ('use get_quote when only the top of book matters'). The when-to-use and when-not-to-use are both explicit.

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

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

Annotations give readOnlyHint and openWorldHint, and the description adds real behavioral context beyond them: a missing ask is derived from the opposite side's bid, and the data is public with no API key required. It stops short of describing latency, rate limits, or staleness of the quote.

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-loads the core purpose, then usage, then behavioral caveat, then return shape. Mostly tight, but the explicit enumeration of returned fields is partly redundant since an output schema exists.

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 two-parameter read tool with full schema coverage, annotations, and an output schema, the description covers purpose, routing, and derivation behavior adequately. The redundant return-field listing is harmless but unnecessary given the output schema.

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 100% and both parameters (venue enum, market_id formats) are fully documented in the schema, so the description owes little. It implies dollar-denominated output but adds no parameter-level meaning beyond the schema, matching the baseline of 3.

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?

Names a specific verb and resource (get quote), states exactly what is returned (best bid/ask on YES and NO in dollars plus fee schedule) and scopes it to two named venues. An agent can distinguish it from get_orderbook or get_market without opening either 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?

Explicitly routes usage: use it to gather prices for check_constraint or to read fee terms consumed by trading_fee, and states the exclusion that check_constraint_live fetches quotes itself so this call is unnecessary beforehand. When/when-not and alternatives are both covered.

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

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

The description adds real behavioral context beyond the annotations: it reads ~/.oracle3/relations.json and makes no network calls, and notes the list is empty if nothing has been saved. readOnlyHint and openWorldHint=false already cover the safety/offline profile, but the concrete file path is useful added detail.

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 core action, then file/read behavior, then routing guidance, then return summary. Every sentence carries information, though the return-details run slightly long given an output schema exists.

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 a full output schema present and 100% parameter coverage, the description need only establish purpose, usage and environment. It does all three, including the offline/local-file nature and the empty-result case, so an agent can call it correctly.

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 100%, so the schema already documents the status, market_id and spread_type filters including their empty-value semantics. The description only restates that results are optionally filtered and adds no filter syntax or format detail, so the baseline 3 applies.

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 verb (List) and resource (market relations) plus the precise scope (saved on this machine by the oracle3 research CLI, optionally filtered). It explicitly names the sibling list_relation_types as the tool for the different concept of abstract relation kinds, so an agent can separate them without opening 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?

Gives explicit when-to-use (reuse pairs already discovered or validated offline) and what to do next (pass a pair to check_constraint_live). It also cleanly routes to an alternative for the abstract relation kinds via list_relation_types.

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

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

Adds real context beyond the annotations by declaring it is 'static reference data with no network or file access' and giving a concrete example of the semantics ('implication: P(A) <= P(B)'). It also previews the return shape, though it does not need to elaborate further given the readOnly/idempotent/closed-world annotations already fix the safety profile.

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 short sentences, front-loaded with what the tool returns, then usage, then the sibling disambiguation. Each sentence earns its place and nothing is padded.

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, yet the description still summarizes the shape ({relations: {name: bound}}) and supplies the domain semantics an agent needs to pick a relation argument. Nothing needed to invoke it correctly is missing.

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?

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter guidance because none is needed.

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 verb and resource: 'List the relation types the constraint checks support and the probability bound each enforces.' It is immediately distinguishable from the sibling list_relations, which is called out separately for concrete market pairs.

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?

Explicitly says to use it 'to choose the relation argument of check_constraint or check_constraint_live' and names the alternative (list_relations) with the condition that selects it ('to see concrete market pairs saved on this machine'). When and when-not are both covered.

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

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

Goes well beyond the annotations: discloses the ledger file path (~/.oracle3/mcp_paper_ledger.json or ORACLE3_MCP_LEDGER), per-level fee charging, held-at-cost positions, buy-only limitation, and the rejection case when paper cash is short. This is unusually rich behavioral disclosure for a mutation tool.

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-loads the core purpose, then mechanics, then return values. Three compact sentences with little waste, though the return-value enumeration partly duplicates the output schema.

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 simulated-order tool with 5 required params, an output schema, and safety annotations, everything an agent needs is present: scope, side effects, file location, fill logic, and status outcomes. Nothing material is missing.

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 baseline is 3, but the description adds real semantics: the fill walks displayed asks from best price up to limit_price and charges the venue fee per level, which clarifies how limit_price and contracts actually interact with the book.

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 precise verb+resource: simulates buying YES/NO contracts in a local paper ledger, filled against the live order book with fees. The opening line and the 'never sends an order to a venue' clause cleanly separate it from any real trading sibling.

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?

Explicitly says to use it to test the legs of a basket found by check_constraint_live, and states the constraint that only buys are supported. It lacks an explicit 'when not to use' or a named alternative for real orders, but context is clear.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses the backing file and env override, that there are no network calls, the $10,000 starting cash, and two important accounting caveats: positions are carried at cost and there is no mark-to-market or resolution tracking. These are exactly the behavioral traits an agent could not infer from structured fields.

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 purpose, then source semantics, then usage, then caveats. Most sentences earn their place, though the final return-field enumeration partially duplicates the output schema and could be trimmed.

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 zero-parameter local read tool with an output schema and safety annotations already present, the description supplies everything else an agent needs: data source, absence of network calls, and the accounting semantics that make the numbers interpretable.

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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies a parameterless call and adds no misleading argument guidance.

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 verb (show) and resource (local paper ledger) and enumerates the contents (cash, open positions, fill count). It is clearly distinguishable from siblings like paper_order, paper_reset, and the market-data tools, since it is the read-side of the paper trading pair.

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?

Explicitly says 'Use it after paper_order to confirm fills and remaining cash,' naming the sibling and the triggering condition. It lacks an explicit when-not statement or mention of paper_reset, but the affirmative guidance is unambiguous.

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

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

Goes well beyond the annotations by disclosing what gets destroyed (all paper positions and fill history), what is NOT affected (no venue contacted, real accounts untouched), and the exact no-op behavior and return status (not_reset) when confirm is false. This is exactly the destructive-operation context an agent needs.

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 short, front-loaded sentences: the destructive action first, then the safety scope, then the confirm gate. No sentence 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 single-parameter destructive tool with annotations and an output schema, the description covers purpose, scope, safety, and gating behavior completely. Nothing needed to call it correctly is missing.

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 already 100%, so baseline is 3; the description adds value by explaining the consequence of the parameter's default state (returns not_reset and changes nothing without confirm=true), which is more than the schema's terse 'otherwise nothing changes'.

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 verb+resource ('Erase the local paper ledger and restore the $10,000 starting cash') and scopes it to the local paper ledger, distinguishing it from sibling tools like paper_portfolio and paper_order. The agent can identify exactly what the tool does without opening the 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?

Gives a clear use case ('start a fresh paper-trading session') and the gate condition for action (confirm=true). It does not explicitly contrast with alternatives such as paper_portfolio, but the reset-vs-read distinction is obvious from the sibling names and the description.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds meaningful context beyond them: no account or API key is required because it reads public APIs, and Kalshi keyword search scans up to 1,000 open events. It omits rate limits and pagination behavior, so it is strong but not complete.

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 tight sentences, front-loaded with purpose then routing then behavior. The final sentence enumerating return fields is partially redundant with the output schema, which slightly blunts conciseness, but nothing is padded.

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 read-only, public-API search with an output schema and readOnly/openWorld annotations already present, the description covers purpose, sibling routing, auth requirements, and result contents. Nothing an agent needs to call it correctly is missing.

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 100%, so the schema already documents limit, query, venue and series_ticker including the Kalshi-only semantics. The description only echoes the Kalshi keyword-scan behavior, adding little parameter meaning beyond the structured fields; baseline 3 applies.

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 states a specific verb and resource ('Search open Kalshi or Polymarket markets') and names the return shape ('candidates with their best prices'), which cleanly separates it from quote/orderbook/market-detail siblings. An agent can identify the tool's role without opening the 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?

It explicitly positions itself as the entry point ('Start here to find market ids') and routes to alternatives by need: get_quote/get_orderbook for live prices, get_market for resolution details. The when-to-use and which-sibling-to-pick guidance is fully spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, but the description adds substantive behavior beyond them: the actual fee formulas per venue, the round_up rounding on Kalshi taker fills, that maker fills are free on Polymarket, and the default rate of 0.07. These are the details that determine what output an agent gets, which annotations cannot convey.

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?

Purpose is front-loaded in the first clause, followed by formulas and then routing guidance in a logical order. The two-venue formula sentence is dense but earns its length by making the calculation unambiguous; nothing is pure filler.

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 deterministic 7-parameter calculation tool, the description supplies purpose, formulas, input provenance and sibling routing, and an output schema exists so return values need not be enumerated (though fee, fee_per_contract, order_type and schedule are listed anyway). Nothing needed to invoke it correctly is missing.

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 would be 3, but the description adds cross-tool provenance for the non-obvious parameters (polymarket_rate, kalshi_maker_fees, kalshi_multiplier all come from get_quote's fee terms) and maps the formula symbols M/C/P onto the inputs. It stops short of explaining edge behavior for the new anyOf rate parameter beyond the documented default.

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 opening clause names a specific verb and resource ('Compute the venue fee for one fill') and immediately scopes it as a pure calculation with no network calls. It also distinguishes itself from siblings by naming check_constraint as the basket-level alternative, so an agent can route correctly without reading either 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?

It states exactly when to use it ('price a single leg or a hypothetical fill') and where to obtain its inputs ('take a live market's fee terms from get_quote'). The explicit handoff to check_constraint for whole-basket pricing covers the alternative path rather than leaving it to inference.

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