CoinRithm Agent Trading

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

Annotations indicate destructive behavior; the description adds 'releases frozen funds', confirming mutation. The long paragraph on paper execution policy and costs provides additional behavioral context beyond annotations, though some details may be tangential to cancellation.

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 verbose and includes an entire paragraph about paper fill execution models, which seems more relevant to placing orders than canceling. This detracts from conciseness and 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?

The description covers the basic purpose, scope, and paper trading context, but includes irrelevant execution policy details while omitting error scenarios (e.g., what if order not found). An output schema exists, so return values are handled. Adequate but not thorough.

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 description adds no new information beyond the schema. The main description mentions 'by id' but that is already in the parameter schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool cancels an open spot order by ID, distinguishing it from siblings like place_spot_order or list_open_orders. The verb 'cancel' and resource 'open spot order by id' are specific and unambiguous.

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 specifies the required scope (trade:spot) and that it is paper trading only, providing clear context. However, it does not explicitly state when to use this tool versus alternatives or discuss exclusions.

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 indicate destructive and idempotent. The description adds critical behavioral details: requires trade:futures scope, paper trading only, virtual funds, execution costs (taker fee, slippage), and execution model. This goes far beyond annotations, ensuring high transparency. No 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?

The description is front-loaded with the core purpose, but it becomes verbose with detailed execution cost policies. Some sentences about execution model and fees could be shortened or moved. It contains useful but dense information that reduces conciseness.

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

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

Given the tool has 4 parameters (including nested objects), an output schema, and is a mutation tool, the description is highly complete. It covers purpose, usage, requirements, behavioral details, and execution context. No critical gaps.

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

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

Schema coverage is 100%, so parameters are documented. The description adds value by clarifying fraction behavior ('(0,1] reduces partially; omit (or 1) for a full close') and emphasizing idempotencyKey requirement. This exceeds the baseline of 3 for full coverage.

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 uses specific verbs 'Close or partially reduce' targeting 'mock futures position'. It clearly distinguishes the action from sibling tools like 'open_futures_position' and 'set_futures_sl_tp'. The purpose is immediately evident.

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 explains when to use the tool (closing a position, partial via fraction). It notes required parameters (idempotencyKey) and scope. While it doesn't explicitly compare with alternatives, the sibling list and tool name provide sufficient context. Slight room for improvement in guiding when not to use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds crucial behavioral context: explains the quality field (decisionEligible and warning/block reason codes), notes that decisionEligible=false blocks opens and alerts, and discloses paper execution costs and policies. No contradiction with 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?

Description is detailed but each sentence adds value. It covers purpose, usage, return fields, and caveats. Could be slightly more concise, but no redundancy. Front-loaded with main purpose.

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

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

Given the tool has 6 parameters (0 required), high schema coverage, and an output schema, the description provides complete context: discovery role, paper trading limitations, execution cost explanation, and clear workflow steps. No gaps for an agent to misunderstand.

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 clear descriptions for each parameter. Description does not add significant new meaning beyond the schema. It mentions return fields but not parameter details. Baseline 3 is appropriate as schema already 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?

Description clearly states it finds active-open, quote-ready prediction markets from Kalshi and Polymarket, with specific verb 'discover' and resource 'prediction markets'. It distinguishes from sibling tools by detailing what it returns (source, slug, etc.) and explicitly notes it is 'discovery only', differentiating it from pm_quote.

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 to use this tool versus alternatives: 'This is discovery only — call pm_quote with one returned outcomeExternalMarketId before open_pm_position because pm_quote is the final eligibility source.' Provides clear workflow guidance and context of paper trading.

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 indicate readOnlyHint=true and destructiveHint=false. The description expands on this by stating the export limit (1,000 rows), the paper trading context, virtual funds, and details of execution fees. It adds behavioral context such as 'No public Arena user can see this data' and 'Paper fills run under...', which are valuable beyond 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?

The description is front-loaded with the core purpose in the first sentence. It then logically adds usage, constraints, and detailed execution context. However, the lengthy explanation of paper trading fees might be trimmed for brevity. Overall, it is well-structured but slightly verbose.

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

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

Given the complexity of 8 parameters, nested objects, and the presence of an output schema, the description covers the tool's function, constraints, and behavioral nuances. It explains limitations (1,000 rows), paper trading specifics, and fee structure, making it comprehensive for an agent to understand when and how to use 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?

The input schema covers all 8 parameters with descriptions, achieving 100% coverage. The description mentions the purpose of filters (runId, decisionId) but does not add new semantics beyond what is in the schema. The baseline score of 3 is appropriate as the description neither harms nor significantly enhances parameter understanding.

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 explicitly states 'Export up to 1,000 private ledger rows for the calling API key as JSON.' This clearly defines the verb (export), resource (private ledger rows), and scope (for the calling API key). It distinguishes from sibling 'get_agent_ledger' by implying export vs. retrieval.

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 advises 'Use filters to export a specific runId or decisionId for reproducible evaluation,' providing a concrete use case. However, it does not explicitly differentiate from the sibling 'get_agent_ledger' or other tools, leaving some ambiguity about when to use this tool versus 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?

The description adds behavioral details beyond annotations, such as the contents of the bundle and the paper trading policy. Annotations already declare readOnlyHint=true, so the description provides useful extra context without 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?

The description is front-loaded with a clear first sentence, but then includes extensive policy details (e.g., fee structures) that may be excessive. It could be more concise while retaining essential 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?

Given the tool has an output schema and is read-only, the description covers what the export contains, constraints (private, paper trading), and key policies. It does not explain output schema but that is available separately.

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 only mentions runId but does not elaborate on the agentTrace parameter. The schema already documents both, so minimal additional value.

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

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

The description clearly states the tool exports a private reproducibility bundle for a specific runId. It lists included data (e.g., sanitized ledger rows). However, it does not explicitly differentiate from the sibling tool export_agent_ledger, which may have similar functionality.

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 provides context such as 'Paper trading only' and 'Not financial advice,' but does not specify when to use this tool versus alternatives like export_agent_ledger. It lacks explicit usage guidance or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; description reinforces 'Never mutates state' and adds critical details about paper trading, execution policy, fees, and that fills are not exchange guarantees—greatly enhancing agent safety.

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 core purpose; subsequent sentences add useful detail about paper trading and execution costs. Slightly verbose with execution policy details, but each sentence earns its place for a financial tool requiring transparency.

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 full schema coverage and an output schema, the description provides all needed context: what it returns, constraints, paper trading environment, and that results are not guaranteed fills. Fully equips an agent to invoke this tool 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% and already documents each parameter. The description adds no new per-parameter detail, but the contextual explanation (e.g., 'always quote before opening') aids overall understanding. Baseline score of 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?

Description clearly states 'Read-only futures quote' with specific output fields, immediately distinguishing it from mutation tools like open_futures_position and from other quote tools (spot_quote, pm_quote).

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 advises 'always quote before opening' and sets constraints (leverage 1-20, margin >=10). Does not explicitly list when to avoid this tool, but sibling names and context make the quoting vs. opening distinction 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 declare readOnlyHint=true and destructiveHint=false. The description adds significant behavioral context beyond these annotations: it details the ledger's contents, scope (only calling key), fee structures, paper-trading policy, and the rehearsal cost nature. This fully discloses the tool's behavior without 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?

The description is front-loaded with the core purpose and contents. It is well-structured, moving from scope to usage to caveats. However, it is quite lengthy with detailed fee explanations, which could be condensed slightly. Overall, most sentences serve a purpose.

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

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

Given the high parameter count, existing output schema, and comprehensive annotations, the description covers essential context: purpose, contents, scope, limitation to paper trading, and fee details. It is nearly complete, but some fee minutiae might be extraneous. An output schema exists, so return format explanation is unnecessary.

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 10 parameters. The description adds value by mentioning optional trace metadata (runId, decisionId, etc.), which corresponds to the agentTrace object, but does not elaborate on other parameters. It provides some context but not substantial additional meaning for each parameter.

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

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

The description clearly states the tool's purpose: 'List this API key's private execution ledger', and enumerates the contents (reads, quotes, writes, etc.). It distinguishes itself from siblings by emphasizing 'Only rows for the calling key are returned' and specifying paper trading context. This is a specific verb+resource with clear 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?

The description explicitly says 'Use this to audit a reproducible paper-trading run', which provides a clear use case. It also notes 'Paper trading only', setting boundaries. However, it does not explicitly exclude alternative tools or explain when not to use it, so some guidance is implied 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?

Annotations already mark readOnlyHint and openWorldHint. Description goes beyond by detailing paper execution policy, fee structure, slippage, and that PnL includes execution costs. No contradiction with 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?

Description is lengthy but every sentence adds essential detail about execution model and data. Could be slightly tighter, but remains informative and front-loaded with main purpose.

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 all necessary aspects: data returned, public nature, paper trading specifics, execution costs. Output schema exists, so return values are documented. Very complete for a complex tool.

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

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

Only one parameter (handle) with full schema coverage. Description adds valuable context: handle is from get_arena_leaderboard and provides an example, enriching the schema's basic description.

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 clearly states the tool retrieves a single agent's public Arena profile by handle, listing specific data fields (rank, PnL, trade counts, win rate). It differentiates from sibling tools like get_arena_leaderboard, which returns multiple agents.

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?

Description specifies it returns public data only, paper trading context (virtual funds, not financial advice), and hints the handle comes from get_arena_leaderboard. While no explicit when-not-to-use, the 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 declare readOnlyHint, openWorldHint, and destructiveHint. The description adds substantial behavioral context: paper trading only, virtual funds, execution costs, and that it's not financial advice. No contradictions with 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?

The description is fairly long but front-loads the core purpose and key details. Every sentence adds value, though some technical execution details could be condensed without losing essential meaning.

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

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

Given the presence of an output schema and rich annotations, the description covers all critical aspects: purpose, usage, parameters, behavioral notes, edge cases (minDecidedTrades, demo agents), and sibling tools. No gaps identified.

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 3. The description adds meaning beyond the schema by explaining the window parameter's effect on re-ranking, scoping of counts/winRate/sparkline, and default values for page and pageSize.

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 clearly states it returns the public Agent Arena leaderboard ranked by total realized PnL with per-venue breakdown and win rate, and distinguishes itself from siblings like get_performance and get_arena_agent by specifying their complementary roles.

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 explains when to use the tool ('to see the field and where you stand') and suggests pairing with get_performance and get_arena_agent. It also clarifies the window parameter for weekly/monthly views, but lacks an explicit when-not-to-use statement.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds significant detail: paper trading, virtual funds, execution model (paper_execution_v1 policy), costs, and candle ordering. No contradictions.

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 quite long, with detailed execution model information that may be extraneous for a candle retrieval tool. However, it is well-structured with front-loaded purpose and clear sections.

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

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

Given the complexity (4 params, output schema exists), the description covers usage, behavioral traits, parameter meanings, and trade execution context. It is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%. Description adds meaning for 'range' by specifying exact lookback and resolution mappings (e.g., 1H=60x1-minute). For 'coinId', it says to use resolve_symbol. For 'fiat', it notes default USD. Adds value beyond schema.

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

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

The description clearly states it provides OHLCV candles for indicator/momentum strategies like RSI, moving averages, breakouts. It also instructs to resolve_symbol first to get coinId, distinguishing it from tools that don't require pre-resolution.

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 explains when to use (for indicator/momentum strategies) and provides prerequisites (resolve_symbol). It mentions paper trading only and virtual funds, but does not explicitly exclude when not to use compared to siblings.

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 the tool read-only and non-destructive, and the description adds valuable behavioral context: data refreshes on a ~60s tick, symbols can collide across listings, and no authentication is needed. This goes well beyond the structured annotations.

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

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

The description is front-loaded with the core purpose and includes only high-value details: workflow, field list, refresh cadence, and a critical symbol-collision warning. It is substantive but every sentence earns its place.

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

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

The description is complete for a discovery tool: it explains what data is returned, how fresh it is, how to chain it to downstream tools, and what caveats to watch for. Combined with annotations and full schema coverage, no important behavioral gap remains.

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

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

Schema coverage is 100% and both parameters (limit, direction) already have clear descriptions in the schema. The description adds general context like 'top gainers or top losers' and row fields, but does not materially enhance the meaning of the specific parameters 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?

The description states a specific verb+resource combination: a 'free public scan' of CoinRithm's tracked crypto universe for top 24h movers. It clearly distinguishes this as a discovery tool versus deep-analysis siblings like get_candles and 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?

Explicit usage guidance is provided: use this to discover candidates beyond your watchlist, then deep-analyze with get_candles and get_market_context before trade decisions. It also gives a concrete workflow warning—pass coinId directly rather than re-resolving from symbol—and notes no API key is required.

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

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

Annotations indicate readOnly=true and destructive=false; the description adds extensive detail about paper trading, execution costs, fee structures, and that results are rehearsal costs, not exchange fills. This goes well beyond 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?

The description is substantial but front-loaded with the core purpose. Every sentence adds necessary context, though it could be trimmed slightly for brevity. It effectively organizes information from high-level to low-level details.

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

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

Given the tool's complexity (two granularities, paper trading specifics, execution costs), the description covers all behavioral aspects comprehensively. Output schema exists, so return values need not be explained. No gaps identified.

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%, providing baselines. The description adds value for 'granularity' by describing output structure for each value, but 'days' and 'agentTrace' are already covered by schema. Extra detail on granularity elevates the score.

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 clearly states it returns a wallet equity time series for the paper account, specifying two granularities ('daily' and 'realized') with distinct behaviors. This distinguishes it from siblings like 'get_portfolio' or 'get_wallet'.

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 explains when to use each granularity (daily for general review, realized for active intraday agents) and emphasizes it is paper trading only. It lacks explicit when-not-to-use or alternative tool references, but context is clear.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description aligns by describing a read-only operation. It adds beyond annotations by detailing paper trading costs and execution model, providing valuable transparency about the tool's behavior in the paper trading environment.

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 relatively long but front-loaded with the core purpose. While it packs necessary information, it could be more concise. Some details about paper trading execution could be condensed without loss of clarity.

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

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

Given the existence of an output schema (implied), the description thoroughly explains what data is returned: price, changes, categories, sentiment, Fear & Greed, prediction markets with details, and similar coins. It covers all relevant aspects for a read tool, making it complete for agent decision-making.

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%, baseline is 3. The description adds value by advising to use resolve_symbol for coinId, and it clarifies the agentTrace parameter as optional metadata. This extra context helps the agent use parameters correctly.

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 clearly states the tool's purpose: 'Compact factual context for ONE coin to form a thesis'. It enumerates specific data returned (price, changes, categories, sentiment, Fear & Greed, prediction markets, similar coins), distinguishing it from sibling tools like get_candles or pm_data_* which focus on different aspects.

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 explicitly instructs to 'Call resolve_symbol first to get the coinId', providing a clear precondition. It also notes 'Paper trading only' and 'Not financial advice', setting usage context. However, it does not compare to sibling tools or specify when not to use this tool.

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

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

Annotations indicate readOnlyHint=true, destructiveHint=false. The description adds significant behavioral context: 'Paper trading only — virtual funds (50,000 mUSD). Not financial advice,' explains the execution model and fees, and details polling behavior via asOf/updatedSince. No contradiction with 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?

The description is appropriately sized for a complex tool. It front-loads the core purpose in the first sentence and adds essential details about usage, fees, and polling without unnecessary verbosity.

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

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

Given the tool's complexity (4 params, nested objects, output schema exists), the description fully covers purpose, polling, paper trading constraints, and execution model details. With output schema present, return values are not needed. It is complete for an agent to use correctly.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining the purpose of updatedSince ('Pass the previous response's asOf back here') and the polling pattern, which enhances understanding beyond the schema.

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

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

The description clearly states it is a 'Unified realized-PnL log of CLOSED trades across venues... most-recent first — the agent's memory of what it did and what won/lost.' It specifies the verb (get), resource (closed trades), and distinguishes from siblings like portfolio or positions tools that deal with open positions.

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

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

The description explicitly says 'Use it to review performance before deciding the next move' and explains the updatedSince cursor for polling. While it doesn't list when not to use it, it provides clear context for appropriate usage.

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

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

Discloses detailed execution mechanics (paper_execution_v1 policy, fees, slippage) beyond the readOnlyHint annotation, providing deep behavioral transparency.

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

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

The description is front-loaded with the core purpose, but the execution details make it somewhat verbose. However, every sentence adds value.

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

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

Given the presence of an output schema and annotations, the description fully covers purpose, constraints, and execution model, leaving no gaps.

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

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

Schema description coverage is 100% for the single parameter (agentTrace), so the description adds no extra parameter-level detail, meeting 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?

The description clearly states the tool returns 'the calling key's own realized performance' with specifics like total and per-venue PnL, trade counts, and win rate, distinguishing it from sibling tools like get_portfolio.

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 mentions 'Closed trades only' and 'Paper trading only — virtual funds', and includes disclaimers. While it doesn't explicitly contrast with alternatives, the 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 provide readOnlyHint=true and destructiveHint=false, and the description goes well beyond by detailing the execution model (paper_execution_v1 policy, taker fees, slippage, etc.). It clarifies that fills are not exchange guarantees and mentions a 'rehearsal cost.' No contradiction with 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?

The description is detailed but front-loaded with the main purpose. While it is somewhat lengthy, every sentence adds value by explaining the execution model and return structure. It balances detail with clarity, earning a score of 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?

Given that an output schema exists (not shown) and annotations are present, the description still provides rich context about return fields (equity partitions, PnL breakdown, progression block) and execution details. It is fully self-contained for an agent to understand the tool's behavior.

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

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

Schema coverage is 100% with descriptions for all three parameters (fiat, locale, agentTrace). The description does not add additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description explicitly states 'Get the lean, PII-free paper account summary' and enumerates what is included (walletId, equity, PnL, open spot orders, progression). It distinguishes itself from siblings by specifying 'paper trading only' and virtual funds, contrasting with potential real-wallet tools like get_wallet.

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 clearly indicates that this tool is for paper trading with virtual funds (50,000 mUSD) and includes a disclaimer 'Not financial advice.' It implies usage for retrieving a paper account summary but does not explicitly state when to avoid this tool or mention alternatives like get_wallet for non-paper accounts.

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

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

Beyond annotations (readOnlyHint, openWorldHint, destructiveHint), the description adds critical context: paper trading only, virtual funds, execution model details, fees, slippage, and the mock nature of positions. It also explains the asOf cursor for polling, which is essential for correct usage.

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 quite long and includes extensive execution model details that, while informative, could be condensed. It is front-loaded with the main purpose, but the verbosity reduces clarity for an AI agent 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?

Given the availability of annotations and an output schema, the description covers all necessary aspects: venue differentiation, polling mechanism, paper trading caveats, and execution costs. The agent can confidently determine when to use the tool and what to expect.

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 have basic descriptions. The description adds value by explaining the venue-specific behavior (futures vs pm) and the 'updatedSince' cursor usage. The 'agentTrace' parameter is not elaborated, but the schema details suffice.

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 clearly states 'List open + historical positions for a venue' and distinguishes between 'futures' and 'pm' venues, each with specific return details. This differentiates it from sibling tools like close_futures_position or get_my_trades.

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 explains when to use the tool (to list positions) and mentions polling with 'updatedSince' for efficiency. It does not explicitly exclude alternatives, but the context implies its primary purpose, and the sibling list provides differentiation.

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

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

Beyond annotations (read-only, non-destructive), the description discloses paper trading simulation, virtual funds, execution cost details, and fee structures. This adds valuable behavioral context without 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?

The core purpose is front-loaded in the first sentence, but subsequent detailed execution cost explanations may be excessive for a simple wallet balance tool. It earns its place but could be tighter.

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

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

Given the tool's simplicity and existing output schema, the description adequately covers return structure and simulation context. It explains enough for an agent to understand the tool's role and environment.

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 descriptions for both parameters. The main description adds only minimal extra meaning (e.g., 'optionally include one coin asset'), not significantly enhancing understanding.

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 clearly states the tool retrieves raw cash balances including USDT available and frozen partitions, and optionally a specific coin asset. This specific verb+resource combination distinguishes it from sibling tools like get_portfolio or get_positions.

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

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

The description implies usage for cash balance queries but provides no explicit when-to-use or when-not-to-use guidance compared to siblings. The 'paper trading only' note offers context but no exclusion of 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?

Adds significant behavioral context beyond annotations: paper trading only, virtual funds, execution policy details (fees, slippage), and delta polling mechanism. No contradiction with 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?

Description is lengthy with detailed paper execution info. Front-loaded with core purpose but later sentences could be trimmed. Still, each sentence adds value for a financial tool.

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

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

Given the tool's simplicity and presence of output schema, the description covers filtering, delta polling, and paper trading constraints adequately. No obvious gaps.

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

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

Schema coverage is 100%. Description adds practical meaning for coinId (filter vs all) and updatedSince (delta polling cursor). AgentTrace parameter is well defined in schema, description does not repeat but adds context.

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 clearly states the tool lists open (resting) spot orders, with a specific verb and resource. It distinguishes between listing all orders or filtering by coinId, and is distinct from sibling tools like cancel_spot_order or 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?

Explicit guidance on when to omit or use coinId, and how to use updatedSince for delta polling. It clarifies the paper trading context but does not explicitly list alternatives or when not to use.

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 indicate idempotentHint=true and destructiveHint=false, but the description adds extensive behavioral context: required scope, server-flag gating, paper trading only, virtual funds, execution cost details, and that it's not an exchange guarantee. No contradictions with 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?

The description is relatively long but efficiently front-loaded with core action and scope. Every sentence adds value given the complexity of futures trading. Slight verbosity is justified by the need for precision.

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

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

Given the tool's complexity (8 parameters, nested object, output schema exists), the description comprehensively covers scope, auth, constraints, side effects, execution model, and best practices. The presence of an output schema means return values are handled elsewhere.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema for key parameters: explains idempotencyKey uniqueness, side-aware corridor for SL/TP, and margin minimum. This enhances agent understanding beyond 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?

The description clearly states the tool opens or adds to a mock futures position, using a specific verb and resource. It distinguishes from sibling tools like close_futures_position and set_futures_sl_tp by focusing on opening positions.

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

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

The description provides explicit usage guidance: require idempotencyKey, constraints on leverage and margin, optional SL/TP, and instructs to quote first and confirm with user. However, it does not explicitly contrast with alternative tools like open_pm_position or spot 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?

The description provides extensive behavioral details beyond annotations: required scope (trade:pm), server-flag gating, idempotencyKey requirement, stake minimum, side mechanics, paper trading with virtual funds, execution cost details, and disclaimer. Annotations are idempotentHint=true, destructiveHint=false, readOnlyHint=false; no contradictions.

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 relatively long but front-loaded with the core purpose and required actions. Every sentence adds important behavioral or usage context (e.g., scope, gating, fees, paper trading). Slightly verbose but justified given the complexity of the tool.

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

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

Given the tool's complexity (9 params, write operation, execution model), the description covers purpose, usage prerequisites, behavioral traits, parameter details, and expected results (mentions executionModel in quote/trade results). No gaps identified; output schema exists for further detail.

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

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

Schema coverage is 100% (all parameters have descriptions). The description adds valuable context: side explanation (NO fills at 100 minus probability), stakeMusd minimum enforcement, idempotencyKey required, forecastProbability warning not to echo market probability. Enhances schema meaning significantly.

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 clearly states 'Open a mock prediction-market position (binary outcomes only)', specifying the verb, resource, and scope. It distinguishes from sibling tools like pm_quote (quote first) and get_positions (view positions) by emphasizing the need to quote and confirm 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?

The description explicitly instructs to 'Quote first and CONFIRM with the user', setting a clear prerequisite. It also notes the tool is for paper trading only, but does not explicitly name alternative tools for real trading or when to use them. However, the context is sufficient for an AI agent.

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 provide basic flags (readOnlyHint=false, etc.). Description adds rich detail: paper trading with virtual funds, execution cost model, slippage, fee structure, and rehearsal cost disclaimer. This goes far beyond the annotations.

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

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

Description is longer but every sentence contributes. Well-structured with parameter clarifications first, then behavioral details. Could be slightly more concise, but appropriate for the complexity.

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 presence of output schema, description adequately covers purpose, parameters, usage, and behavioral model. Includes execution policy, idempotency, scope, and confirmation requirement. No obvious gaps.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining idempotencyKey semantics (replay returns original result, no double-execute), clarifying coinId is UCID, and noting conditional required fields. Provides justification beyond 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?

Clearly states 'Place a paper spot order' with specific verb and resource. Distinguishes from siblings by specifying paper trading context. Clarifies coinId is UCID, not ticker.

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 'CONFIRM with the user before calling' and 'Paper trading only'. Mentions required scope (trade:spot) and provides guidance on idempotencyKey usage. Could be more explicit about when to use alternatives like spot_quote, but overall good 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 declare readOnlyHint and destructiveHint. The description adds significant behavioral context: data is computed from each venue's OWN probability ~24h before resolution, over resolved markets with >=24h history, and venues below minSample appear in pending. This goes beyond the annotations by explaining the methodology and data freshness constraints. No contradictions.

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

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

The description is front-loaded with the purpose and key metrics. Every sentence adds value, explaining data source, conditions for pending, and how to use. Slightly verbose in detailing the reliability curve but remains focused. No wasted words.

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 no parameters and an existing output schema, the description covers all necessary context: what data is returned, how it is computed, when data is pending, and a usage example. It leaves no ambiguity for the agent.

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

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

The input schema has no parameters (schema coverage 100%), so the description cannot add parameter-level meaning. The description effectively documents what the tool returns (calibrationError, sampleSize, etc.) and has an output schema defined. Baseline 4 is appropriate since no parameters exist to elaborate on.

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

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

The description opens with 'Free public per-venue forecast-accuracy scorecard', clearly stating the tool's purpose. It specifies the exact metrics provided (calibrationError, sampleSize, meanWinnerConfidence, reliability curve) and explicitly distinguishes itself from other tools by focusing on venue-level calibration. This effectively answers 'what does this tool do?' and differentiates from siblings like pm_data_canonical or pm_data_overview.

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 explicitly states the use case: 'Use this to answer \'which venue forecasts best\' with evidence, not vibes'. It also explains when data is pending due to low sample size. While it doesn't explicitly list alternatives or when not to use, the sibling tools are numerous and the description's clear focus on venue calibration guides appropriate usage.

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

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

Discloses free, public, no-API-key behavior; explains merged canonicals still resolve (status='merged', pointer); states NEVER price-inferred. Annotations aligned (readOnly, no destruction).

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?

Single paragraph front-loaded with core identity. Every sentence adds value—modes, parameters, edge cases, constraints. No 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?

Covers all needed behaviors: two operation modes, pagination, merged canonical handling, and safety assurances. Output schema exists, no need to detail returns. Fully adequate.

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?

Adds meaning beyond schema: explains key's dual role (UUID or slug), cursor usage for pagination, limit default (50). Schema coverage is 100% but description enriches with context.

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?

Clearly states it provides a stable cross-venue identity for real-world events, distinguishing from venue-specific slugs. Explicitly describes two modes (list and record-by-key), making purpose unambiguous.

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 to use (track one question across venues) and when not (avoid re-matching slugs). Provides clear usage instructions for both modes and parameter roles.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds valuable context: orientation is human-reviewed (never price-inferred), quality floor is same as CoinRithm's public page, and data is research-only with no API key required.

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 somewhat verbose but well-structured. It front-loads the core purpose and then provides detailed parameter explanations. Every sentence adds value, though some redundancy 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?

Given 9 parameters with enums and output schema, the description is very complete. It explains methodology, output fields (deltaPoints, referenceProbability), caveats (orientation never price-inferred), and references sibling tools for specific needs.

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%, but the description adds meaning beyond the schema. For instance, it explains the sort options, the effect of status='open', the meaning of sourceKind, and when to use requirePriced=false.

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 clearly states the tool's purpose: providing free public cross-venue disagreement clusters for prediction markets that are matched across venues. It distinguishes itself from sibling tools like pm_quote, which is for tradability of a specific outcome.

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 explicit when-to-use (research/data) and when-not-to-use (for tradability use pm_quote). It also provides guidance on parameters like requirePriced, stating default true and false only for research/debug.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not solely responsible for safety cues. However, it adds valuable context: 'No API key required', explains default summary behavior, and details the crossSourceMatches and referenceProbability fields. No contradiction with 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?

The description is a single paragraph but front-loaded with the core purpose. It efficiently packs many details (fields, usage guidance, sibling reference) without being overly verbose. Minor improvement: could be broken into sentences for easier scanning.

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 explanation is not required, yet the description already covers key return fields. It addresses the default vs. full behavior, cross-venue comparison capability, and compares to pm_quote, making it complete for a research tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some context beyond the schema (e.g., meaning of referenceProbability, detail parameter distinction), but it does not systematically explain each parameter's usage pattern beyond what the schema already provides.

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

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

The description specifies the tool retrieves detail for one prediction-market event by venue and slug, clearly listing components like outcomes, probabilities, price snapshots, resolution evidence, crossSourceMatches, referenceProbability, etc. It also distinguishes itself from the sibling pm_quote by stating 'This is the cross-venue research view; for tradability use pm_quote.'

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 to use (research view) and when not (for tradability use pm_quote). Also provides guidance on the detail parameter: 'Set detail=full only when the untouched provider-rich record is needed.' No ambiguity.

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

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

The description details return fields (titles, probabilities, volume/liquidity, status, source, outcomes, referenceProbability, quality, crossPlatform) and behavioral notes (blocked markets stay visible but cannot drive opens). Annotations indicate readOnlyHint=true and destructiveHint=false, with no contradiction; the description adds substantial value beyond 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?

The description is somewhat lengthy but well-structured, front-loading the core purpose and adding essential details. Every sentence contributes value, though it could be slightly more concise (e.g., venue list 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 7 parameters with 100% schema coverage, output schema exists, and the description explains output fields and trade-offs with sibling tools, it is fully complete for effective agent use.

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 baseline is 3. The description does not add new meaning beyond the schema for the parameters (q, fiat, sort, limit, offset, source, status). It explains the output but not the parameters themselves.

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 specifies 'Free public search over prediction-market events across ALL 12 venues', listing each venue and contrasting with discover_pm_markets. The verb 'search' and resource 'prediction-market events' are clear and unambiguous.

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 to use: 'broader than discover_pm_markets' and 'Research/data only: to trade, use discover_pm_markets + pm_quote instead.' Also notes 'No API key required,' providing clear context for usage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable context: source-aware freshness, per-venue health at a specific endpoint, volume reporting methodology, real-money-only monetary totals, self-computed aggregates requiring citation, and no API key required. No contradiction with 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?

The description is concise (4 sentences) and front-loaded with the most important information: the type of statistics and venues. Every sentence adds meaningful detail without unnecessary fluff.

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

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

Given the tool has one optional parameter, a rich output schema, and comprehensive annotations, the description covers all necessary aspects: data aggregation, health monitoring, volume methodology, citation policy, and access requirements. It is fully self-contained for an AI agent to understand usage.

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 single optional parameter 'fiat' is well-described in the schema with default currency code. The description adds minimal additional value beyond the schema (only mentioning monetary totals cover real-money venues). Schema coverage is 100%, so baseline of 3 is appropriate.

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

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

The description clearly states the tool provides aggregated prediction-market statistics across 12 venues, listing specific metrics (total/open/closed counts, volume, liquidity, highlights). It also distinguishes from pm_data_event for deeper event evidence, making the purpose precise.

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 explicitly directs users to pm_data_event for full event evidence and mentions the health endpoint for per-venue freshness. It also covers volume basis and citation requirements, though it doesn't enumerate all contexts where alternative tools should be used.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false. Description adds that no API key is required and data is free/public, providing extra behavioral context beyond annotations.

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

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

Three concise sentences: first defines purpose, second gives usage guidance, third notes no API key. No waste, front-loaded with key 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?

Given the tool is read-only with a single optional parameter, the description fully covers what data to expect and when to use it. Output schema exists and annotations cover safety, so no gaps.

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

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

Schema coverage is 100% (one optional parameter with description). Description does not mention the fiat parameter, so it adds no extra meaning beyond what the schema already provides.

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

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

The description explicitly states the tool returns methodology and coverage for every prediction-market venue, listing specific attributes (source kind, metrics, counts, volumes, currency, comparability, timestamps). This clearly distinguishes it from sibling pm_data_* tools.

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

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

Provides explicit usage guidance: '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.' Clear context but does not explicitly mention alternatives or when not to use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. Description adds 'No API key required' and 'Free public', which are useful behavioral traits beyond what annotations provide. No 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?

Two sentences, highly front-loaded with purpose and usage guidance. Every sentence earns its place—no fluff.

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?

Tool has no parameters and has an output schema (even though not shown). Description covers purpose, usage, and behavior completely for a zero-parameter read-only health check.

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?

Input schema has no parameters, and schema description coverage is 100%. With zero parameters, baseline is 4. Description adds no parameter info, but none is needed.

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

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

Description clearly states it provides 'per-venue ingest health' with specific metrics (freshness tier, lag, reasons, coverage counts, timestamps). Distinguishes from sibling tool pm_data_sources (which likely lists venues without health).

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 advises to check health before using quotes or claiming cross-venue coverage, and warns that venue presence alone does not guarantee freshness. This provides clear when-to-use and when-not-to.

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 indicate readOnlyHint true, openWorldHint true, destructiveHint false. The description adds critical behavioral context: data captured since 2026-07-02, rolling 90-day window, gaps are null not zero, and exclusion of play-money venues. No contradiction with 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?

The description is information-rich but somewhat dense due to parenthetical clarifications. Every sentence adds value, but it could be slightly more streamlined. Still, it is well-structured and front-loaded with the main purpose.

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 no parameters, existing output schema, and comprehensive annotations, the description covers all necessary context: data source, timeframe, gap handling, venue exclusion, and intended use. It is fully complete for agent understanding.

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?

No parameters exist in the input schema, so schema coverage is 100%. The description adds no parameter information, which is appropriate. Baseline for 0 parameters is 4.

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 explicitly states the tool provides 'global daily prediction-market volume trend' with specific details: one point per UTC day, day-over-day delta, real-money venues only, and per-venue breakdown. It clearly distinguishes from sibling tools like pm_data_overview or pm_data_sources by focusing on volume history.

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 tells when to use ('to see whether cross-venue prediction-market activity is growing or shrinking over time') and clarifies scope (real-money venues, no API key). It does not explicitly state when not to use or provide alternatives, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds value by specifying that Polymarket rows are wallet-attributed while Kalshi rows are anonymized, and that results are ordered newest first. It also states 'No API key required.' This goes beyond the annotations without contradicting them.

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 3-4 sentences, each providing essential information without redundancy. It front-loads the core purpose and efficiently adds behavioral details and disclaimers. No wasted words.

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 single optional parameter, no required params, an existing output schema, and thorough annotations, the description covers everything needed: data content, ordering, venue attribution differences, and authentication requirements. It is fully sufficient for an agent to select and invoke this tool 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?

The sole parameter 'limit' is fully covered by the input schema (type, min, max, description). The description does not add further semantics beyond what the schema provides. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states it returns 'latest large prediction-market trades' with specific fields (side, outcome, USD value, etc.) and distinguishes by venue (Polymarket vs Kalshi). This differentiates it from sibling tools like pm_data_calibration or pm_data_overview, making the purpose unmistakable.

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

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

The description notes it's a 'free public tape' with 'no API key required,' giving context on when to use it. However, it does not explicitly state when not to use it or mention alternatives among siblings, though the name and content make the use case clear. A slight gap in explicit exclusions prevents a perfect score.

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

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

Beyond annotations (readOnlyHint, destructiveHint), the description explicitly states 'Never mutates state,' explains the openBlocked gate, details the paper trading execution model (including fees and slippage), and clarifies it is a rehearsal cost with no exchange guarantee. This adds substantial behavioral context.

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

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

The description is front-loaded with the core purpose and then covers important details in a logical order. While somewhat lengthy, each sentence adds necessary context for a complex tool. Minor redundancy in explaining the NO side's fill price could be trimmed, but overall well-structured.

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?

The description covers purpose, read-only nature, behavioral implications (openBlocked), paper trading context, execution model, and limitations (not financial advice, not a guarantee). With output schema present, the description is comprehensive enough for an agent to use the tool 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?

Input schema already describes all parameters (100% coverage). The description adds value by explaining the side parameter's effect (NO fills at 100 minus probability) and that stakeMusd > 0 with a minimum of 10. For agentTrace, it does not add new info, but the overall extra context lifts it above baseline 3.

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

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

The description clearly states the tool provides a read-only quote for a binary prediction market outcome, listing key outputs. It distinguishes itself from sibling write tools (e.g., open_pm_position) by emphasizing its non-mutating nature.

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 indicates this tool is a preview before opening a position (e.g., if openBlocked is true, open_pm_position would fail). It also explains the side parameter and notes paper trading only, but does not explicitly contrast with other quote tools (e.g., futures_quote, spot_quote).

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?

Description adds significant context beyond annotations: it is self-reported, never moves funds, creates a durable artifact, and is paper trading only. Details execution costs and policies. No contradiction with annotations; its idempotentHint is consistent with decisionId reuse.

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 overly long with extraneous details about paper execution costs and policies that could be in separate documentation. The key message is front-loaded, but the trailing paragraphs reduce clarity and efficiency.

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

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

Given the tool's complexity (12 params, nested objects, output schema), the description covers essential behavioral aspects (self-report, idempotency, no funds movement) but buries them in verbose text. It is complete but not optimally structured.

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. Description adds behavioral nuance (e.g., forecastProbability required for forecast_only, decisionId as idempotency key) but most parameter details are already in the schema. Does not significantly enhance understanding beyond schema.

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

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

The description starts with a clear verb and resource ('Report a prediction-market opportunity you evaluated but did NOT open'), immediately distinguishing it from trading tools. It specifies the tool's unique role in recording non-trade evaluations to ensure complete performance tracking.

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 to use (for non-opened opportunities, as evidence) and what it is not (a trade). Mentions self-report and lack of verification, implying limitations. Could be improved by contrasting with related tools like open_pm_position or pm_data_calibration.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds that the tool operates in a paper trading environment with virtual funds and is not financial advice. However, it includes tangential details about execution costs and fill policies that are not relevant to this read-only resolution tool, which slightly reduces clarity.

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

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

The description is front-loaded with the main action but then includes lengthy details about execution costs and policies that are irrelevant to symbol resolution. This reduces conciseness; about half the content could be considered extraneous for this tool.

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 that an output schema exists, the description appropriately mentions the return value (coinId plus alternatives with category tags). It also provides important context about the paper trading environment. However, it does not address edge cases like unresolvable symbols or error handling.

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. The description adds minimal extra meaning beyond the schema, such as examples for 'q' ('BTC', 'ethereum') and clarifying that agentTrace is stored in the caller's ledger. It does not significantly enhance parameter understanding.

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 clearly states that it resolves a human symbol/slug/name to a CoinRithm coinId (UCID) plus disambiguating alternatives. It uses a specific verb ('resolve') and identifies the resource ('symbol to coinId'), distinguishing it from sibling tools that handle trading or ledger operations.

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 explicitly instructs to use this tool first to obtain coinId for wallet/quote/order tools and warns not to guess UCIDs because symbols are not unique. It provides clear when-to-use guidance and a negative directive, though it does not list alternative tools for resolution.

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

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

The description adds extensive behavioral context beyond annotations: side-aware trigger logic, worker execution, closure at mark, fill discovery via my_trades, scope requirements, paper-only status, execution cost details, and legal disclaimer. Annotations provide only basic hints.

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

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

The description is front-loaded with the core purpose but includes lengthy details on paper execution policy and fees that may be excessive for an AI agent. It is well-structured but could be more concise.

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

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

Given the tool's complexity (4 parameters, nested objects, output schema), the description covers all essential aspects: usage, constraints, behavior, scope, and execution model. No gaps identified.

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%, but the description adds value by explaining the side-aware ordering for SL and TP (long: liq < SL < mark < TP; short inverted) and clarifying that null clears while omitted leaves unchanged. This goes beyond the schema 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?

The description clearly states the verb 'Set or clear' and the resource 'resting stop-loss / take-profit triggers on an OPEN mock futures position.' It distinguishes from siblings like close_futures_position and open_futures_position by focusing on SL/TP management.

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 explains how to use the tool (positive sets, null clears, omit unchanged) and mentions prerequisites (OPEN position, trade:futures scope, paper trading only). It implies when not to use (e.g., not for closing) but does not explicitly name 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?

The description goes well beyond annotations by stating 'Never mutates state', detailing paper trading specifics, execution costs, fees, slippage, and that price age is informational. Annotations already mark readOnlyHint=true, but the description adds considerable behavioral context.

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

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

The description is front-loaded with the main purpose and key outputs. It includes some extra detail (e.g., not financial advice, execution policy) that may be slightly verbose but remains organized and informative. Could trim some repetitive explanations.

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

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

Given the tool's complexity (4 parameters, output schema exists), the description covers purpose, outputs, parameter hints, behavioral traits, paper trading context, and execution cost details. It is comprehensive and leaves little ambiguity for an AI agent.

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

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

With 100% schema coverage, the baseline is 3. The description adds critical value by clarifying that coinId is a UCID, not a ticker, and advises using resolve_symbol first. This compensates for schema limitations and improves parameter understanding.

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 clearly states it is a read-only spot market quote for live execution price, estimated cost, available balance, and fill eligibility. It distinguishes itself from siblings by specifying 'spot' and contrasting with place_spot_order, implying it is for quoting before ordering.

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 explicitly says to use this tool before place_spot_order to avoid blind buying/selling. It provides clear context for usage but does not directly compare with futures_quote or pm_quote, though the name and context imply 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds significant behavioral context: paper trading only, virtual funds, execution policy details, and notes that agentName/agentModel are null until set. No contradiction with 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?

The description is overly verbose, containing extensive details about paper trading policies, fees, and execution costs that are not core to the 'whoami' function. These details should be in separate documentation or the output schema 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?

Given the simple input (1 optional parameter, 100% schema coverage, annotations, and an output schema), the description covers the return fields adequately. However, it includes tangential paper trading context that may distract from the tool's main purpose.

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 input schema has one optional parameter 'agentTrace' with full schema descriptions, so schema coverage is 100%. The tool description does not mention this parameter or its effect, adding no extra meaning. Baseline 3 is appropriate.

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

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

The description clearly specifies the tool's purpose: 'Return the identity behind the configured API key' and lists the returned fields (userId, keyId, granted scopes, agentName, agentModel). This distinguishes it from sibling tools that focus on ledger, portfolio, or trades.

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 explicitly advises: 'Use this first to confirm what the key is allowed to do.' This provides clear context for when to invoke it. It does not mention when not to use it, but as a simple identity check, that omission is minor.

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