Arena Predictions

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

Annotations declare destructive/idempotent/openWorld, and the description adds real value beyond them: the collateral effect of cancelling (hold returned vs. position left untouched), idempotent behavior on already-filled/closed orders (reduced_by=0), and the venue-specific refusal behavior for live/poly_intl. This is the kind of preconditions and side-effect detail an agent needs to avoid a failed call.

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 then adds effect, edge case, and constraints in short sentences with no filler. Slightly telegraphic fragments ('confirm=true') but 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 mutation tool with an output schema and full annotation coverage, the description supplies exactly the missing behavioral context: side effects on holds/positions, idempotency edge case, and the paper-only venue restriction. Nothing an agent needs to call it correctly 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?

Schema coverage is 100%, so baseline is 3; the description goes further by spelling out the failure mode for live (Kalshi) and poly_intl (Polymarket International) rather than just their destinations, and reiterates the confirm=true requirement. The added meaning around venue flags and the refusal semantics exceeds what the schema fields alone 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?

'Withdraw a resting limit' states a specific verb and resource, and the following sentences describe the exact effect for buys (hold returned) and sells (position unchanged), so an agent understands the operation without ambiguity. It is clearly distinct from the ordering siblings like place_trade and sell_trade.

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 concrete usage constraints: confirm must be true, and live/poly_intl calls are refused on this paper-only server (live_not_hosted). It doesn't explicitly name place_trade/sell_trade as the inverse to reach for, but the conditions that gate correct invocation are all present.

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 readOnly/idempotent annotations: prices are after taker fees, the list is sorted arbitrage-first, label is only arbitrage under $1 on contracts that settle alike and at most 15s old, reasons explains downgrades, and it warns that nothing is risk-free. It also discloses the Polymarket US-persons restriction and that no sign-in is needed.

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?

Dense and front-loaded, with the return shape (list vs ref, arbitrage first) stated first and caveats last. Every clause carries information, though the telegraphic fragments and unexplained jargon ('label', 'reasons', 'legs') make it harder to parse than it needs to be.

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 raw return values need no explanation, yet the description still clarifies the semantics of key returned fields (edge, label, reasons). Combined with the us_only, ref and full behaviors, an agent has everything needed to call 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 already 86%, but the description adds real meaning: ref switches between the list and all pairs, us_only defaults true and forces Polymarket pairs to never be arbitrage, and full adds legs and caveats. It reinforces the size constraint via 'sized' but leaves limit/league/min_gap to 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 price gaps) and names the exact venues involved, then defines the core concept: a pair buys YES on one venue and NO on another with edge = 1 - cost per $1 contract. This is precise enough to distinguish it from the closest sibling, get_cross_venue_quotes, 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?

Clearly routes usage modes: omit ref for the list (arbitrage first), supply ref for all pairs of one instrument, and use full to add legs and caveats. It does not, however, name an alternative tool or state when to prefer a sibling like get_cross_venue_quotes, so it falls short of explicit 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 establish this is a safe, read-only, non-destructive call, so the bar is lower. The description does add useful non-obvious context — paper-dollar units, carry-over semantics, the DEPRECATED status of season_start_dollars — plus a directive to surface recently_settled to the person, which is a genuine behavioral instruction not derivable from annotations or schema.

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?

It is short and dense, but the structure is a semicolon-separated list of return fields rather than a front-loaded purpose-then-detail shape. The most important information (that this retrieves the account balance) is never stated at all, so brevity here reflects omission rather than economy.

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 description carrying the full burden of explaining return fields is partly redundant, yet its field notes and deprecation warning are still useful. What is missing is the framing sentence that tells the agent this is the balance-retrieval tool and when to call it; for a simple zero-parameter read that gap is survivable but real.

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 per the rubric the baseline is 4. There is nothing for the description to compensate for and no input contract that could be misinterpreted.

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 evokes the resource — the account balance in paper dollars — but never states a verb or a purpose sentence; it opens mid-thought with 'The account in paper dollars, carried over.' The tool is distinguishable from siblings like get_positions or get_orders by virtue of its name, but the prose itself reads as field documentation rather than a statement of what the tool does.

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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to any alternative sibling tool. The only quasi-instructional content is 'tell the person' about recently_settled, which is about presentation, not about when to invoke this tool versus another.

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 only safety (readOnly/idempotent/non-destructive), and the description layers on substantial operational context beyond them: freshness semantics (stale:true past a minute, rows up to 5 minutes old), Novig's feed-vs-polling variability, ProphetX sandbox caveat, and that paper trades are sandbox-only and never sent to the venues. This is exactly the extra behavioral detail the 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?

The purpose is front-loaded, but the body is a single dense run-on paragraph of semicolon-chained clauses that drifts into trade-routing and paper-trade behavior tangential to reading quotes. It is information-rich but poorly structured and not concise for the two-argument read it performs.

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 spelled out, and the description nonetheless covers venue coverage, data freshness, and source caveats well. The only real gap is the undocumented `full` parameter, so an agent can call this correctly but not tune its verbosity.

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 only 50%: `ref` is documented in the schema, but `full` has no description and the tool description never explains what it does. The description instead spends its detail on output fields (yes_pct, as_of, last_trade_at), so it does not compensate for the undocumented parameter.

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 states a specific verb-plus-resource and scope: one instrument's YES price across every venue Arena shows, explicitly naming Kalshi, Novig, Polymarket and ProphetX and noting it is not ranked by price. That is enough for an agent to separate it from siblings like get_instrument, get_market and find_price_gaps without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the reader infers this is the tool for cross-venue comparison, and the note 'When cross_venue is false only Kalshi is listed' gives one conditional. There is no explicit when-to-use/when-not guidance and no routing to sibling tools such as get_instrument or find_price_gaps.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds real context: no sign-in required, ranking is never by profit, scores carry 95% intervals, and tied_with_above explains that the sample does not separate a row from the one above. That tie/interval semantics is genuinely useful for interpreting results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence that leads with the resource and its ranking scope, with the tie clarification parenthetical placed immediately after. Dense but no filler; only minor friction from the jargon-heavy phrasing.

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 not be restated, and the description usefully pre-empts interpretation questions (ranking basis, ties, intervals, no auth needed). The main gap is that the optional filters and their defaults are left entirely to the 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 60% and the description contributes nothing about the five parameters (kind, limit, cohort, window, min_scored); it instead introduces terms like rank_basis that are not parameters of this call. It does not compensate for the partially documented 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?

Names a specific resource (the public eval board) and states exactly what is on it: people and AI models scored on settled public picks, ranked within rank_basis. It is clear this is a read-only ranking view, though it does not explicitly distinguish itself from siblings like get_leaderboard or get_track_record.

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?

No when-to-use guidance and no named alternative. The description tells the agent what the board contains but never says when to prefer it over get_leaderboard, get_track_record, or get_my_stats, leaving selection entirely 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 cover read-only, idempotent, and non-destructive semantics, so the bar is lower, and the description adds real value: 'No sign-in' discloses the auth requirement, and 'signed out, the moneylines only' warns that an unauthenticated call returns a reduced dataset. It doesn't mention rate limits or pagination, but the partial-data caveat is the important 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?

One dense sentence with the key identifier and the returned fields front-loaded; nothing is wasted. The parenthetical '(Kalshi's chance; signed out, the moneylines only)' is compact but reads awkwardly and blurs two distinct facts.

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 needn't document return values, and annotations carry the safety profile, so what remains — identity of the resource, auth behavior, and the unauthenticated data reduction — is largely covered. The undocumented full/market_type parameters are the only notable hole.

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 50%, so half the parameters (full, market_type) are undocumented in both places. The description does reinforce the ref/game semantics ('game_ id, slug or words') and hints at ordering with 'moneylines first,' but it never explains the boolean full flag or how market_type overrides the default moneyline-first behavior.

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 resource (one game, keyed by game_ id, slug, or team words) and enumerates the instrument fields returned, which clearly distinguishes it from the plural sibling list_games. The verb is implicit rather than stated ('One game ... with every instrument'), so it's clear but slightly elliptical.

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?

'No sign-in' tells the agent this call is available without authentication, which is genuine usage context. However, it never states when to pick this over list_games, get_market, or get_instrument, nor any conditions or exclusions — usage 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 already establish read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: newest-first ordering, the P&L/tally payload, and the edge case that a reset write-off surfaces as sold with close_reason account_reset. It stops short of describing pagination or how limit interacts with the result set.

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?

Two tight sentences with no filler: payload and ordering first, scoping second, the reset-write-off caveat last. Every clause carries information, though the instrument_id mention is wedged into an already dense list.

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 return values need no further explanation, and annotations cover the safety profile. For a zero-required-param history reader this is nearly complete; only pagination behavior and the semantics of full versus limit are left unstated.

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 71%, in the mid band where the schema does most of the work. The description names window, since, until and run as scoping options but adds no syntax, format or precedence rules beyond what the schema already states, and never mentions full, limit or the deprecated month.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and scope: 'Settled and sold trades, newest first, with realized P&L, instrument_id and a win/loss/void tally.' That is enough to separate it from get_perp_history (perp-specific), get_orders (working orders) and get_track_record (aggregate stats) without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Scope with window, since, until or run' gives filtering mechanics but no guidance on when to choose this over get_perp_history, get_orders or get_track_record. Usage is implied by the resource description rather than stated as a when-to-use 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds 'No sign-in', an authentication/access fact the annotations do not express, which is genuinely additive. It omits nothing critical for a single-record read.

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?

A single dense sentence that front-loads the identifier form, followed by a short access note. No wasted preamble. It runs slightly long by enumerating returned fields that the output schema already covers, but nothing is 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?

An output schema exists, so return values need not be spelled out (the description does so anyway). Annotations carry the safety profile. The remaining gap is the unexplained `full` parameter and the absence of sibling routing, leaving the definition adequate but not complete.

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 only 50%: `ref` is described in the schema and the description merely repeats it ('ins_... or slug'), while the boolean `full` parameter is documented nowhere. With incomplete coverage and no compensating explanation in the description, it falls below the baseline 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?

States a specific verb+resource: retrieve one instrument by ins_ id or slug, and enumerates what the record contains (YES semantics, tie rule, game, Kalshi ticker side mapping). That is more concrete than a bare 'look up a market', though it never explicitly contrasts itself with get_market or list_markets. An agent can infer scope but not the boundary against neighbours.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative (e.g. get_market vs get_instrument). The only contextual signal is 'No sign-in', which is an access note rather than a routing rule. 'One instrument' implies single-item lookup, but that is purpose, not usage 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 read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely new context: results are 'as of the daily snapshot' (freshness/caching) and require 'No sign-in' (no auth needed), plus the edge case that an empty people board falls back to the AI board. These go beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded ('Public leaderboards in paper dollars:') followed by rules, then two short supplementary sentences. It is dense and semicolon-heavy, which slightly taxes parsing, but no clause appears 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 shapes need not be described, and annotations plus the description cover auth, freshness, and edge cases. The one real gap is the `full` boolean, which is undocumented in both schema and description. Otherwise an agent has enough to invoke 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 75% and the schema descriptions are thin ('Default 30d.'), yet the description adds real meaning: the 30d/90d windows rank profit on trades closed in the window (5+ minimum) while 'all' ranks since Sep 1, 2026 (20+ closed trades), and kind defaults to people with an AI fallback. It leaves `full` and `limit` unexplained, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and scope: 'Public leaderboards in paper dollars' ranked by profit. 'Public' and 'No sign-in' implicitly distinguish it from account-scoped siblings like get_my_stats and get_track_record, and the ranking rules (trades closed, thresholds) make the resource concrete. It never names a sibling explicitly, so differentiation is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the resource name and the 'public / no sign-in' framing, but there is no explicit when-to-use or when-to-prefer-an-alternative statement. The description explains board semantics rather than telling the agent under what conditions to call this versus get_eval_board or get_track_record.

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/openWorld/non-destructive, so the bar is lower. The description still adds real behavioral context: it discloses the signed-out fallback ("an instrument's Kalshi price (signed_in: false)") and the side-effect-free enrichment triggered by contracts/stake_dollars (cost and payout), beyond what annotations provide.

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 is front-loaded, but the body is a long semicolon chain, and a large clause ("bid and ask in cents, yes_pct, no_pct, spread, status, close, game_state") enumerates return fields that the output schema already covers. Dense and readable but with redundant content and only moderate structure.

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 spelled out, and annotations carry the safety profile, so the description is nearly sufficient: it covers input resolution forms, quoting output, enrichment via contracts/stake_dollars, and the signed-out behavior. The main gap is the undocumented `full` parameter and absent 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 80%, so baseline is 3. The description adds meaning the schema lacks — that the reference can be "a bet in words," which is not documented in any parameter description, and that contracts/stake_dollars produce cost and payout outputs. It does not explain the `full` flag, leaving one parameter undocumented in both places.

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 opens with a specific verb+resource and scope: "Live quote for one market," which separates it from list_markets/search_markets (many markets) and get_orderbook (depth). It does not name or contrast any sibling explicitly, so an agent must infer how get_market relates to get_instrument or get_cross_venue_quotes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied — quoting a single market by ticker/id/slug/bet-in-words — and the accepted reference forms are useful context, but there is no explicit when-to-use, when-not, or "use X instead" guidance despite many overlapping siblings (get_instrument, list_markets, get_orderbook).

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context in the form of the default time window ('since Sep 1, 2026') and the fact that `by` triggers a breakdown, though most of the metric list is redundant with the output schema.

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 metric list, followed by the default window and the `by` behavior; there is little wasted text. The dense metric parenthetical is information-rich but slightly heavy for a single sentence.

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 explaining return values and annotations covering safety, the description is adequate for a read-only stats tool. It falls short on tool-selection context (why this over get_track_record) and does not clarify that it scopes to the caller's own account versus other traders.

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 high (86%), so the schema already documents most parameters, which sets the baseline at 3. The description adds marginal meaning by noting the default window and that `by` produces a breakdown, but gives no detail on the enum values (league/band/hold) or the deprecated `month` parameter.

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 ('grades') and resource ('your closed trades') and enumerates the metrics produced, so the agent knows exactly what it returns. It does not, however, distinguish itself from close siblings like get_track_record, get_leaderboard or get_trader, so the agent must infer the difference.

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?

There is no explicit statement of when to use this tool versus alternatives such as get_track_record or get_trader, and no prerequisites or exclusions are given. The only usage-ish note ('Default since Sep 1, 2026. by adds a breakdown.') concerns parameter behavior, not tool selection.

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, destructiveHint=false and idempotentHint=false, covering the safety profile. The description adds genuinely new behavioral context beyond that: the walk computation triggered by contracts and the note that paper fills take the whole size at one price. It remains silent on pagination, rate limits, or ref/ticker resolution order, so it is useful but not rich.

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 with no filler; the return format leads and the behavioral caveats follow. The trade-off is that the compressed, jargon-heavy style ('contracts adds walk') costs some readability, keeping it just below the top score.

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 value need not be re-explained, and annotations carry the safety profile. What is missing is usage context and how ref and ticker relate for identification, which the description leaves entirely to the schema. Adequate but with clear gaps.

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 all four parameters and the baseline is 3. The description does add meaning for contracts ('walk, that size's cost through the book'), but its phrasing is telegraphic and adds little for ref, depth, or ticker. No compensation is needed since the schema is complete.

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?

Specifies a concrete verb+resource (fetch order book depth) and even the exact return shape: '[price_cents, quantity] bid pairs per side plus best bid and ask'. That is more specific than a generic 'gets the book'. It stops short of naming or contrasting siblings like get_market or get_price_history, so it misses the top of the scale.

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?

There is no explicit when-to-use guidance and no named alternative among the many get_* siblings (get_market, get_price_history, get_cross_venue_quotes). Usage is only implied by the content of the return value. The contracts/walk note hints at a matching use case but never states when to reach for this tool.

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 destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: what 'resting' means operationally (live, holding money, able to fill) and that cancel_reason explains why an order ended, neither of which appears in the schema or annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single dense sentence (plus a short follow-up) with no filler, and the default-status semantics are front-loaded. The phrasing is a little compressed and reads awkwardly in places, but every clause 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, the description does not need to explain return values, and annotations cover the safety profile. It covers the key gotcha (resting = funds committed) and the cancel_reason field; only the limit/pagination behaviour is left implicit.

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 75%, so most params are documented, but the description still adds meaning: it clarifies the default status=resting and defines what that state implies, which the schema only notes tersely as 'Default resting.' It does not describe the limit param or the pagination behaviour, so it is not a full 5.

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 gives a specific verb+resource ('Your limit orders') and scopes it to an instrument, which is enough to separate it from sibling order tools like cancel_order or place_trade. It stops short of explicitly naming a sibling alternative, so it lands at 4 rather than 5.

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 gives a concrete usage trigger: 'check it before placing on the same market,' which tells an agent when this lookup is worth doing ahead of place_trade. There are no explicit when-not conditions or named alternatives, which keeps it out of 5 territory.

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 cover read-only/safe/idempotency, so the bar is lower, yet the description adds substantial context: result ordering, currency unit, and the currently-disabled server state with the exact not_available response and the clarification that it is not about the ticker. That failure-mode disclosure is exactly the kind of trait 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?

Four short sentences, each earning its place: purpose first, then parameter behavior, then the critical availability caveat. Front-loaded and free of 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, return values need no explanation, and the description covers what it returns, ordering, units, parameter behavior and the current disabled state. 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, since, until, source and ticker. The description mostly restates these (default 20, max 50, source values), adding only the mild framing that since/until 'bound the window'. Baseline 3 is appropriate 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 ('Recent stored snapshots for one Kalshi perpetual') plus scope, ordering ('newest first') and unit ('in dollars'). The perp-specific framing implicitly distinguishes it from get_history and get_price_history, but it never names those siblings, so differentiation is left to 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?

Gives concrete operating guidance: limit default/max, that since/until bound the window, and the source options. Crucially it warns that the tool is currently switched off and will answer not_available, telling the agent what to expect before calling. It stops short of saying when to prefer this over get_history or get_price_history.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the mark is 'live' (explaining the idempotentHint=false) and denominated in dollars, which is useful context, but it says nothing about update frequency, rate limits, or behavior when a ticker is unknown.

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?

Two short sentences, no filler, with the core meaning front-loaded and the input-source hint trailing. Every clause 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 single-parameter read tool with an output schema and full annotation coverage, the description supplies what/unit/input-source and leaves return formatting to the output schema. Only edge-case behavior (invalid or expired ticker) is unaddressed.

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 schema already supplies the KXBTCPERP example, so the baseline is 3. The description goes beyond the schema by telling the agent where valid ticker values originate (list_perps), which is actionable provenance the schema does not provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (the live settlement mark) for a specific instrument class (Kalshi perpetual ticker) and gives the unit (dollars), which distinguishes it from get_perp_history and list_perps. It stops short of explicitly contrasting itself with the history sibling, but the purpose is unmistakable.

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 second sentence, 'Tickers come from list_perps,' is real routing guidance for obtaining the required input and points at a sibling tool. However there is no statement of when to prefer this over get_perp_history or get_market, and no exclusions or preconditions.

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?

With annotations already declaring readOnlyHint and destructiveHint=false, the description adds valuable context: it details what live=true adds (current_bid_cents and mark_cents) and what those fields mean for selling and unrealized P&L. It also explains that recently_settled covers bets settled in the last 24 hours and tells the agent to relay that. No safety or auth behavior is contradicted, though rate limits are not discussed.

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 description is front-loaded with the resource and key fields, and the 'start here' directive appears early. It is dense but mostly earns its place, though the trailing recently_settled instruction feels tacked on and could be structured more cleanly.

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?

Given the output schema exists, the agent does not need return values explained, yet the description helpfully clarifies the live behavior and recently_settled meaning. The main gap is the unexplained full parameter, but with only two optional booleans and annotations covering safety, the description is largely complete 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 50%: live has a short schema description, while full is undocumented. The description compensates for live by explaining what live=true adds and the default, but it says nothing about the full parameter, leaving half the parameters without semantic clarification.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the specific resource (open positions) and lists the key fields returned (stake, instrument_id, bet, payout_if_win_dollars, loss_if_lose_dollars, web_url), so the agent knows what this tool fetches. It does not explicitly distinguish itself from siblings like get_orders or get_balance, though 'start here' implies it is the primary entry point for positions.

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 phrase 'start here' gives explicit guidance to use this tool first, which is a clear when-to-use signal. It also explains the default behavior of live=true and instructs the agent to surface recently_settled information, but it does not name alternatives or when-not-to-use conditions.

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 the safe read-only, non-destructive profile, so the description does not need to restate it. It does add one genuinely new behavioral fact — the *_pts fields are legacy aliases slated for removal in 0.7.0 — which helps an agent avoid coupling to deprecated output, but it omits any rate-limit, caching, or scope 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?

Two tight sentences with the field list front-loaded and a useful unit clarification in parentheses. The trailing legacy-field sentence is slightly tangential but short and does carry migration value.

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 enumerating return fields is more redundant than necessary, and parameters and safety are covered by the schema and annotations respectively. The remaining gap is the missing cross-reference to the sibling history tools, which prevents a full 5.

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 ref, points, and lookback (including the 2-60 range and enum values) are fully documented in the schema. The description adds no further parameter meaning, which makes the baseline 3 appropriate.

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 conveys a specific verb+resource: the recent price path of one market, with units in cents/percent. It is clear what the tool returns, but it never distinguishes itself from the many sibling history/market readers (get_history, get_perp_history, get_market), leaving the agent to infer the boundary.

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?

There is no when-to-use statement, no prerequisite, and no named alternative. With siblings like get_history and get_perp_history, the description gives no cue for choosing get_price_history over them, so the agent must guess from names alone.

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/non-destructive, so the safety bar is low. The description adds genuinely useful behavioral context beyond that: privacy is private by default, and the call exposes how many trades are hidden plus whether balance and rank are visible to others. It still doesn't say anything about permissions needed to read another account's state.

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?

A single dense sentence with no filler; the most important fact (private by default) leads. The trailing settings_url clause is slightly disorienting but not wasteful.

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 not be described, and annotations carry the safety profile. Combined with a 0-parameter schema, the definition covers what an agent needs; only the routing guidance relative to set_privacy 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 and the schema is an empty object, so there is nothing for the description to compensate for. Baseline of 4 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 names the resource (the account's privacy state) and enumerates exactly what is reported: private/public flag, count of hidden trades, and visibility of balance and rank. It is clearly a read of privacy state, distinguishable from the write-oriented sibling set_privacy, though it never explicitly contrasts itself with that 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?

There is no statement of when to call this tool versus set_privacy. The note that 'only the person makes it public (settings_url)' references an external settings page rather than a tool, and actually muddies the picture given that set_privacy exists as a sibling — it neither routes the agent nor excludes anything.

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 annotations that already cover read-only/idempotent/open-world, the description discloses the 90-day window, the Ed25519 signature scheme, the semantics of verify (checks against the website-published key) and the meaning of check.ok. It stops short of noting any rate limits or what happens when verification fails.

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 tightly-packed sentences that front-load what the tool returns and then layer the verification semantics. Every clause carries information with no filler, though the phrasing is dense enough to border on terseness.

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 needn't be described, and the description still covers the authorization model (no sign-in), the data window and verification outcome. For a zero-required-param read tool this is nearly complete, missing only a clarifying note on ref/trader aliasing and failure behavior.

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 67% and the schema already equates ref and trader. The description adds real meaning for verify by explaining the check against the published key and that check.ok is true only when all checks pass, which goes beyond the bare boolean type.

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?

It names a specific verb+resource (a trader's Ed25519-signed record) and scopes the window to the last 90 days, so the agent knows exactly what artifact it retrieves. It does not, however, explicitly distinguish itself from the overlapping sibling get_trader, which an agent might otherwise reach for.

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 gives one clear usage fact - verify=true validates against the key Arena publishes and 'No sign-in' is required - but says nothing about when to choose this over get_trader, get_my_stats or get_history. The condition to enable verification is implicit (set verify=true when you need trust), not stated as 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 establish read-only, idempotent, non-destructive semantics, so the description earns credit for the extra behavior it discloses: private accounts return private: true with trader_id null, public ones return standing, lifetime P&L, resets and recent_record, and picks=true expands the pick list. That privacy/null contract is the kind of thing an agent cannot derive from annotations and would otherwise mis-handle.

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 and tightly compressed: identity, privacy behavior, then the picks expansion, with no filler sentences. The telegraphic fragments ('resets', 'standing') are efficient but border on cryptic for a reader without domain context.

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 needn't enumerate return fields, and it still flags the key non-obvious outcomes (private vs public shape) plus the picks expansion. It omits not-found/unknown-trader behavior and the exact effect of limit, minor gaps against a well-annotated, output-schema-backed tool.

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 75%, with picks undocumented in the schema; the description fills that gap by explaining picks=true lists the recent picks. It only loosely gestures at limit ('recent_record over the last picks') and says nothing about the ref/trader aliasing beyond pointing at the param names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('One trader's public record') and pins the identity args ('by user id or name'), which is enough to separate it from list-oriented siblings like get_leaderboard. It never names an adjacent single-trader tool such as get_my_stats or get_track_record, so the differentiation from those is left to 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?

'No sign-in' tells the agent this is callable unauthenticated, and the private-by-default note explains the result the agent will get for most accounts. There is no explicit when-to-use vs when-not guidance, and no routing to alternatives for a caller who actually wants their own stats or a multi-trader track record.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds a real behavioral fact with 'No sign-in' and discloses the empty-result behavior of returning next_date. It does not describe pagination or cost of large day queries, but the added auth and empty-state context is genuine value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Compact and front-loaded, with the primary listing behavior stated before the mode conditions. The telegraphic semicolon style ('priced', 'today (New York)') is dense enough that a first read can misfire, 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-shape detail is not required, and the description still conveys grouping-by-league and the moneyline percent unit. The only real hole is the unexplained 'full' flag, which leaves a mode of the call invisible to the agent.

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 75% and the description reinforces the date semantics ('today' is New York time) and the limit asymmetry (max 100 for a day, default 20 for a league), which is real added meaning. However, the 'full' boolean is undocumented in both schema and description, so one parameter is opaque in the only two places it could be explained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (a day's games, or a league's upcoming games) plus what is returned (moneyline chance from Kalshi, grouped by league). It distinguishes its own two operating modes clearly, but never names sibling tools like get_game or list_markets, so the agent must infer the boundary itself.

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 usable routing logic: with a date you get that day's slate, with a league and no date you get that league's upcoming priced games, and an empty day points you to next_date. No explicit exclusions or named alternatives are given, which is the only thing separating this from 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 already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for adding traits annotations cannot express: quotes are compact/summary-level, carry a spread, and go stale, requiring a get_market refresh before acting. That freshness caveat is genuinely useful and not derivable 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?

Two short sentences with zero filler, front-loaded with purpose and ending on the operational caveat. Every clause 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-format detail is unnecessary, and the description supplies the remaining essentials: scope, filters, and the staleness/refresh requirement. The only minor hole is the unexplained 'full' parameter, which is small against an otherwise complete picture.

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 60% (full and sport are undocumented in the schema). The description maps its three filter axes to league/sport/event_ticker, but says nothing about the 'full' or 'limit' parameters, so it only partially compensates for the coverage gap. Baseline 3 is appropriate.

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 gives a specific verb and resource ('Browse open markets') plus the filter axes (league, sport, event) and the shape of what comes back ('compact quote rows with a spread'). It differentiates itself from get_market, but not from the similarly-scoped siblings search_markets and screen_markets, which is the main gap.

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 an explicit follow-up workflow: rows go stale, so call get_market before trading. That is real when-to-use guidance naming an alternative. It does not, however, say when this tool is preferred over search_markets or screen_markets, which are the closest competitors.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that — the records include live settlement marks denominated in dollars and come from a specific endpoint — but says nothing about pagination, result size, or rate limits.

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?

Two tight sentences, front-loaded with the resource and scope, with no filler. Slight redundancy in re-listing the enum values already present in the schema 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?

An output schema exists, so return-value explanation is unnecessary, and one optional enum parameter with an annotation-covered safety profile is a simple surface. The description covers purpose, endpoint and filter; only pagination/scale behavior is unaddressed.

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 the single enum parameter already documents 'Default active.' The description merely restates the same enum values and default, adding no syntax, format, or behavioral 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 a specific verb (List) and resource (Kalshi perpetual tickers and their live settlement marks), plus the source endpoint (GET /perps/markets) and the data's unit (dollars). It is clearly distinguishable from get_perp_mark and get_perp_history by being a listing operation, though it never explicitly names those siblings.

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?

Listing intent is implied by 'List ... tickers', and the status filter values give some operational context, but there is no explicit statement of when to use this versus get_perp_mark or get_perp_history, and no prerequisites or exclusions are mentioned.

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 destructive/write semantics, and the description adds rich operational context: idempotency_key_reused, replayed=true on retry, upstream_unavailable/timeout handling, insufficient_balance with details.max_contracts, the ~20/min dry_run limit, and refusal of live/poly_intl (live_not_hosted). This far exceeds what the annotations alone 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?

Long, but the length is justified by 19 parameters and dense server rules; required inputs are front-loaded before fill/error behavior. It reads as a run-on wall of text, however, and dry_run is described more than once, costing some crispness.

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?

Given an output schema exists (so return values needn't be documented), the description still supplies the error codes, retry contract, and payout_if_win_dollars/loss_if_lose_dollars/fill_venue fields the agent must relay to a person. 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 coverage is 95% so the baseline is 3, but the description adds cross-parameter logic the schema can't express: exactly one of ticker+side or instrument_id+instrument_side, stake_dollars needing max_price_cents or limit_price_cents, and pass-one-of live/poly_intl. It stops short of explaining a few params (venues, token_id, expires_at) but clearly exceeds schema field docs.

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?

Opens with a specific verb and resource ('Buy YES or NO contracts') and is instantly distinguishable from siblings like sell_trade and cancel_order. The trade-execution action and its paper-only nature are stated up front.

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 when-to-use and when-not: it routes the agent through dry_run + confirm for route=best and says to pass route=kalshi otherwise, gives retry guidance (retry once with the same key, never retry a 4xx), and names get_positions/get_orders as ground truth. Alternatives and preconditions are all present.

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/openWorld/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: it never guesses, no rows signals a rephrase, without a day word all unfinished games return with pregame first, and a started game's prices are in play. It still omits any latency/rate-limit caveats, keeping it at 4.

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 purpose, then layer-by-layer adds query syntax, failure modes, and how to act on results — every sentence carries information. It is a dense single block with no whitespace or bullet structure, which slightly hurts scannability but not substance.

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 resolver with an output schema, the description still adds value by telling the agent how to act on results (buy kalshi[].buy_side on kalshi[].ticker, or pass instrument_id with instrument_side = query_side) and to store instrument_id as given. Coverage is strong, though the unexplained `full` param leaves a small gap.

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 67% and `query`'s only schema text is the useless 'The bet in words.' The description compensates heavily with query construction rules (team names, spread, over/under, day words, league qualifiers), adding meaning the schema lacks. The `full` parameter is never explained in either place, which holds this below 5.

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 — mapping a natural-language bet ('chiefs ml', 'mia +3.5') to Arena instrument ids plus the Kalshi ticker and side to buy. The purpose is unmistakable and distinct in spirit from id-based siblings like get_market. It stops short of naming an alternative tool (e.g., search_markets), so it does not fully earn a 5.

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 concrete usage context: 'no rows means rephrase: add the other team or league; a total needs over or under', and explains day-word behavior and default ordering. This is rich when-to-use guidance. It does not explicitly route the agent away from alternatives such as search_markets, so it sits below the 5 bar.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds that rows carry spread_cents and move_cents, useful output context, but says nothing about ordering, pagination, or the row-count limits an agent would want to know.

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?

Two sentences, no filler, with the purpose and filter set front-loaded before the workflow hint. Nothing wasted and no buried 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?

For an 11-parameter screening tool with an output schema (so returns need not be explained), the description covers the main filter dimensions and a safety pointer. It still leaves the sort enum, the full flag, and default limit/pagination behavior unaddressed, which are non-trivial for this parameter count.

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 only 45%, so the description must compensate, and it does: it enumerates the seven screening concepts (league, group, volume, price, spread, time to close, 24-hour move) that map onto the eleven filters, and clarifies spread_cents/move_cents fields. It stops short of disambiguating min/max price or the sort/full flags.

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 (screen) and resource (open markets), then enumerates the screening dimensions (league, group, volume, price, spread, time to close, 24-hour move). The agent understands this is a filtered discovery tool, though it is not explicitly distinguished from siblings list_markets or search_markets.

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?

"get_market before trading" gives a downstream workflow pointer, implying screen results are candidates to be inspected before acting. However, it never states when to prefer screen_markets over list_markets or search_markets, nor any exclusions, so the choice between the three discovery tools remains implicit.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: matching is substring-based, one word at a time, and game winners are titled by city. It says nothing about result ordering, pagination, or why the search is open-world, so it stays at an adequate-but-thin level.

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?

Two dense sentences, front-loaded with the core matching semantics before the sibling aside. The nested parentheses make the parenthetical example slightly hard to parse, 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 values need not be described. The matching semantics and one-word constraint are covered, but the 'full' parameter is unexplained and there is no note on ordering or result scope for a search tool that can return many matches. Adequate for the tool's complexity but with visible holes.

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 33%: only 'limit' is documented (default 10, max 50) in the schema itself. The description meaningfully explains what 'query' matches (titles and tickers, one word at a time, with the 'Kansas City' example), which is more than the schema offers. The 'full' boolean, however, is undocumented in both schema and description, leaving a real gap.

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 mechanism (substring search) and the exact resource fields searched (market and event titles and tickers). It also gestures at the sibling boundary by noting that list_markets with event_ticker lists an event, so the agent can distinguish the two without opening schemas. Not fully 5 because the relation to screen_markets is left unstated.

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 gives an actionable querying rule ('one word at a time') and hints that list_markets is the alternative for listing an event's markets, which is genuine routing guidance. However, it never states when to prefer search_markets over screen_markets or list_markets, and no exclusions are given. Usage is implied rather than 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 declare destructiveHint=true, idempotentHint=true and openWorldHint=true, but the description adds substantial context beyond them: a closed trade returns its terminal state, route=best may split fills into legs, contract_note appears on every non-Kalshi exit, selling is never membership-gated, and live/poly_intl calls are refused with live_not_hosted on this paper-only server. This is rich disclosure the structured fields do not 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?

Purpose is front-loaded and every clause carries information, but the procedural tail is a dense run-on of sentence fragments ('Live=true sells on Kalshi. Pass one. Default is paper.') that is harder to parse than it needs to be. Size is defensible for a 15-parameter tool, but the telegraphic style costs readability.

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 needn't be explained, yet the description still names the fields an agent must surface (proceeds_dollars, pnl_dollars, fill_venue, price_cents, crosses_now). It covers venue selection, the paper-only refusal, the split-order case, and the confirm/idempotency dance — everything needed to call 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 already 80%, so the schema carries most parameter documentation; some description content (confirm/idempotency_key requirements, time_in_force rest semantics) overlaps it. However, the description adds genuine semantics the schema lacks — what route=best vs route=kalshi means for fill venue, the relationship between the dry run's fill_venue and min_price_cents, and the 'pass one' rule for live/poly_intl.

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 sentence states a specific verb and resource — 'Exit an open position at the bid (current_bid_cents), or rest a limit exit' — and immediately distinguishes the two exit modes. It reads clearly against the buy-side sibling place_trade. An agent can tell what this 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?

It gives explicit branching: with route=best, run dry_run=true first, report proceeds/pnl/fill_venue to the person, then re-call with confirm=true; otherwise pass route=kalshi. It also states when to pass min_price_cents based on the dry run's fill_venue, and that confirm plus a fresh idempotency_key are required except for dry_run. Alternative paths and their selecting conditions are named.

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 destructiveHint=true and idempotentHint=true, so the mutation profile is known. The description adds real value by naming what changes (visibility of trades and record), requiring in-conversation consent, and noting the operation is one-directional through this tool. It does not discuss timing or confirmation of the resulting state, so not quite 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 tight clauses with zero filler: effect is front-loaded, then the consent gate, then the scope limitation. Every sentence earns its place and nothing is 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 an output schema present, return values need not be explained, and annotations cover the safety profile. The description supplies purpose, consent gating, and irreversibility via this tool, which is sufficient to invoke correctly. Minor gap: no mention of the resulting state or confirmation behavior, but nothing that would cause a wrong call.

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% with both params (confirm, private) documented and constrained to const true. The description reinforces the consent intent behind confirm but adds no syntax or format detail beyond the schema. 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+resource (make the account private) and the concrete effect: others stop seeing its trades and record. It also explicitly bounds scope by stating it cannot make an account public. An agent can distinguish this setter from the get_privacy read sibling 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 gate (only when the person asked in this conversation) and a when-not/alternative path (cannot make public; do that in Settings on the website). Both the enabling condition and the excluded direction are stated, leaving little 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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered; the description's 'Idempotent' merely repeats the annotation. It does add useful operational context (cron backstop, safe at session start), but never explains what the destructive side of settlement actually does to a position.

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?

Two short sentences, front-loaded with the action and effect, then the operational context and the required flag. 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?

With an output schema present (so return values need no explanation) and annotations carrying the destructive/idempotent profile, the description supplies exactly what is missing: when to reach for it and the confirm gate. Nothing an agent needs to invoke it correctly 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?

Schema description coverage is 100% for the single confirm parameter, so the schema already documents it; the description's 'Requires confirm=true' is a helpful reinforcement of the required flag but adds no new semantics or format detail. 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 precise verb+resource ('settle your positions whose markets have resolved') plus the effect ('report what changed'), which cleanly separates it from resolve_market (which resolves a market rather than settling positions). An agent can identify the operation 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 situational cue: it is a backstop to an automatic 5-minute settlement cron and is safe to run at session start, implying it should be called when settlement may have been missed. It stops short of naming explicit alternatives or a when-not condition (e.g., what to do if nothing is open).

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