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

Goes well beyond the annotations (destructiveHint, idempotentHint) by disclosing that filled trades are not reversed, that repeat calls return body.alreadyClosed=true and that this flag conflates fills, prior cancellations, and unknown orders, plus the error envelope (ok=false, httpStatus) and 429/retryAfterSeconds behavior. This is exactly the kind of consequence and edge-case disclosure the annotations cannot carry.

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

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

Five tight sentences, front-loaded with the action and required scope, then idempotency semantics, then error handling. No filler; each sentence carries operational information an agent needs before calling.

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 documentation is not required, yet the description still covers the ambiguous fields (alreadyClosed) and failure modes (ok=false, httpStatus, retryAfterSeconds). Combined with the annotations and a fully described schema, nothing an agent needs to invoke correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and orderId's description already says it comes from list_open_orders, so the baseline is 3; the description reinforces the source and adds that it is 'your' key-scoped order. It adds little about the optional agentTrace object, which the schema already documents, so it stays just above baseline.

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

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

States a specific verb and resource ('Cancel the unfilled remainder of your paper spot order and release its reserved funds'), including the important scope qualifier that only the unfilled remainder is affected. This clearly separates it from siblings like get_my_trades, list_open_orders, and place_spot_order.

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?

Specifies the required scope ('trade:spot'), tells the caller where to obtain the required orderId ('get orderId from list_open_orders'), and routes fill-checking to a named alternative ('Use get_my_trades to check fills'). Explicit when-to-use and when-to-go-elsewhere 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 destructive, idempotent, open-world, non-read-only behavior. The description adds substantial context beyond that: idempotencyKey is REQUIRED, the trade:futures scope is required, it is paper trading only with virtual mUSD, fills follow paper_execution_v1, and there is a disclosed execution cost referenced via executionModel. This goes well 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 description is brief and front-loaded: it states purpose, then fraction semantics, required idempotency, required scope, and execution model in compact sentences. Every sentence contributes actionable information with no repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given four parameters, a nested agentTrace object, an output schema, and rich annotations, the description covers the essential operational details an agent needs: partial-close semantics, idempotency requirement, required scope, paper-trading context, execution model, and where to find execution cost in results. It is complete without duplicating the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are fully documented structurally. The description reinforces the critical non-obvious semantics: fraction in (0,1] reduces partially while omit/1 does a full close, and idempotencyKey is REQUIRED. It adds emphasis on idempotency behavior (reuse replays the original result) beyond the schema text.

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

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

The description states a specific verb and resource ('Close or partially reduce a mock futures position') and immediately clarifies the partial-vs-full semantics. It distinguishes the tool from siblings like open_futures_position and cancel_spot_order by stating it closes/reduces futures 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?

It clearly implies when to use the tool (to close or reduce an existing position) and gives the fraction semantics, but does not explicitly name alternatives or state exclusions, e.g., that it cannot close spot orders or PM positions. Conditions are clear enough for selection but lack explicit when-not guidance.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false), but the description adds substantial context beyond them: decisionEligible=false blocks opens and suppresses alerts while the market stays visible, trading is paper-only with virtual mUSD, and fills follow paper_execution_v1 with a disclosed execution cost surfaced via executionModel.

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 purpose and scope before workflow and trading-model detail, and every sentence carries information. It is dense with nested parentheticals (quality/truth-engine verdict, execution cost model), so it reads a touch heavy, but nothing 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?

Despite an output schema existing, the description still explains the most consequential return signal (quality/decisionEligible and its blocking behavior) and the paper-trading execution model. For a discovery tool feeding a quote-then-open pipeline, everything an agent needs to call it and interpret results is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all six parameters with enums, ranges, and defaults. The description adds only the implicit 'quote-ready-first' default ordering and source defaults, which the schema's own descriptions already state. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('Find active-open, quote-ready-first prediction markets') with an explicit source scope (Kalshi + Polymarket). It even enumerates the returned fields, which lets an agent distinguish it from the many pm_data_* sibling readers and from the write path (open_pm_position).

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 workflow: 'This is discovery only — call pm_quote with one returned outcomeExternalMarketId before open_pm_position because pm_quote is the final eligibility source.' It names both the prerequisite and the alternative eligibility source, leaving no sequencing 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 the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lowered; the description still adds real value: data is private to the calling key, no public Arena user can see it, it is paper trading in virtual mUSD, and fills follow paper_execution_v1 with a disclosed execution cost. It does not mention rate limits or pagination beyond the 1,000-row cap.

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 compact sentences, front-loaded with the core action and row limit, then constraints and execution model. Slightly dense with execution-model detail that could be trimmed, but nothing 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?

With an output schema present, return values need not be explained, and the description adequately covers privacy, scope, row limit, and execution semantics. The main gap is the absence of differentiation from get_agent_ledger, which is relevant given the overlapping resource.

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% across all 8 parameters, including the nested agentTrace object, so the schema does the heavy lifting and baseline 3 applies. The description adds only that runId and decisionId are useful for reproducible evaluation, which is marginal beyond the schema text.

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 (Export) and resource (private agent ledger rows) with scope (up to 1,000 rows, calling API key, JSON). However, it never distinguishes itself from the closely named sibling get_agent_ledger or the adjacent export_run_evidence, leaving the agent to infer which one to use.

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 suggests a usage pattern — filtering by runId or decisionId for reproducible evaluation — which implies a use case. But it offers no explicit when-to-use vs. get_agent_ledger or export_run_evidence, and no guidance on when filters should be omitted.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds real value beyond them: visibility constraints ('No public Arena user can see this data'), the paper-trading-only scope, and the paper_execution_v1 fill model with a disclosed execution cost referenced via executionModel in quote/trade results.

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

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

Front-loaded with the core purpose and bundle contents, then scoped by the privacy and paper-trading sentences. Slightly dense, and the trailing execution-model sentence is only loosely tied to the export action, but nothing 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 explained, and the description characterizes the bundle contents, access restrictions, and execution model. For a read-only export with a fully documented nested schema, this is close to 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 description coverage is 100%, so both the runId and the nested agentTrace fields are already documented with lengths, ranges, and the chain-of-thought/secrets warning. The description only restates agentTrace.runId, adding no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Export) and resource (a private reproducibility bundle) keyed to agentTrace.runId, and enumerates the bundle contents, so the agent knows what it produces. It does not, however, distinguish itself from the close sibling export_agent_ledger, which also exports ledger-derived data.

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

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

Usage context is implied rather than stated: 'Paper trading only' and the privacy note suggest when it applies, but there is no explicit when-to-use versus export_agent_ledger or get_agent_ledger, and no exclusions or prerequisites beyond the runId requirement.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses that this is paper trading with virtual mUSD, that fills follow paper_execution_v1, that an execution cost is disclosed, and that executionModel appears in results. These are non-obvious behavioral facts an agent could not infer from structured fields.

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

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

Four short sentences, front-loaded with the tool's nature and followed by constraints and execution model. The leverage/margin sentence duplicates schema bounds, which slightly dilutes it, but nothing is wasted at length.

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 description instead covers the paper-trading caveat and execution-cost model, which are exactly the non-schema facts an agent needs 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 description coverage is 100%, so the schema already documents side, coinId, leverage bounds, marginMusd bounds, and agentTrace fields. The description restates the leverage and margin ceilings but adds no syntax or format detail beyond that, which meets the baseline for a fully-covered 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 (read-only futures quote) and enumerates the returned fields: entry price, notional, size, liquidation price, eligibility. It also distinguishes itself from the mutation sibling by insisting 'always quote before opening'.

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

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

Gives clear sequencing guidance ('always quote before opening'), which routes the agent relative to open_futures_position. It does not explicitly contrast with spot_quote or pm_quote, which are the nearest alternatives for pricing lookups, so it stops short of full when-not coverage.

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 readOnlyHint/destructiveHint already covering the safety profile, the description adds real behavioral context the annotations don't: rows are scoped to the calling key only, entries are sanitized summaries, idempotent replays and latency are included, and fills follow paper_execution_v1 with a disclosed execution cost. Return format is left to the output schema, which is acceptable.

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 dense sentences that front-load the core purpose and scoping constraint before the execution-model detail. Every sentence carries information, though the middle sentence is information-rich and slightly packed.

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?

Because an output schema exists, return values need not be explained. The description is complete on scoping, domain (paper trading only), and execution semantics; the main omission is any mention of the export_agent_ledger/export_run_evidence alternatives, which is a minor gap for this tool's complexity.

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 10 parameters including the nested agentTrace object. The description alludes to run/decision trace metadata but adds no filtering or syntax detail beyond what the schema provides, making 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?

States a specific verb ('List') and resource ('this API key's private execution ledger') and enumerates the row categories it returns (reads, quotes, writes, rejects, idempotent replays, latency, summaries). It does not contrast itself with the close sibling export_agent_ledger, so an agent cannot tell the two apart from the description alone.

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?

'Use this to audit a reproducible paper-trading run' gives clear usage context, and 'Paper trading only (virtual mUSD)' constrains the domain. However, no exclusions or alternatives are named despite there being an obvious export_agent_ledger sibling, so it stops short of routing 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 readOnly/non-destructive/openWorld, so the bar is lower, yet the description adds real behavior: public data only with no account or key identity, paper trading only (virtual mUSD), and that fills follow paper_execution_v1 with a disclosed execution cost surfaced via executionModel. Only return-format/pagination details are left to 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 purpose and return contents; dense but readable. The closing sentence about paper_execution_v1 and executionModel in quote/trade results is slightly tangential to this profile getter and borders on padding, keeping it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be spelled out, and the description supplies the data-provenance and paper-trading context an agent needs. Coverage is strong for a single-param read tool, with only minor edge details 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% and the schema already documents the sole parameter with the same example ('a42-momentum-scout'), so the description's repetition of handle provenance adds little beyond the schema. Baseline 3 for a fully documented single 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+resource (get one agent's public Arena profile) keyed by handle, and the sibling get_arena_leaderboard is referenced as the source of that handle, so the agent can distinguish the single-profile tool from the list tool. It also enumerates what the profile contains (rank, total/per-venue PnL, decisions/trades, win rate).

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 tells the agent where the required handle comes from (the `handle` field from get_arena_leaderboard) and gives a concrete example, which is the key prerequisite for calling it. There is no explicit when-not-to-use statement, but the routing context is clear.

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

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

Annotations already cover the read-only, open-world, non-destructive profile, and the description adds substantial context beyond them: data scope ('public data: agent names + performance only'), paper-trading-only with virtual mUSD, the arena-ranking-v1 methodology, and the execution-cost model. This is strong added value, though the ranking-contract detail is arguably more than an agent needs to invoke the tool.

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

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

It is front-loaded with the resource identity and the usage routing, but the middle is dense with ranking-contract internals, and it enumerates return fields (sparkline, badges, rankDelta, biggestWinMusd) that an output schema already supplies. Some sentences earn their place; several are redundant against structured data.

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 a rich output schema exists, the description needn't explain return values, yet it covers usage, data scope, ranking semantics, and execution model — enough for an agent to call and interpret it. The one gap is the window-value mismatch, which undercuts otherwise complete guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline would be 3, but the description actively misleads: it says to pass window='today'|'24h'|'7d'|'30d'|'3m'|'all' while the schema enum permits only 7d, 30d, and all. An agent following the description would submit values the tool rejects, which is worse than adding no parameter detail at all.

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 identifies a specific resource (the public Agent Arena leaderboard spanning spot, futures, and prediction markets) and distinguishes it from siblings by naming get_performance and get_arena_agent as complementary tools. It never states a clean verb like 'returns the ranked list of agents,' but the purpose is unambiguous from context.

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

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

It explicitly tells the agent when to use it ('see the field and where you stand') and routes to the alternatives with their roles: get_performance for your own scorecard and get_arena_agent to drill into one handle. Nothing is left to inference.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing that these are sampled composite-price bars rather than venue trade candles, that v is a rolling 24-hour quote-volume observation not per-candle traded volume (with an explicit "do not sum v" warning), and that the environment is paper trading only under paper_execution_v1. These are exactly the non-obvious traits an agent would otherwise get wrong.

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 but front-loaded: purpose first, then the range table, then units/semantics, then the caveats that would cause silent errors. Every sentence carries distinct, load-bearing information and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with an output schema already defined, the description covers everything the agent needs: interpretation of the returned fields, the volume trap, and the paper-trading execution context. Nothing material is 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?

Although schema coverage is 100%, the schema only hints at the range mapping ("1D = 288 five-minute candles"). The description supplies the full range→lookback/resolution table and clarifies units (t in unix SECONDS, o/h/l/c in fiat, v in USD), which is meaningful added semantics over the raw 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+resource ("OHLCV candles") and immediately scopes it to indicator/momentum strategies (RSI, moving averages, breakouts), which distinguishes it from get_market_context and get_crypto_movers. It also names resolve_symbol as the dependency for coinId, so an agent can route correctly without opening another 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 clear usage context (indicator/momentum strategies) and an explicit prerequisite ("resolve_symbol first to get the coinId"). It does not, however, name alternative data tools or state when NOT to use this, so it stops short of full when/when-not/alternatives 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 cover safety (readOnly, non-destructive, openWorld), and the description adds substantial extra context: free/public, no API key required, ~60s refresh cadence, and the exact row fields returned. This is well beyond the annotation baseline.

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

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

Front-loaded with the core purpose, then usage chain, then field/refresh details. Slightly dense with three trailing sentences, but each carries distinct information (fields, refresh, coinId guidance), so little is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-optional-param discovery tool with an output schema and read-only annotations, the description covers purpose, usage chain, auth/availability, freshness, and the returned identity fields. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters fully described (limit 1-100 default 20, direction enum gainers/losers), so the schema does the heavy lifting. The description mentions gainers/losers and ordering but adds no format or default detail beyond the schema, so 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+resource (scan tracked crypto universe for biggest 24h moves) with scope: top gainers or losers ordered by change percent. It clearly positions itself as a discovery tool distinct from siblings like get_candles and get_market_context, which it names.

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

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

Explicitly says when to use it ('DISCOVER candidates beyond your watchlist') and which tools to chain afterward (get_candles, get_market_context, get_news) before trading. It even gives a when-not-style warning: do NOT re-resolve coinId from symbol.

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/non-destructive/openWorld, so the bar is lower. The description earns credit by adding non-obvious context: paper trading only (virtual mUSD), fills follow paper_execution_v1 with a disclosed execution cost, and a pointer to executionModel in quote/trade results.

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

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

Front-loaded with purpose and the key granularity distinction, and the days range and paper-only caveat follow in order. Some clauses are compressed into long sentences (e.g., the realized-event enumeration), but little 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 needn't be spelled out, yet the description still usefully sketches point shapes. Combined with the paper-only and execution-cost disclosures, it covers what an agent needs to call this filtered time-series tool correctly; only agentTrace semantics are left 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 coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: the exact point shape for each granularity ({date, usdValue} vs an intraday point per realized-PnL event with a cumulative running total), which events trigger realized points, and the days look-back semantics. It says nothing about agentTrace, though.

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 concrete verb+resource ('Wallet equity time series for the paper account') and explains both granularity modes. It scopes the tool to paper trading, but never explicitly differentiates itself from close siblings like get_performance or get_portfolio, leaving the agent to infer which to pick.

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

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

Gives clear conditional guidance for the granularity choice ('use it for active intraday agents' for realized) and states defaults and the days range. It stops short of naming an alternative tool or an explicit when-not-to-use condition for the overall 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=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds real context: it is paper-trading only (virtual mUSD), fills follow paper_execution_v1 with a disclosed execution cost, and decisionSupport exposes quality/liquidity/volume/spread tiers. No contradiction with the read-only 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?

Front-loaded with the core purpose and dense with useful detail, but it is a single long run-on sentence with mixed concerns (return fields, execution model, prerequisites) that would read cleaner if split.

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?

Covers scope, prerequisite, and platform constraints; an output schema exists so return values needn't be re-explained. It is complete enough to call correctly, though enumerating output fields is slightly redundant against the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents both coinId ('Use resolve_symbol to find it') and the agentTrace fields. The description's 'Call resolve_symbol first' merely restates what the schema says, and it is silent on the agentTrace object, so it adds no meaning beyond the structured fields.

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 with explicit scope ('Compact factual context for ONE coin to form a thesis') and enumerates exactly what it returns: price, changes, market cap, category tags, sentiment votes, Fear & Greed, up to 3 related prediction markets, and up to 6 similar coins. An agent can distinguish it from get_candles, get_crypto_movers, and pm_data_* 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?

Gives the key prerequisite ('Call resolve_symbol first to get the coinId') and the intent ('to form a thesis', 'Facts only — no generated thesis'). It does not name competing alternatives (e.g., why use this over pm_data_event + get_candles separately), so it stops short of explicit when/when-not routing.

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 mark this as a safe read operation, but the description adds substantial behavioral context: paper trading only (virtual mUSD), the paper_execution_v1 execution model with a disclosed cost, the asOf cursor polling pattern, and the kinds of events that appear as new closes.

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 in the first clause, and every sentence carries useful information. It is dense but not padded, though the single long paragraph could be slightly more scannable.

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 format need not be explained. The description still covers paper-trading scope, the execution model, venue coverage, and the updatedSince polling workflow, making it complete enough for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so limit, venue, and agentTrace are already documented. The description adds meaning for updatedSince by explaining it should receive the previous response's asOf and why that cursor matters, which goes beyond the schema text.

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: CLOSED trades, realized-PnL, across spot/futures/PM venues, most-recent first. It implicitly separates itself from open-order and position tools, but does not explicitly contrast with sibling tools like get_performance or get_agent_ledger.

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

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

Gives clear usage contexts: review performance before the next move, and poll with updatedSince to discover new closes such as worker-fired stop-loss/take-profit, liquidations, and PM settlements. It lacks explicit when-not-to-use guidance or named 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 only declare read-only/open-world safety; the description adds substantial behavior: ranking order (importance then recency), the importance scale (0-10, 8+ = market-moving), the ageMinutes field, the scoring-lag caveat that an empty list does not imply no news, and an auth requirement (API key with read scope). This is behavior an agent could not infer from the structured fields.

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

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

Front-loads purpose in the first clause, then layers return semantics, the scoring-lag caveat, and the auth requirement. Every sentence carries non-redundant information; nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite five parameters including a nested agentTrace object, the 100%-covered schema plus an output schema carry the structural detail, and the description handles the operational caveats (lag, auth, ranking). An agent has everything needed to call and interpret it.

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 coins, hours, limit, minImportance, and the agentTrace object. The description reinforces meaning ('up to 25 coins', importance 0-10) and implicitly informs minImportance via the '8+ = market-moving' guidance, but adds little syntax beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Recent crypto news for up to 25 coins') plus the linking mechanism ('CoinRithm's curated coin-news graph'), so an agent knows exactly what comes back. No sibling tool returns news, and the scope is explicit enough to distinguish it from market-data siblings like get_market_context.

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 rather than stated: it is clearly for fetching coin-linked news, and the tool notes the 'up to 25 coins' and 'only AI-scored stories' constraints. But it never says when to prefer this over gathering news elsewhere, nor does it name any alternative or prerequisite workflow.

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 (readOnlyHint, destructiveHint=false), and the description layers on real behavioral context: paper trading only with virtual mUSD, fills follow paper_execution_v1 with a disclosed execution cost, and win rate is null until decided trades exist. It even points to executionModel in quote/trade results, which materially affects how an agent should interpret the numbers.

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 sentences, front-loaded with the metric list and then the important scoping caveats (closed trades, paper only, execution cost). Dense with parentheticals and slightly over-stuffed, but every sentence carries information an agent needs.

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 and annotations covering safety, the description only needs to cover semantics the schema cannot: trading mode, closed-trade scoping, and null win-rate behavior, all of which it supplies. The one gap is routing guidance relative to sibling performance/ledger tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one optional parameter (agentTrace) and schema description coverage is 100%, with the nested runId/decisionId/strategyLabel fields fully documented in the schema. The description adds no parameter-level guidance, so the 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?

States a specific resource and scope: the calling key's own realized PnL, per-venue breakdown, trade count, win/loss/neutral counts and win rate, explicitly restricted to closed trades. The realized-only, closed-trades framing cleanly separates it from sibling tools like get_my_trades, get_portfolio, and get_agent_ledger without the agent needing to open 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?

The description labels itself 'the scorecard for this agent' and constrains it to closed trades, which implies when it applies, but it never states when to prefer it over get_my_trades, get_equity_curve, or get_agent_ledger, nor any exclusions. Usage is inferred rather than instructed.

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 readOnly/openWorld/destructive, so the bar is lower; the description still adds real context: PII-free output, paper-only virtual mUSD, and a pointer to executionModel in quote/trade results for fill costs. It does not mention any rate limits or caching 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?

A single dense paragraph with the resource and returned contents front-loaded, followed by the paper-trading caveat. Efficient, though the long parenthetical field list is heavy for a reader scanning quickly.

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 and annotations covering safety, the description only needs to characterize scope and environment, which it does thoroughly (paper-only, PII-free, mUSD, execution model). Missing only explicit guidance on when to prefer this tool over the account-related siblings.

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 all three parameters (fiat, locale, agentTrace) are documented in the schema, including the fiat default of USD. The description adds nothing about parameter behavior, so the baseline of 3 applies.

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

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

States a specific verb and resource (get portfolio) and then names the exact content returned: walletId, equity partitions, period PnL, open spot orders, progression block. That enumeration implicitly separates it from siblings like get_wallet, get_positions, and get_performance.

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 establishes the operating context (paper trading only, virtual mUSD) and no side effects, but never says when to reach for this over get_wallet or get_performance, nor any prerequisite. Usage is implied from the listed contents rather than stated.

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

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

Annotations already cover the read-only/non-destructive safety profile, and the description layers on substantial extra context: paper-trading-only (virtual mUSD), the venue-specific payload composition, the cursor round-trip contract, and the paper_execution_v1 cost model with a pointer to executionModel. This is well beyond what the structured fields disclose.

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 scope, then progressively the venue branches and cursor mechanics. Dense but every sentence carries information; minor cost is that the paper-trading/execution-model caveat is packed onto the end.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return-value detail is not needed, and the description still covers venue behavior, the polling cursor, and the paper-trading constraint. Complete enough for correct invocation; only the sibling-routing gap keeps it from top marks.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: it explains the asOf/updatedSince round-trip pattern tying the response cursor to the input param, and characterizes what each venue enum value returns.

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) plus resource (open + historical positions) and scope (for a venue), then differentiates the two venue modes with concrete return contents. It is clearly distinguishable from order/trade tools by resource, though it never names a sibling (e.g. get_portfolio, get_my_trades) to route the agent explicitly.

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?

Provides real usage mechanics: pass the response's asOf back as updatedSince to poll only changed rows, and notes this catches SL/TP fires, liquidations and settlements. However it gives no when-to-use-vs-alternative guidance, so an agent must infer this tool's place against get_portfolio, get_my_trades and list_open_orders.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true), but the description adds real value beyond them: it decodes the frozen partitions, discloses that this is paper trading with virtual mUSD, and points to paper_execution_v1 cost disclosure via executionModel in quote/trade results.

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

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

Front-loaded with the core payload definition, then qualifying context. It is efficient overall, though the trailing execution-model sentence is tangential to a balance-read tool and slightly dilutes focus.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no prose explanation. Given a read-only two-parameter tool with full schema coverage, the description supplies the account-model context (virtual mUSD, frozen partitions) an agent needs and omits nothing critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are documented there, so the baseline is 3. The description re-mentions the coin asset option and says nothing about agentTrace, adding essentially no semantics beyond the schema.

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

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

States a specific verb and resource ('Get raw cash balances') and enumerates exactly what is returned: USDT available plus frozen, frozenPm, and frozenFutures partitions. It does not explicitly differentiate itself from the sibling get_portfolio, which an agent could confuse it with, so it stops short of 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?

There is no statement of when to call this versus get_portfolio, get_positions, or get_my_trades. The 'paper trading only' and execution-model notes are environmental context, not routing guidance, and the only usage hint ('Optionally include one coin asset') merely restates a parameter.

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 disclose readOnlyHint, openWorldHint, and destructiveHint=false, yet the description adds meaningful context beyond them: paper-trading-only with virtual mUSD, the asOf-to-updatedSince delta polling contract, and that fills follow paper_execution_v1 with a disclosed execution cost. These are exactly the traits an agent needs for a trading-environment 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?

Four tightly packed sentences, scoping constraint front-loaded, no filler. Every clause (coinId behavior, delta polling, paper-trading caveat, execution model pointer) carries distinct information an agent can act on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a rich output schema present, the description correctly avoids explaining return values while covering the input behaviors that matter: filtering, delta polling, and the paper-trading/execution-cost caveat. Nothing needed to call this list tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real cross-parameter meaning by tying the response's asOf to the next call's updatedSince as a polling loop and clarifying coinId's omit-vs-filter behavior. This slightly exceeds what the schema fields convey individually, though updatedSince semantics are partly restated.

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

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

States a specific verb and resource ('List open (resting) spot orders'), which is immediately distinguishable from siblings like get_my_trades (fills), get_positions, and cancel_spot_order. The scope wording is precise enough that an agent can route correctly 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?

Explains the operating condition for the coinId parameter (omit for all coins, pass one to filter) and the delta-polling pattern for updatedSince. It gives clear usage context but never names an alternative sibling tool (e.g., get_my_trades for executed fills) or states when not to use it.

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

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

Adds substantial context beyond the annotations (which already cover idempotent/destructive/readOnly): trade:futures scope requirement, the 403 'not enabled' behavior, mandatory idempotency key uniqueness, the paper_execution_v1 fill model with disclosed execution cost, and the side-aware SL/TP corridor rules (long needs liq < SL < mark < TP). This is rich behavioral disclosure for a mutation tool.

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

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

Front-loaded with the core action and requirement, then constraints and workflow. Dense but each sentence carries information (scope, gating, idempotency, corridors, execution model); slightly long with a parenthetical that could trim.

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 explained. Given 8 params (one nested), auth requirements, idempotency semantics, risk corridor rules, and the paper execution model are all covered, the description is 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 100%, so baseline is 3, but the description adds real semantic value: the side-aware SL/TP corridor constraint, the leverage 1-20 and marginMusd >= 10 bounds, and the emphasis that idempotencyKey must be unique per intent. These go beyond the schema's field-level descriptions.

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 ('Open (or add to) a mock futures position') and immediately signals the mock/paper nature. This clearly distinguishes it from siblings like place_spot_order, open_pm_position, and close_futures_position.

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 workflow directive ('Quote first and CONFIRM with the user') and states the required scope plus the server-flag gating condition. It does not explicitly name the futures_quote sibling, but the sequencing instruction is clear enough for correct 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?

Adds substantial context beyond annotations: paper trading only (virtual mUSD), the trade:pm scope requirement, server-flag gating with a specific 403 'not enabled' failure mode, and the paper_execution_v1 fill model with a disclosed execution cost. These are exactly the behavioral traits 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?

Front-loaded with purpose and kept to a single dense paragraph where every sentence carries operational weight. Minor redundancy with the schema on required idempotencyKey and the stake minimum, but the quote/confirm instruction 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?

With an output schema present (executionModel in quote/trade results) and 100% schema coverage, return values need not be explained. The description still covers auth, gating, fill behavior, and safety posture, leaving no material gap for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description restates the side semantics (NO fills at 100 minus probability) and stake minimum, but these already live in the schema, so it adds little beyond what structured fields 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 verb (open) and resource (prediction-market position) with the scope qualifier 'binary outcomes only', which cleanly distinguishes it from open_futures_position and place_spot_order among siblings. 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 operational precondition ('Quote first and CONFIRM with the user') and a scope requirement, which routes the agent toward pm_quote before writing. It lacks explicit when-not conditions or named alternatives, but the sequencing guidance is actionable.

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

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

Goes well beyond the annotations: discloses paper-only settlement in virtual mUSD, the paper_execution_v1 fill model with a disclosed execution cost surfaced via executionModel, and the full retry contract (reuse the SAME idempotencyKey to replay the original result; it never double-executes). This is exactly the mutation/auth/retry context an agent needs for a write tool. Note the tension with idempotentHint=false: the annotation describes distinct-intent calls, while the description explains key-based replay, so this is added nuance rather than a contradiction.

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?

Seven tight sentences, all front-loaded around the action, the disambiguating coin-id warning, conditional parameter rules, the idempotency contract, and the confirmation requirement. No filler and no restatement of the title.

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 8-parameter write tool with a nested agentTrace object and an output schema, the description covers everything the schema cannot: scope requirement, confirmation policy, paper-vs-live semantics, fill model, and where to read execution cost. Return values are legitimately left to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3, but the description consolidates the conditional requirements (limitPrice for limit & stop, stopPrice for stop) and adds a high-value warning that coinId is a UCID and NOT a ticker, plus the replay semantics of idempotencyKey that the schema only states tersely.

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?

Specific verb + resource + scope: "Place a paper spot order" immediately separates it from open_futures_position, futures_quote, and spot_quote in the sibling list. The description also pins the mode (paper, virtual mUSD) so an agent cannot mistake it for a live-trading path.

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?

States the precondition (requires trade:spot scope), the human-in-the-loop requirement (CONFIRM with the user before calling), and the execution context (paper only, fills follow paper_execution_v1). It stops short of explicitly naming spot_quote as the preview step, so it is clear context rather than full when/when-not routing.

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 safety (readOnlyHint=true, destructiveHint=false), and the description adds meaningful disclosure beyond them: it is free/public, requires no API key, uses a single snapshot window (20-28h, nearest 24h), enforces a minSample threshold, and warns that lanes are not interchangeable. It does not discuss pagination or rate limits, but the added operational context is substantial.

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

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

The purpose is front-loaded in the first sentence, and subsequent sentences are dense but each adds a caveat (sample threshold, lane non-interchangeability, citation requirement). It is on the long side and could be tightened, but every clause carries distinct 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?

An output schema exists, so the description needn't detail return values, yet it helpfully defines the key fields (calibrationError scale/direction, sampleSize) and the pending/threshold behavior. Combined with full annotation coverage, this is complete enough for an agent to call and interpret the tool, with minor room to state the underlying venue list or exclusions more concretely.

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. The schema is empty at 100% coverage and the description correctly provides no parameter guidance, instead clarifying output semantics (calibrationError definition, sampleSize meaning).

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

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

The description states a specific verb+resource ('per-venue market-price calibration scorecard') and explicitly scopes what it measures versus what it does not (provider/agent forecast skill, profitability, continuous 24h history). That scoping helps separate it from other pm_data_* tools, but no sibling is named directly, so differentiation is implied rather than explicit.

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 real usage context: venues below minSample appear in `pending`, the finalPrice/ownCapture lanes are not interchangeable with the primary lane, and results should be cited with methodology and excluded counts. However, it never states when to reach for this tool versus alternatives like pm_data_overview or pm_data_canonical, so usage is inferred rather than routed.

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

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

Adds substantial behavior beyond the read-only/openWorld annotations: merged canonicals still resolve (status='merged' + mergedInto pointer, never 404s), methodology constraints ('orientation ... NEVER price-inferred'), append-only lineage semantics, and the null-when-disagreement rule for consensus. These are non-obvious operational facts an agent needs.

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

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

Dense but front-loaded: the identity statement and list/detail modes come first, with edge-case behavior (merged status, consensus nullability) afterward. Every clause carries information, though the run-on detail about consensus/listings could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even though an output schema exists (so return values needn't be described), the description previews the returned fields and edge-case behavior thoroughly. Combined with the 100% schema coverage and read-only annotations, an agent has everything needed 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 description coverage is 100%, so the schema already documents `key`, `limit`, and `cursor` including the uuid-or-slug duality. The description reinforces mode binding ('list mode only') but adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific resource (cross-venue canonical event identity) and both operating modes: omit `key` to page the active-canonicals directory, pass `key` for one canonical's full record. It clearly differentiates itself from sibling venue-specific tools like pm_data_event/pm_data_events by framing the resource as venue-independent.

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

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

Gives explicit mode selection ('Omit `key` to page...' / 'Pass `key` ... for one canonical's full record') and states the intended use case: 'track one question across venues by a durable identity instead of re-matching venue slugs yourself.' It stops short of naming the specific sibling tools an agent should prefer this over.

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

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

Goes well beyond the annotations: explains that orientation is human/aggregator-reviewed and never price-inferred, what requirePriced drops (unpriced placeholders and quote-dead pairs), what referenceProbability means, and the citation requirement. The readOnlyHint is implicit but not contradicted.

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 concept and ends with usage routing, which is good, but the middle is dense with metric names (maxOverallGap, maxOutcomeGap, maxConfidence) and parenthetical asides that would benefit from trimming or structuing.

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 9-param research tool with an output schema, this covers origin of matches, quality floor, orientation, and citation expectations. It does not need to reproduce the output schema, and nothing an agent needs is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so a baseline of 3 applies, and the prose adds real meaning for requirePriced and the divergence metrics that minDivergence and sort act on. This is a meaningful lift over the schema descriptions alone.

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: free public cross-venue disagreement clusters built from approved cross-source matches, graph-clustered so one row spans every venue. Clearly distinguishes itself from the many pm_data_* siblings by naming the matched-question clustering concept.

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

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

Explicitly routes single-outcome tradability to pm_quote and labels requirePriced=false as research/debug only, giving a clear when-not-to-use case. Still doesn't state when to prefer this over pm_data_canonical or pm_data_event for the same question.

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 the safety profile (readOnly/openWorld/non-destructive), and the description adds substantial behaviour beyond that: the default summary bounds arrays while preserving counts, hasObservedPrice:false vs omitted vs unknown, sourceObservation:null meaning 'unavailable provenance, not proof of absence', priceBasis:'unquoted' meaning never traded with no usable book, and the referenceProbability composition (liquidity-weighted median over matched real-money venues with venueCount and spreadPoints, which must be quoted together). It also discloses auth ('No API key required') and data-capture windows (volume points since 2026-07-02).

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 purpose and payload, and most parentheticals carry real semantic load. It is nonetheless a very long, heavily nested single block, and the caveat chain (hasObservedPrice / sourceObservation / priceBasis) is dense enough that a reader can lose the main thread before reaching the pm_quote routing line.

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, annotations covering safety, and 100% parameter coverage, the description supplies exactly the missing layer: field-level semantics for the ambiguous/auxiliary fields, default-vs-full behaviour, and the sibling routing rule. Nothing an agent needs to call or interpret the result 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%, so the baseline is 3. The description goes modestly beyond it by explaining what detail=full actually yields versus the bounded default summary, and by framing source as the venue key for slug resolution, but fiat is left entirely to the schema and no format/syntax detail is added.

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+keying scheme: fetch free public detail for one prediction-market event by venue + slug, then enumerates the concrete return payload (outcomes/probabilities, price snapshots, resolution evidence, crossSourceMatches, referenceProbability, whales, related events/news, volumeHistory). It explicitly separates itself from the tradability sibling: 'This is the cross-venue research view; for tradability use pm_quote.' An agent can place it against pm_data_events/pm_quote without opening schemas.

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

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

Clear usage context and one explicit alternative ('for tradability use pm_quote', plus 'No API key required'), and it gives a condition for the detail flag ('Set detail=full only when the untouched provider-rich record is needed'). It does not, however, disambiguate against the closest research siblings (pm_data_canonical, pm_data_disagreements, pm_data_events) even though it describes canonical/cross-venue concepts those tools likely own.

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/openWorldHint/destructiveHint=false, so safety is covered. The description still adds real behavioral context beyond that: the outcome-ordering rule (live quotes ahead of terminal rows), the referenceProbability and quality verdict semantics (blocked markets stay visible but cannot drive paper opens or alerts), and the no-API-key requirement. It stops short of documenting rate limits or pagination behavior.

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

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

The core scoping distinction is front-loaded well, but the single paragraph then enumerates return fields, referenceProbability internals, and quality reason codes — much of which duplicates the existing output schema. Those sentences do not earn their place given the output schema is present.

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 research/search tool with annotations and an output schema already present, the description covers routing, auth, scope, and notable response behaviors. Nothing an agent needs to select or invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds venue-scope context but no syntax or format detail for q, fiat, sort, limit, offset, source, or status beyond what the schema already documents, so it neither compensates nor regresses.

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 (search) and resource (prediction-market events) and pins the scope to ALL 12 venues, naming them explicitly. It also differentiates itself from discover_pm_markets (paper-tradeable only) and pm_data_event (all outcomes/full evidence), so an agent can pick the right tool without opening a schema.

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

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

Explicitly states when-not: 'Research/data only: to trade, use discover_pm_markets + pm_quote instead,' and routes single-event deep dives to pm_data_event. Both the alternative and the selecting condition are named, leaving nothing 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 the read-safe, open-world profile, but the description adds substantial context the annotations do not: no API key required, freshness is source-aware with per-venue lag/health, monetary totals cover real-money venues only, and aggregates are self-computed requiring attribution to CoinRithm. These are meaningful operational caveats beyond the structured hints, though it does not describe rate limits or payload shape.

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 lead sentence front-loads what the tool is and the metrics it returns, and the remaining sentences each add a distinct caveat (sibling routing, freshness, venue basis, attribution, auth). It is dense and long for a one-parameter read tool, but there is little waste.

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 re-explained, and the description covers scope, freshness semantics, monetary caveats, attribution, and auth. Combined with the schema it is essentially complete for correct invocation, with only minor ambiguity about the 'compact discovery shape'.

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?

With schema description coverage at 100% and a single optional fiat parameter already documented in the schema, the description does not need to carry parameter burden. It only implies that fiat governs monetary figures, which the schema already states, so the baseline 3 applies.

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

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

The description names a specific resource (cross-venue prediction-market statistics) and enumerates the exact metrics returned (total/open/closed market counts, total and 24h volume, liquidity) plus the full list of 12 venues. It explicitly distinguishes itself from the pm_data_event sibling, so an agent can tell them apart 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?

It names one alternative with its selecting condition: 'Use pm_data_event for full event evidence.' It also points to /api/prediction-markets/sources/health for per-venue freshness, which is real routing guidance. It does not, however, disambiguate against the many other pm_data_* siblings (volume_history, disagreements, calibration), so the guidance is clear but not exhaustive.

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 readOnlyHint/openWorldHint/destructiveHint already covering the safety profile, the description adds genuinely new behavioral context: 'Free public', 'No API key required', and that outputs carry explicit as-of timestamps and volume bases. These tell the agent about access requirements and data provenance beyond the annotations. No return-format or rate-limit detail is added, so not 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?

Two sentences, front-loaded with the resource and its contents, then the usage rule. The field enumeration is dense but each item is substantive and earns its place. Slightly list-heavy but not padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only metadata endpoint with an output schema, the description need not explain return values, and it covers scope, contents, and usage rationale. An output schema exists and annotations carry safety, so the remaining burden is low. Adequate and nearly 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 100% for the single fiat parameter, so the schema already documents it fully (default usd). The description's mention of 'currency basis' loosely relates but adds no syntax or constraint detail beyond the schema. Baseline 3 is correct 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?

The description names a specific resource (methodology and comparable coverage for every prediction-market venue) and enumerates what it returns: source kind, supported metrics, market counts, volume bases, currency basis, comparability, timestamps. That is far more than a restated name. It stops short of differentiating itself from close siblings like pm_data_sources_health or pm_data_overview, so an agent must 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?

It gives explicit, actionable context: 'Use this before comparing venue totals so a completed-day figure is never described as rolling 24h and play-money points are never described as USD.' That is clear when-to-use guidance tied to a concrete failure mode. It does not name alternatives or state when-not-to-use, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: the endpoint is free, public, and requires no API key, and it clarifies the semantics of 'freshness' relative to a quote. Return format is left to the output schema, which is appropriate.

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

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

Three sentences that front-load the resource and scope before the usage warning. Each sentence carries information, though the final 'No API key required' is a minor add-on that could be merged. No padding or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only inspection tool with an existing output schema, the description supplies everything an agent needs: what it reports, when to consult it, and its auth profile. Nothing material for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there are no parameter semantics to document and the baseline of 4 applies. No description content is needed here and none is missing.

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 (per-venue ingest health) and enumerates the outputs (freshness tier, observed lag, stale/degraded reason, coverage counts, health timestamps) with the scope 'all CoinRithm sources'. It distinguishes itself from the catalogue concept (pm_data_sources) by warning that catalogue presence alone doesn't guarantee live freshness, though it never names that sibling directly.

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 triggering condition: 'Check this before using a quote or claiming cross-venue coverage.' That is actionable when-to-use guidance. It does not name alternative tools or state explicit when-not-to-use cases, so it falls short of the top band.

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, but the description adds substantial behavior the annotations cannot: forward capture since 2026-07-02, a rolling ~90-day bound, daily UTC bucketing, per-venue bySource breakdown, and the crucial semantic that missing values are null gaps, never zero. The 'do not read a gap as zero activity' warning materially prevents misinterpretation of results.

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

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

The core definition is front-loaded and information-dense, with caveats (window, null semantics, no key) following. Overall efficient, though 'Free public' and 'No API key required' restate the same access fact and the opening sentence is heavily parenthesized.

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 no-argument aggregation tool with an output schema present, the description covers everything an agent needs: what the series means, its time bounds, granularity, venue inclusion rules, and how to interpret nulls. With the output schema carrying return structure, nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. No parameter claims are contradicted or left ambiguous.

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 (daily prediction-market volume trend) with the exact scope: cross-venue, real-money venues only, per-UTC-day granularity. An agent can distinguish it immediately from siblings like pm_data_overview, pm_data_calibration, or pm_data_sources.

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

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

Explicitly states the intended use case — 'see whether cross-venue prediction-market activity is growing or shrinking over time' — which gives clear context for selection. It does not, however, name or exclude any specific alternative sibling tool, so routing vs. pm_data_overview or pm_data_calibration is left 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, openWorldHint, and destructiveHint, so safety is covered. The description adds real behavioral context beyond that: it is free/public, needs no API key, uses a ~$1k+ notional cutoff, distinguishes wallet-attributed Polymarket rows from anonymized Kalshi prints, and cautions that a large print is information, not a recommendation.

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

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

Three tight sentences, front-loaded with the resource and scope, each carrying distinct value (what it is, source caveats, disclaimers). No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tape tool with an output schema and full annotation coverage, the description is nearly complete. The field list slightly duplicates the output schema, but the venue/attribution caveats and threshold make it sufficiently informative for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single, fully documented 'limit' parameter (1-50, default 10), so the schema does the heavy lifting. The description adds no additional parameter meaning, making the baseline 3 correct.

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 clearly: a tape of the latest large prediction-market trades across venues, with an explicit $1k+ notional threshold and 'newest first'. It is distinct from siblings like pm_data_overview or pm_data_events, though it never names the closest alternatives (pm_data_whale_wallet/wallets) to explicitly distinguish scope.

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 'latest large trades, newest first' framing and the notional threshold, but there is no explicit when-to-use, no when-not-to-use, and no routing to the sibling whale-wallet tools for per-wallet views. The agent must infer the niche from context.

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/non-destructive/open-world, and the description adds real contextual value: no API key required, the distinction between matched-trade flow fields and separately-sourced provider positions/PnL, as-of markers, and the caveat that 'absence of a row is not proof of inactivity.' That is meaningful disclosure beyond the annotations, though it stops short of rate limits or caching 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?

Purpose is front-loaded in the first sentence and every sentence carries information. The middle sentences on CoinRithm flow fields and provider PnL are dense but earn their place; nothing is purely 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 not be spelled out, and annotations cover safety, so the remaining burden is usage routing, which is only implicit. For a two-param read tool this is close to complete, missing only explicit when-to-use guidance versus sibling whale tools.

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 both params are fully documented in the schema (venue enum, address pattern, provenance of the address). The description's phrase 'one supported ... venue and address' merely restates the two params without adding format or semantics beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('wallet movement detail for one supported on-chain prediction-market venue and address') and constrains scope to a single wallet, which distinguishes it from the sibling list tool pm_data_whales. An agent can tell what it retrieves 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?

The description implies usage (free public single-wallet lookup) but never explicitly says when to reach for this versus pm_data_whales or pm_data_whale_wallets, nor any prerequisite beyond 'no API key.' The routing hint exists only in the wallet param schema, not in the tool description.

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

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

Annotations already cover readOnly/destructive/openWorld, so the bar is lower; the description adds genuinely useful behavioral context beyond them — free, no API key, default window, and crucially the coverage limitation that anonymized venues and unavailable feeds are excluded, so an absent wallet is not proof of absent trading. It stops short of describing pagination or rate limits, but the caveats it does disclose are valuable.

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 what the tool returns, then the caveats and the no-key note. Five sentences is on the long side but each carries distinct information; nothing is redundant with the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value documentation is not strictly required, and the description nonetheless names the returned fields. It covers caveats and access constraints well. The one omission is sibling differentiation against the other whale tools, which leaves an agent without a clear selection rule.

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, source, and window with defaults and enums. The description only echoes the default window and the venue-address restriction, adding little beyond the schema. 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?

States a specific verb and resource: aggregation of identifiable large-trader wallet activity for prediction markets over a 7d/30d window. It is clear on what is produced (trade count, notional, venue attribution, timestamps). However, it never differentiates itself from the close siblings pm_data_whales and pm_data_whale_wallet, which an agent must distinguish by name alone.

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 description gives implied context (market context, not a recommendation) but no explicit 'use this when' guidance or alternatives. With pm_data_whales and pm_data_whale_wallet in the sibling set, the absence of routing guidance is a real gap.

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 annotations: 'Never mutates state', paper-trading-only (virtual mUSD), fills follow paper_execution_v1 with a disclosed execution cost, min-to-open is 10, and it discloses specific 422 reject codes (quality_state_missing, quality_state_stale, quote_dead, stale_freshness). This is exactly the kind of behavioral context annotations cannot carry.

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

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

Front-loaded with the purpose and scope before the long field enumeration, and every sentence carries substantive information. It is dense and the list of decisionSupport/quality subfields partly duplicates what the output schema already exposes, keeping it short of 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?

For a read tool with 8 params, an output schema, and nested objects, the description covers intent, trade-safety semantics, gating behavior, execution model, and error previews. Nothing an agent needs in order to invoke and interpret it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so baseline is 3, but the description adds real meaning: the stakeMusd > 0 floor plus the 'min to open is 10' threshold and the side='no' payoff/fill mechanics (fills at 100 minus probability, pays if resolved false), which are not stated in the schema for the minimum.

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 ('Read-only PM quote for a binary outcome') and enumerates the quote's contents, so an agent can immediately tell it apart from pm_data_* reads and from open_pm_position.

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

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

Explicitly names the related sibling and the condition that routes to it: when openBlocked is true, open_pm_position would be rejected 422 with the stored reason codes, making this a pre-trade gate preview. It doesn't state when NOT to use this tool versus the pm_data_* family, so it stops short of a 5.

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

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

Annotations cover only the generic write/non-destructive profile, and the description adds the operationally critical details: it never moves paper funds, requires the read scope, does not verify the caller's evaluation, the first stored record wins on retries, and a network error does not prove rejection. It even explains the idempotentReplay/decisionUuid return semantics, none of which annotations 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?

Dense but front-loaded, leading with what gets written and the safety boundary before enumerating the kind choices and retry semantics. Every sentence carries information, though it is on the longer side for a single tool description.

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 12-parameter write tool with nested objects, the description covers the mutation semantics, scope requirement, retry/idempotency behavior, success-confirmation guidance, and the sibling alternative. An output schema exists, yet the return fields are still summarized, leaving no material 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 100% so the baseline is 3, but the description adds genuine meaning: forecastProbability must be the caller's own (1-99) and never the market price, cohort.universeSize records cohort breadth, and decisionId must be reused for retries with an agentTrace.decisionId fallback. These rules go beyond the schema text.

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: saves a durable SELF-REPORT of a PM evaluation for a decision that did not open a position. It is clearly distinguishable from open_pm_position, which it explicitly names as the tool for the opposite case (actually placing a paper 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?

Explicitly covers when to use it (non-opened evaluations), how to choose among the three kinds (abstained / forecast_only / quote_expired, with the forecastProbability requirement called out), and the alternative (open_pm_position) for the case where a trade is actually placed.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: paper trading only (virtual mUSD), fills follow paper_execution_v1 with a disclosed execution cost, and executionModel appears in quote/trade results. Some of that execution detail belongs more to the trade tools than to a resolver, but the environment constraint is useful.

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, followed by usage routing, then environment notes — a sensible order with minimal waste. The trailing sentence about paper_execution_v1 and execution cost is slightly tangential for a pure resolution tool, trimming it to a 4.

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 needn't be re-explained, and the description covers purpose, usage ordering, and environment. The only soft spot is that the execution-cost sentence is more relevant to downstream quote/trade calls, but it does no harm.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both `q` and `agentTrace` (with its nested fields) are already documented in the schema. The description's format examples ('BTC', 'ethereum') restate what the schema provides, adding little beyond the baseline.

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

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

Specific verb+resource: 'Resolve a human symbol / slug / name ... to a CoinRithm coinId (UCID) plus disambiguating alternatives, each with its CoinGecko category tags.' It clearly names its output and its role relative to the wallet/quote/order tools, so an agent can distinguish it from siblings 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?

'Use this FIRST to get the coinId that the wallet / quote / order tools need — don't guess UCIDs (symbols are not unique)' gives explicit ordering, names the dependent tools, and states an exclusion (don't guess). Nothing about when to invoke is left to inference.

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

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

Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=false) by disclosing that a per-minute worker fires off the live mark, that liquidation takes precedence, that a fire closes the FULL position at mark with realized PnL, that fills between polls surface via my_trades with updatedSince, and that execution follows paper_execution_v1 with a disclosed cost. This is unusually rich operational context.

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

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

Dense but front-loaded: the core action and trigger semantics come first, then firing behavior, then scope/paper-mode caveats. Some clauses (agentTrace is not mentioned at all, executionModel pointer) could be trimmed, but each sentence carries real information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need no explanation, and the description covers the remaining gaps an agent needs: side-aware constraints, firing mechanics, scope, paper-trading status, and the execution-cost model.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, and the schema already states 'positive sets; null clears; omit = unchanged'. The description adds genuine value beyond that with the side-aware ordering constraint (long: liq < SL < mark < TP; short inverted), which the schema does not encode.

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