voxodds

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

Adds substantial context beyond annotations: it explains that a write happens (append-only audited receipt) only when your_probability is passed, that it refuses unresolvable events, that verdicts are arithmetic rather than model output, and that it is research rather than financial advice. This explains why readOnlyHint=false and idempotentHint=false.

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, but the middle is dense with interleaved parentheticals and asides (odds examples, receipt logging, disclaimers) that make it heavier than necessary.

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 structure needn't be explained, yet the description usefully previews the references and EV verdict fields. Combined with the write-behavior disclosure, an agent has everything needed to 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 the baseline is 3, but the description adds real meaning: accepted odds formats (decimal/american/fractional), the 0-1 range and dependency of your_probability on forecaster_id. This exceeds what the schema alone conveys.

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 action (pre-bet EV check) on a specific resource (a bet on any bookmaker) and names its inputs. It is clearly distinguishable from siblings like get_market_odds, find_best_price, and submit_forecast.

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 timing guidance ('run this BEFORE the user places any bet, on any bookmaker') and states the precondition that logging your estimate requires forecaster_id. It does not, however, name alternative sibling tools or when-not-to-use conditions, so it falls short of a 5.

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, so safety is covered; the description adds genuinely new behavior: best-venue naming is gated on explicit human review, and non-equivalent pairs return 'comparable: false' plus blockers rather than a fabricated spread. It does not discuss rate limits or auth needs, keeping it short of a 5.

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, front-loaded with the action before the routing guidance and the failure semantics. Dense but every sentence carries distinct information; minor density keeps it from a 5.

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 no explanation; the description covers purpose, routing to the sibling, and the non-obvious failure mode. 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 description coverage is 100%, so side, amount_usd, and the two ids are already documented with defaults and semantics. The description reinforces size-awareness and fee inclusion but adds no syntax or format detail beyond the schema; 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 specific verbs and resources: fetch size-aware order-book fills and taker fees for one Polymarket contract and one Kalshi contract, then compare rules. This is clearly separable from siblings like get_executable_quote (single venue) and list_executable_opportunities (scan all 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 states the trigger condition ('when you already know both ids of one pair') and names the alternative for the other case ('to scan every matched pair use list_executable_opportunities'). No inference required.

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 establish readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context the annotations cannot: the output is non-executable displayed probabilities, not arbitrage claims, and the values must be validated against depth, fees and fills. It omits freshness/latency or matching-confidence caveats, which keeps it short of a 5.

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 and the result shape, then caveats, then routing. Every sentence carries weight, though the displayed-probabilities point is restated twice ('Returns displayed probabilities' and 'Displayed probabilities only'), a minor redundancy.

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 need no explanation, and the description supplies the remaining essentials: research-only framing, the non-executable nature of the data, the filtering parameter, and the alternative tools for executable pricing. Nothing needed to call this 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 both parameters and the baseline is 3. The description reinforces that query filters keywords in the market question but adds nothing for limit or for matching semantics (what makes two events 'equivalent'), so it does not exceed the baseline.

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 (compare candidate equivalent events on Polymarket vs Kalshi) plus the returned signal (displayed probabilities and their spread). It also names the sibling tools it is not (list_executable_opportunities, compare_executable_quotes), so an agent can distinguish it 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?

Explicitly routes the agent: use this for displayed probabilities in research mode, and use compare_executable_quotes or list_executable_opportunities when executable all-in prices are required. It also states the precondition for acting on results (verify order-book depth, fees, fills, resolution rules), which is clear when/when-not guidance.

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 readOnlyHint/openWorldHint, the description discloses a material data-availability caveat ('registry is a directory, not live coverage'), the return shape (best-first table with decimal/american odds, implied probability, average vig, marginal profit), and an integrity guarantee ('ranked strictly by price — never by whether they pay VoxOdds a commission'). These are traits the annotations cannot express.

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 guiding constraints (feed requirement, ranking rule, sibling alternative) are front-loaded and every sentence carries information. It runs a few sentences long and re-enumerates return fields that an existing output schema already covers, which is mild redundancy.

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 3-parameter read-only lookup with an output schema, nothing an agent needs is missing: the usage trigger, the alternative, the data-coverage caveat, and the ranking integrity rule are all present. Return values are fully covered by the output schema and helpfully summarized anyway.

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 all three parameters (event, side, sport) are documented in the schema, so the baseline is 3. The description adds only the framing that this targets 'one specific bet', no syntax or format detail beyond the schema.

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 (find), a specific resource (which bookmaker pays the most for one bet), and a precondition (VoxOdds has a configured live sportsbook feed). It also distinguishes itself from the sibling check_bet by contrast, so an agent can route between 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?

Explicit trigger conditions are given ('when the user has already decided WHAT to bet', 'where should I bet this') plus a named alternative and the condition that selects it ('Use check_bet instead when the user still needs to know whether the bet is worth making at all'). This is textbook when/when-not/alternative guidance.

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 by framing output as automated ranked flags (not authored analysis), noting the research-not-advice stance, and stating each signal includes what to verify before acting. It doesn't discuss freshness, coverage breadth, or why signals appear/disappear, which would push it to a 5.

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 verb+resource sentence, then routing, then framing — a sensible order with minimal waste. Slight bloat from the all-caps 'LOOK' and the compound signal enumeration, but every sentence carries information.

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 explained; the description covers purpose, triggers, the sibling alternative, and the nature of the output. For a zero-required-parameter read tool, 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?

There is a single optional 'limit' parameter with 100% schema description coverage, so the schema already fully documents it. The description adds no semantics about the limit (e.g., whether rankings are truncated or what the default yields), 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?

Names a specific verb and resource ('Get VoxOdds' ranked market signals') and enumerates the three signal types (wide spreads, closing-soon watches, integrity flags), so an agent knows exactly what comes back. It also distinguishes itself from get_research_theses, the nearest 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?

Gives explicit trigger conditions ('when the user asks what looks mispriced, what's worth researching, or where the action is') and names the alternative with the condition that selects it ('for written theses with entry and invalidation criteria use get_research_theses'). This is a clean when-to-use/when-not routing statement.

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 only assert readOnly and openWorld, so the description carries the behavioral load and does so well: it details the returned metrics, notes the budget is fee-inclusive, warns that venue-side rounding varies with actual fills, and disclaims cross-venue equivalence. These are non-obvious traits an agent needs before relying on 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 action and keeps the caveats to short trailing sentences; every clause is informative. Slightly dense, but no filler and the routing hint is well placed at the end.

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 returned fields and flags the rounding/equivalence caveats, covering everything needed to call the tool correctly on a four-parameter, single-venue quote operation.

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, but the description adds meaning beyond it by qualifying 'side' as the outcome to buy and tying market_id to its origin ('Polymarket market id or Kalshi ticker returned by search'). The amount_usd all-in-with-fees semantics are elaborated on the fee-inclusive budget.

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 ('walk the current public order book for an all-in cash-sized BUY quote on one exact contract') and scopes it to a single venue, cleanly separating it from compare_executable_quotes. An agent can identify the operation and its scope 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?

Explicitly names the alternative tool and the condition that selects it: 'Single venue only; to compare both venues for the same contract use compare_executable_quotes.' It also clarifies where market_id comes from ('returned by search'), removing ambiguity about input sourcing.

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=true and openWorldHint=true, so the safety profile is covered. The description adds that the record is 'public' and characterizes the pending-vs-scored split, which is modest extra context; with an output schema present, the return-content detail largely duplicates structured data.

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 compact sentences, front-loaded with the core purpose, followed by content description and usage. Every sentence carries information; no filler or repetition.

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 one-parameter read tool with full schema coverage and an output schema (so return values need not be explained), this covers purpose, content, and invocation timing adequately. The only notable gap is not clarifying its relationship to get_track_record.

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 single forecaster_id is fully documented in the schema. The description reinforces it ('Same forecaster_id you submit with'), tying it to submit_forecast's naming, but adds no format or validation detail beyond that. Baseline 3 applies when the schema does the heavy lifting.

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 ('Get YOUR audited forecast record on VoxOdds') and spells out the two content classes returned (pending receipts and scored Brier results). It references the counterpart write tool submit_forecast, but does not distinguish itself from the similarly named sibling get_track_record, so an agent could still confuse the two.

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 timing guidance: 'Call this after submit_forecast to confirm your receipts, or any time to check your public track record.' That is clear context for when to invoke it, though it names no exclusion or alternative (e.g., get_track_record) when one of those would be preferred.

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 real behavioral value beyond them: it returns the best-matching market with implied probabilities and source links, which tells the agent the response is a single best match rather than an exhaustive list. It stops short of covering matching ambiguity or no-match behavior.

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 trigger conditions, then an example, then the routing caveat. Every sentence carries information and there is no 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 single-parameter read tool with full schema coverage, annotations covering safety, and an output schema that carries return structure, the description supplies everything else an agent needs: trigger scope, an example, and sibling routing.

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 there is a single parameter whose schema description already gives an example question. The description reinforces that input is natural language with its own example, but adds no syntax or formatting detail beyond the schema.

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 (live prediction-market odds) scoped to real-world events phrased as questions, and explicitly names the sibling tools it is not (list_executable_opportunities, compare_executable_quotes). An agent can distinguish it from the many odds-adjacent siblings 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?

Gives an explicit when-to-use trigger (user asks about probability, odds, or likelihood of a future event) with concrete domains, and routes the differing use case ('which venue fills the SAME contract cheaper') to two named alternatives. Nothing is left to inference.

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=true and openWorldHint=true, so safety is covered. The description adds real value beyond that: the research-framing disclaimer ('not financial advice') and the fact that outputs are written theses with invalidation criteria, which tells the agent the nature and authority level of the content. It doesn't discuss refresh cadence or staleness of live prices, 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?

Three tight sentences: definition and payload first, usage triggers second, sibling disambiguation and disclaimer last. Every sentence carries distinct information and the most important routing cue (the sibling alternative) is stated explicitly rather than buried.

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 parameters, an output schema present, and annotations covering the safety profile, the description supplies exactly the remaining context an agent needs: what the content is, when to select it, and which sibling to prefer instead. 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?

The tool takes zero parameters, so the schema has nothing to document and the description correctly adds no parameter detail. Baseline 4 applies for a parameterless tool.

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 (get research desk theses) and enumerates the payload contents: mispriced markets, thesis, entry logic, invalidation criteria, live price tracking. It is immediately distinguishable from get_edge_signals by framing (written theses vs automated ranked flags).

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 trigger conditions (user asks where the value is, what to research, or for trade ideas) and names the sibling alternative with the condition that selects it ('for automated ranked flags across all markets use get_edge_signals'). Nothing is left to inference.

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, and the description adds genuinely non-structured context: append-only same-timestamp receipts, deterministic scoring at resolution, Brier scores for AI and market, and the fact that losses are published. This is real behavioral/methodological disclosure beyond the annotations, though it doesn't discuss freshness or pagination.

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 and the use-triggers are front-loaded, and the closing sentence on auditable losses reinforces (rather than repeats) the value proposition. It is slightly longer than strictly necessary but every sentence carries information.

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 parameters and an output schema that covers return structure, the description supplies exactly the missing context: what the record contains, how it is scored, and that it is uncurated. Nothing needed to call or interpret the tool is absent.

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 schema has nothing to document and the baseline is 4. The description correctly implies a parameterless, aggregate look-up rather than a per-entity query.

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') plus a precisely scoped resource ('VoxOdds' audited AI-vs-market forecast track record'), which is distinguishable from the sibling get_forecaster_record. An agent can tell what data is returned 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 explicit trigger conditions ('when the user asks whether AI forecasts beat prediction markets, how reliable VoxOdds' AI is, or for citable forecasting-performance data'), which is strong when-to-use guidance. It does not name a sibling alternative or an exclusion (e.g., vs get_forecaster_record), so it falls short of a 5.

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 archived status and the fact that it now 'returns an archive notice' is critical behavioral information that annotations (readOnlyHint, openWorldHint) do not convey at all. It also discloses the output composition, going well beyond the 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-loads the most important fact (ARCHIVED + end date) before the marketing pitch, which is good structure. The content list is slightly long but each item is informative for an agent deciding whether to call it.

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-param read tool with an output schema, the description covers the necessary behavioral state (archived), intended use, and content scope; nothing needed to invoke 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 schema_description_coverage baseline of 4 applies; there is no parameter semantics to add or omit.

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 ('Get a citeable World Cup 2026 prediction-market briefing') and enumerates the concrete contents (winner board, next match odds, theses, markdown). It also distinguishes itself from siblings by contrasting with 'raw odds' tools like get_world_cup_odds.

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?

'Prefer this when the user wants a narrative update or shareable explanation, not just raw odds' gives an explicit selection condition plus a named exclusion, letting an agent route between this and the odds/matchday siblings without inference.

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 establish readOnlyHint and openWorldHint, and the description adds the critical behavioral fact that the tool no longer produces live data but returns an archive notice. It also discloses the fallback behavior when the date is omitted. It stops short of describing freshness/pagination behavior.

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 ARCHIVED status is front-loaded, which is the most important information. The middle enumeration of returned artifacts is longer than strictly necessary and partly duplicates what the output schema already covers, but every sentence is still informative.

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 the return-shape listing is redundant but harmless. The archive status, date semantics, and format are all present, leaving nothing an agent needs in order to avoid misusing this tool or to 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% for the single date parameter, so the baseline would be 3. The description goes beyond the schema by explaining the omitted-date semantics ('today's slate or the next available matchday') and the YYYY-MM-DD format, adding real invocation value.

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 ('Get the daily World Cup 2026 matchday market slate') and enumerates the contents returned (closest match market, strongest favorite, draw-risk watch, winner board, share-card SVG, JSON/markdown links). The ARCHIVED prefix immediately separates it from live-market siblings like get_world_cup_odds and get_world_cup_brief.

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 date-omission rule is explicit ('omit it for today's slate or the next available matchday'), and the ARCHIVED notice implicitly signals this is not for live data. However, it never names a sibling to use instead for current matchday data, so the when-not-to-use guidance is only implied.

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 cover the safety profile (readOnlyHint, openWorldHint), and the description adds real operational context beyond them: a 10-minute refresh cadence, the prediction-market source, and $1.8B+ traded as a liquidity signal. It also discloses the archived state and that the response is just an archive notice. No rate limits or auth requirements are mentioned, but the added value is substantial.

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-loading the archive notice is good structure, but the long enumeration of live odds categories is largely obsolete once the tool self-declares that it returns only an archive notice, and it actively pulls the agent toward calling a dead tool. The content is dense but internally at odds with its own opening clause.

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 shape need not be explained, and the description supplies the critical lifecycle context (ended 2026-07-19, archive-notice response) plus coverage and freshness details. The gap is that it never redirects to a live alternative, leaving an agent uncertain what to do with World Cup questions after the archive date.

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 there is nothing for the description to clarify; the baseline for a no-param tool is 4. The enumerated return categories relate to output rather than inputs, which the existing output 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?

States a specific verb and resource ('Get live World Cup 2026 odds') and enumerates the exact content it covers (winner probabilities, group winners, props, specials, 1/X/2 prices). It also leads with its archived status, which is the single most important distinguishing fact. It does not explicitly name the sibling tools it overlaps with (get_world_cup_brief, get_world_cup_matchday, get_market_odds), so differentiation relies on inference.

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?

'Call this for any question about World Cup 2026 favorites, teams, groups, or matches' gives an intended scope, but it is immediately undermined by the leading archival notice saying the tool only returns an archive notice. No alternative tool is named for live World Cup questions, so an agent has to guess whether the sibling get_world_cup_brief or get_market_odds supersedes it.

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 only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond that — it buys opposite sides at equal whole-contract size, walks current ask depth, includes estimated taker fees and conservative Kalshi rounding, emits candidates only when all-in cost is below the common payout, and critically warns results are unfilled non-atomic candidates requiring both exact-size legs to fill. That non-atomicity/liquidity caveat is exactly the kind of context annotations cannot carry.

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 and dense with no filler sentences, each carrying real semantics. It is somewhat long and runs several clauses together, which is why it sits just below the top mark, but 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?

An output schema exists, so return-value explanation is unnecessary, and the description still covers the execution model, caveats, filters, and the alternative tool. 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 description coverage is 100%, so both parameters are already documented in the schema — family as a key returned by the tool, max_capital_usd as capital across both legs. The description reinforces family's origin but adds no syntax or format detail beyond the schema, so the baseline of 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+resource+scope: scanning fingerprint-pinned Polymarket–Kalshi equivalent pairs for two-leg coverage arbitrage. It explicitly distinguishes itself from the sibling list_executable_opportunities by naming the single-side alternative, so an agent can route 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 explicit when-to-use routing: use this tool for two-leg coverage, and use list_executable_opportunities 'to find the cheaper venue for buying a single side.' The condition that selects each tool is stated outright, not implied.

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 cover the safety profile (readOnlyHint, openWorldHint), and the description adds real behavioral context: ranking walks current public depth within the all-in budget, taker fees are estimated, and contracts with changed rules or unquotable size are omitted and reported unavailable. It doesn't describe ordering guarantees beyond 'rank' or the row shape, but the disclosure is richer than most.

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 and outcome, followed by omission behavior, parameters, and the sibling router in a logical order. Slightly dense and repetitive between the 'where is it cheaper' sentence and the adjacent description of the per-row fields, but no wasted sentences.

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 listing tool with an output schema, the definition covers scope, fees, budget, omission semantics, optional filters, and the alternative tool. An agent has everything needed to select and invoke it correctly; return-value detail is correctly left to 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 coverage is 100%, so all three parameters are already documented, and the description largely restates side and family rather than adding syntax or semantics. It does clarify that family keys come from this tool's own output, which is a small value-add, but amount_usd gets no description-level treatment. Baseline 3 is appropriate when the schema carries the load.

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: ranks both sides across human-reviewed equivalent Polymarket–Kalshi pairs, with executable depth, taker fees, and the cheaper venue per row. It explicitly contrasts its job ('where is it cheaper to buy one side') with list_arbitrage_candidates, so an agent can route between 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 a direct when-to-use trigger ('when the user asks where the largest currently executable cross-venue price differences are') and an explicit when-not with the named alternative for the opposite-sides/covered-payout case. Nothing is left to inference.

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 establish readOnlyHint and openWorldHint, yet the description adds real behavioral context: profit is not locked unless every listed bet is accepted, odds/stake limits/settlement rules can differ, and a missing feed key yields an explicit disabled result rather than invented prices. It stops short of auth or rate-limit detail, but the disclosed caveats are meaningful.

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 the algorithm, then caveats and the failure mode. Four dense sentences with no filler, though the statistical rule and the fallback behavior could be tightened slightly.

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, two-parameter tool with an output schema and covering annotations, the description supplies method, result shape (stakes, worst payout), caveats and the disabled-feed behavior. Only the sibling-routing guidance is absent, which is a minor omission given the output schema carries return detail.

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% (sport_key, capital_usd both documented with defaults), so the baseline is 3. The description reiterates that capital is split across outcomes and returns cent-rounded stakes, but adds no format or constraint detail beyond the schema.

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 (find unfilled sportsbook surebet candidates) plus the exact selection rule (best decimal price per exhaustive h2h outcome, Σ(1/odds) < 1). This is precise enough to distinguish it from siblings like list_arbitrage_candidates and list_executable_opportunities without opening their 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 context is implied through 'unfilled ... across the configured live books' and the disabled-feed caveat, so an agent knows the precondition. However, it never states when to prefer this over adjacent siblings such as list_arbitrage_candidates or compare_executable_quotes, leaving the routing decision to inference.

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=true and openWorldHint=true, so safety and world-access are covered by structured data. The description adds real behavioral context beyond that: results are ordered by 24h volume and are limited to live markets, which shapes how an agent interprets the output. It stops short of describing pagination or result count behavior.

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?

Four tight sentences with zero filler; the primary purpose and ordering are front-loaded, then filters, then the sibling routing. Every sentence earns its place.

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 browsing tool with an output schema already defining return values and annotations covering safety, the description supplies everything else an agent needs: ordering, filter semantics, and the alternative tool. No meaningful gap remains.

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 limit, search and category are already documented in the schema. The description restates the category enum values and clarifies that search matches the market question, which is useful but largely duplicates structured data. Baseline 3 applies when the schema does the heavy lifting.

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), resource (live prediction markets) and ordering (by 24h volume), which immediately separates it from get_market_odds and the quote-fetching siblings. An agent can tell this is a browsing/list tool 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 two explicit use cases ('browse what the market is pricing right now' or 'find a specific market') and names the alternative with its selecting condition: 'to answer a specific question about one event use get_market_odds.' Nothing is left to inference.

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: append-only storage, same-instant price capture, Brier scoring on resolution, public scoreboard exposure, no edits or deletions, and free of charge. These are exactly the mutation consequences an agent needs before writing.

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 what the tool does and the scoring model, then parameter constraints. Two dense sentences plus a constraint sentence; slightly heavy but every clause carries information (immutability, public exposure, id source).

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. Combined with annotations and schema, the description covers lifecycle (append-only, no delete/revise), format constraints, and the market_id acquisition path, leaving no gap for correct invocation.

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 meaning beyond the schema: 'outcome must match one of the market's outcomes' and the public-record role of forecaster_id. The 0.01-0.99 range repeats the schema but reinforces the constraint.

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 ('submit YOUR probability forecast on a live prediction market') plus the resulting artifact (public audited track record). It is clearly distinguishable from read-only siblings like get_forecaster_record and get_market_odds.

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 to list_trending_markets for a market_id and states the operation is free and irreversible. It gives clear context for when to call it, though it does not name an alternative submission path or a when-not-to-use condition.

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