Swarm Tips — Earn, Spend, and Discover for AI Agents

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

Discloses execution details beyond annotations: reads directly via getAccountInfo, no orchestrator hop, no cache, and that either PDA may be absent. Adds derived metrics computation. No contradiction with readOnlyHint=true.

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?

Starts with clear label '[READ]', then logically flows from data sources to derived metrics to parameter usage. Each sentence adds value, no redundancy. Efficient and 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?

Covers return values (derived metrics, null PDAs) despite no output schema. Lacks mention of error conditions or rate limits, but for a read-only tool with annotations this is adequate. Sibling context is well handled.

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 significant meaning beyond schema: explains default behavior for wallet (omission queries caller's wallet) and tournament_id (defaults to 1, per-tournament nature). With 100% schema coverage, description enriches 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 it is a '[READ]' operation for 'trustless on-chain reputation lookup', listing specific data sources (AgentState, PlayerProfile) and derived metrics. This clearly distinguishes it from sibling tools like agent_trust_score or shillbot 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?

Provides clear guidance on wallet parameter usage ('Pass wallet to query an agent; omit for your registered wallet') and tournament_id default. Does not explicitly state when not to use, but context is sufficient given sibling tools are mostly write operations.

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, and the description adds that the tool returns a composite score, confidence (0..6 signals), and a breakdown per signal with applied weight. It also notes partial-data tolerance and weight renormalization, which are beyond annotations and add significant value.

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, dense paragraph with clear structure (bracketed summary, bullet-like lists). Every sentence contributes meaning, with no redundancy or fluff. It could be slightly more concise but remains effective.

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

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

Despite no output schema, the description fully explains the return values (score, confidence, breakdown). All parameters are covered with usage details. The tool's moderate complexity is well-addressed, though an explicit list of return fields would enhance completeness.

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. The description adds meaningful context: wallet omission queries caller's wallet, agent_rank is externally computed, curator_tier specifies ascription values, tournament_id defaults to 1. This goes beyond the schema's minimal 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 tool computes a composite trust score (0..1) from multiple signals, with '[READ]' indicating read-only operation. It distinguishes from siblings like 'query_agent_credit_web_score' by listing specific components (EigenTrust, Shillbot, etc.) and emphasizing the composite 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 explains when to use it: when a composite trust score is needed, with partial-data tolerance. It doesn't explicitly exclude alternatives, but mentions optional parameters and defaults, providing clear context. A minor gap is not naming sibling tools for simpler queries.

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 marks itself as a read operation with '[READ]' and explains the return states. The annotation 'readOnlyHint: true' already indicates safety, and the description adds value by detailing the possible states. However, it does not disclose rate limits or idempotency.

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

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

Two sentences, no wasted words, front-loaded with the '[READ]' label. Every sentence adds 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?

For a simple polling tool, the description is largely complete with the schema covering the parameter. It could mention that repeated calls are needed to track progress, but this is implied by the polling nature. With no output schema, the return values are adequately described.

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 only parameter 'session_id' is fully described in the schema with 100% coverage. The tool description does not add any additional meaning beyond what the schema provides, so baseline score of 3 applies.

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

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

The description clearly states it checks the status of a video generation request and specifies the three possible return values ('generating', 'complete' with video_url, 'failed'). It distinguishes itself from the sibling 'generate_video' tool by focusing on status polling.

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 after 'generate_video' by referencing the session_id it returns, but does not explicitly state when to use or when not to use this tool, nor does it provide 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 notes the tool is a read-only wrapper (consistent with readOnlyHint annotation) and explains that each returned entry carries a 'vertical' field for routing. This adds useful context beyond the annotation, though the read-only nature is already declared.

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, well-structured, and front-loaded with '[READ]' and a clear statement of purpose. Every sentence adds value without 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?

With no output schema, the description explains the vertical field and routing. It covers the main usage scenarios and constraints. Could mention error cases or empty results, but it is sufficiently complete for a search 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%. The description restates the intent and keyword parameters but does not add significant new meaning beyond what the schema descriptions already provide. 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 clearly states it performs a unified search across earn and spend verticals, wrapping list_earning_opportunities and list_spending_opportunities. It specifies the filter options (intent, category, keyword) and distinguishes itself from sibling per-vertical tools by naming them.

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 tells when to use (when uncertain about earn/spend or wanting a keyword search across both) and when not (for deep per-vertical control, use the per-vertical tools directly). Provides clear alternatives.

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

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

Annotations already declare readOnlyHint=true; description reinforces with '[READ]' and explains return states. Adds polling advice but does not contradict 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?

Two sentences, no wasted words. Front-loaded with action verb and resource. Highly 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?

For a zero-parameter polling tool with no output schema, the description completely covers purpose, return states, and usage pattern. 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?

No parameters in schema, so no additional explanation needed. Baseline 4 applies; description does not need to add any parameter information.

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 'check if you have been matched' with specific verb and resource. Distinguishes from sibling tools like game_find_match (which initiates) and game_get_result (which gets result after game).

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 instructs to 'Poll every 2-3 seconds after calling game_find_match,' providing clear context and timing, and differentiating it from other match-related tools.

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 context beyond the destructiveHint annotation by noting 'no funds movement at this step' and describing the return of an unsigned transaction. However, it does not disclose that the commit is irreversible or that it transforms the game state, which would be valuable given the destructive hint.

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 three sentences with no padding: action, output and next steps, financial clarification. 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?

Given the simple tool (1 param, no output schema), the description adequately covers the return type (unsigned commit transaction) and workflow linking to sibling tools. It lacks preconditions (e.g., need an active match) but that is implied by the game flow.

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

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

Schema coverage is 100% with a single parameter. The description adds meaning by explaining what 'same' means ('opponent is same type'), which goes beyond the schema's brief description. This adds value without redundancy.

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 'Commit your guess on-chain: same or different' with a specific verb and resource, and distinguishes it from sibling tools like game_reveal_guess and game_submit_tx by explaining the workflow.

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 clear context: when to use (after match lock), what to do next (sign and submit via game_submit_tx, then poll game_reveal_guess), and an exclusion (no funds movement here). However, it does not explicitly state when not to use this tool (e.g., no active match).

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 context beyond destructiveHint annotation: describes two-phase reveal, r_matchup semantics, and anonymity barrier. 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?

Concise description, front-loaded with [STATE] marker. Dense but not overly verbose; could be slightly clearer in structure.

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

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

Given simple tool with one parameter and no output schema, the description explains response behavior and context adequately. Missing minor details like error cases, but sufficient.

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 with full schema coverage. The description reinforces the need for game_id but adds no new semantics beyond the schema.

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

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

The description clearly states it notifies the commitment of a guess on-chain for a same-chain EVM match, detailing the response behavior (r_matchup condition). It distinguishes from sibling tools like game_commit_guess by being a notification after the fact, though not explicitly.

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

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

It mentions requirements (registered wallet, game_id) and implies use after committing, but lacks explicit when-to-use vs 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?

The description adds value beyond the readOnlyHint annotation by specifying the return values ('waiting' or 'matched') and the requirement for a registered EVM wallet. It does not contradict 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 extremely concise with two sentences, front-loaded with '[READ]'. Every sentence is necessary and informative, with 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 zero parameters, presence of annotations, and no output schema, the description fully covers the tool's purpose, usage context, and behavior. It explains the workflow and prerequisites completely.

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

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

There are no parameters, so the baseline is 4. The description does not need to add parameter semantics, and it correctly does not attempt to describe nonexistent parameters.

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 polling tool for EVM match status, specifying return values 'waiting' and 'matched'. It distinguishes itself from sibling tools like game_find_evm_match by indicating it is to be called after that tool returns 'waiting'.

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 tells when to use the tool: 'Call after game_find_evm_match returned 'waiting'.' It implies when not to use and provides a prerequisite (registered EVM wallet). However, it does not mention alternatives or when to use other tools.

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 destructiveHint: true, implying side effects. The description adds context: the tool places the player in a queue, returns a state, and provides unsigned calls for creation or joining. 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 comprehensive but somewhat long. It is front-loaded with [STATE] and includes all necessary details without 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?

Given the tool has one parameter and no output schema, the description adequately explains behavior, states, and return structure. It provides sufficient context for agent 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 only parameter (tournament_id) has 100% schema coverage. The description adds that it defaults to 1, which is helpful but minimal extra value 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 the tool joins the same-chain EVM coordination game queue and matches with another player. It distinguishes from cross-chain game and specifies the context testnet only (Base Sepolia).

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 join an EVM match) and contrasts it with the cross-chain game. It does not explicitly state when not to use it, but 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?

Goes beyond the destructiveHint annotation by detailing the locking of ante, winning/losing consequences, and negative-sum nature. Discloses financial implications and the need for a registered wallet, providing full 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?

Single paragraph front-loaded with cost, action, workflow, and consequences. Every sentence provides essential information without redundancy. Structure effectively guides the agent from what to do to what to expect.

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

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

Despite no output schema, description implies the return of an unsigned transaction and covers prerequisites, parameters, cost, and consequences. Complete for a tool that builds a transaction in a financial game context.

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 value by clarifying the tournament_id default and that it should usually be omitted. Does not repeat network details but the schema already provides thorough documentation. Overall adds meaningful 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 builds an unsigned deposit_stake transaction to join matchmaking, specifying the verb 'build', the resource 'deposit_stake transaction', and the context 'join matchmaking queue'. Distinguishes from sibling tools like game_submit_tx and register_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?

Explicitly explains when to use (to join matchmaking), prerequisites (call register_wallet first), follow-up steps (sign locally, submit via game_submit_tx), and parameter guidance (tournament_id defaults to 1, omit unless known). Also notes cost and game economics.

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 the description reinforces this with '[READ]' and 'Get'. It additionally discloses the scoring formula, providing transparency 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?

Two concise sentences convey all necessary information without redundancy. Every word earns its place.

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

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

For a simple read-only tool with two parameters and no output schema, the description fully explains functionality, scoring, and defaults. 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 covers both parameters with full descriptions. The description adds context about tournament_id default and the fact that only one active tournament exists, which is helpful but not critical 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 it retrieves the tournament leaderboard for the Coordination Game, specifying the scoring formula (wins^2 / total_games). This is distinct from sibling tools like game_get_messages or game_check_match.

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 guidance on tournament_id default and when to omit it. While it doesn't explicitly state when not to use this tool versus alternatives, the unique purpose makes it sufficiently 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?

Adds key behavioral details beyond readOnlyHint: messages are drained from buffer, each returned once, implicit session scoping. Discloses mutation of temporary state while readOnlyHint indicates no persistent mutation.

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 with front-loaded [READ] tag. Every sentence provides essential info: purpose, idempotency, scope, session resolution. 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?

Complete for a simple read tool with no params and no output schema. Covers what it does, how it works (drain, once), and when to invoke (session context). 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?

No parameters, so schema coverage 100%. Description adds value by explaining why no game_id needed (implicit session scoping) and resolution chain, going beyond the empty 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?

Description clearly states 'Get all chat messages from your opponent', specifying verb and resource. It distinguishes from siblings like game_send_message (write) and game_get_result (result), and includes scope limitation 'since the last call'.

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?

Implies use for retrieving opponent messages, with clear context about draining and once-only retrieval. Does not explicitly mention when not to use or alternatives, but sibling list provides contrast.

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. Description adds that it returns on-chain game state with specific details, providing useful behavioral context beyond the annotation.

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 sentence with front-loaded '[READ]', no redundant words. Highly concise and 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?

Given no output schema, description adequately explains return values. Tool is simple with no parameters; description covers all essential aspects for agent 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?

No parameters (0 params, 100% schema coverage). Baseline 4 for zero-param tools; description adds no parameter info as none 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?

Clearly states it's a read tool for getting the result of the current or most recent game, and specifies the return content (on-chain game state, players' guesses, resolution status). Distinguishes from sibling tools like game_commit_guess or game_find_match.

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

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

States it's for getting results of current/most recent game, implying after game completion. Does not explicitly list alternatives, but context makes usage 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?

The description goes beyond the annotations (destructiveHint=true) by detailing the resolve outcome: correct guess recovers ante, wrong forfeits, and the game is negative-sum after treasury cut. This adds critical behavioral context not in 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 one paragraph but contains all essential information in a logical order: state check, action required, consequences. It is concise without wasted words, though slightly dense.

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, no output schema, and only destructiveHint annotation, the description fully covers the tool's behavior: what it returns, how to use the result, and the economic impact. No gaps remain.

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

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

There are no parameters, and schema coverage is 100% (none). The description adds value by explaining the return values ('waiting' or transaction), which compensates for the lack of an output schema. Baseline for 0 params 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 clearly states the tool checks if both players have committed and returns either 'waiting' or an unsigned reveal transaction. It identifies the specific action (reveal guess) and distinguishes from sibling tools like game_submit_tx.

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: poll every 3-5 seconds if 'waiting', and then use game_submit_tx with action='reveal_guess' to submit the signed transaction. It also explains the consequences of correct/wrong guesses, guiding the agent's decision. It lacks explicit 'when not to use' but context is strong.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It mentions sending a message but fails to explain potential side effects, rate limits, error conditions (e.g., no active game), or whether messages are persisted.

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, using two sentences plus a resolution note. It is front-loaded with the core purpose and efficiently conveys the scope. Minor room for improvement in structural 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 tool's simplicity (1 param, no output schema, no annotations), the description covers the basics but omits important contextual details such as expected behavior on failure, message visibility, or game state requirements.

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 'text'. The description adds a usage guideline ('Keep messages casual and human-like') but does not enrich the meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Send a chat message to your anonymous opponent during the game.' It uses a specific verb-resource combination and distinguishes itself from sibling tools like game_get_messages (read) and game_commit_guess (guess).

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 that the message is implicitly scoped to the active game session, so no game_id is needed. However, it does not explicitly state when to use this tool versus its alternatives or provide conditions to avoid misuse.

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 annotation already marks it as destructive, but the description clarifies that funds movement is determined by a prior call and warns about wrong network leading to BlockhashNotFound, adding 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 concise, front-loaded with the verb and action list, and includes a critical note about the prior tool call. 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?

While the description covers the broadcast action and an error condition, it omits what the tool returns (e.g., transaction signature). Given no output schema, more detail on outputs would improve completeness.

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 parameters. The description does not add additional parameter-specific semantics, only context about the tool's role.

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: submitting a signed Solana transaction for any game step, listing specific actions. It distinguishes from siblings that likely build unsigned transactions.

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 the tool is used after building an unsigned transaction, providing clear context. It does not explicitly state when not to use it or name alternatives, but the context is sufficient.

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?

Details payment protocol (x402 v2, USDC on multiple chains), generation trigger, and return value (session_id). Annotation destructiveHint: true is consistent with cost. No mention of rate limits or other constraints, but sufficient.

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 comprehensive but slightly long due to complex payment flow. Front-loads cost and key usage pattern. Could be tighter, but each 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?

No output schema, but description explains return value (status, instructions, payment_details, session_id) and refers to check_video_status for polling. Complete for a payment-gated generation 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%, but description adds meaning: prompt max 1000 chars, url as optional context, tx_signature omitted for first call. Explains the two-call protocol, making each parameter's role clear.

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 generates a short-form video from a prompt or URL. Distinguishes from sibling tools like check_video_status and shillbot_submit_work.

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 explains two-call payment flow: first call returns payment instructions, second call with tx_signature triggers generation. Mentions tip to submit to shillbot. Does not explicitly state when not to use, but flow is clear.

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

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

Beyond the readOnlyHint annotation, description details the read operation nature, output structure (fields like source, title, reward), and distinguishes between first-party (with claim_via) and external claims. Adds significant 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?

Single paragraph, well-structured, front-loaded with purpose. Every sentence adds value without redundancy. Efficient and informative.

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

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

Given no output schema, description compensates by listing returned fields and explaining the entry structure. Covers aggregation, sources, claim mechanisms, and filtering effects comprehensively.

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 covers all 4 parameters with descriptions. Description adds minor nuance about min_reward_usd excluding entries without USD estimate, but overall does not substantially supplement parameter meaning 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?

Description clearly states it aggregates earning opportunities across the ecosystem, lists included sources (Shillbot, Bountycaster, etc.), and explicitly differentiates from per-source listing tools by recommending this as the universal entry point.

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 clear guidance to prefer this over per-source tools and explains claim methods for first-party vs external sources. Lacks explicit when-not-to-use scenarios but effectively communicates primary use case.

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 starts with '[READ]' reinforcing the readOnlyHint annotation, and adds context about the return structure and the edge case of empty results on unsupported clusters, which is beyond what annotations provide.

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

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

The description is three sentences with no extraneous content. The first sentence states the core purpose, the second covers optional filters, and the third describes the return format and edge case. Efficiently front-loaded.

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

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

Despite having no output schema, the description explicitly provides the return format and mentions the empty-case behavior. With parameters fully documented in the schema, this description is sufficient for an agent to understand and invoke 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?

Schema coverage is 100% and both parameter descriptions already specify 'base58'. The description merely restates these filters without adding new semantic information, so 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 states the verb 'List' and the resource 'active extension-credit obligations', with optional filters and return format. It distinguishes itself from sibling tools which are mostly game-related.

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 querying extension-credit obligations with optional filters. It mentions the empty response on clusters without the extension-registry, but does not explicitly state when not to use or 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 adds context beyond the readOnlyHint annotation by specifying that it is a read operation, listing the fields in each entry, noting that v1 covers limited services, and clarifying that opportunities without USD estimates are included. Slight deduction for not mentioning pagination or rate limits, but still strong.

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, well-structured paragraph that front-loads the purpose and efficiently communicates all necessary details without redundancy. 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 lack of output schema, the description adequately explains the return structure (each entry includes title, description, source, cost, USD estimate, etc.) and the tool's scope. Completeness is high for a list tool with no required parameters.

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 has 100% coverage with clear parameter descriptions. The description adds minimal new meaning beyond the schema (e.g., examples for category). Baseline 3 is appropriate as the schema already provides sufficient detail.

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

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

The description clearly states it provides an aggregated list of paid services for agents to spend on, distinguishes between first-party and external services, and differentiates from sibling tools like list_earning_opportunities by focusing on spending rather than earning.

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 (to discover spending opportunities) and what to do after: for first-party services use the named spend_via tool, for external services navigate to the URL. No ambiguity about 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?

Beyond readOnlyHint=true annotation, the description adds details: computation method (EigenTrust anchored to trusted root), condition (>=1 received extension), return fields, and behavior on clusters without extension-registry.

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 a single sentence with key info front-loaded ([READ]), plus two short sentences. No redundancy, every word 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 one optional parameter and no output schema, the description covers the purpose, computation, return structure, edge cases, and relation to sibling tool. Fully complete.

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

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

Schema coverage is 100%, but description adds value by explaining that omitting wallet uses the registered wallet, which is not in the schema 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 it's a read that returns an extension-credit web score (0..1) computed via EigenTrust, and distinguishes from sibling tool agent_trust_score by noting this signal feeds into it.

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 explains when to use (get agent's credit web position) and notes edge case (empty/0 on clusters without extension-registry). Lacks explicit alternatives 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?

With no annotations, the description fully discloses important behaviors: non-custodial (private key never leaves device), persistence of binding across restarts, and expected outputs per network (Solana: address + SOL balance; EVM: CAIP-10 account). It also highlights a limitation (no EVM RPC client).

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 longer than ideal but each sentence adds value, covering purpose, prerequisites, network differences, and persistence. It is front-loaded with the core purpose and structured logically, though could be slightly 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 simplicity (one parameter, no output schema, no annotations), the description comprehensively covers what an agent needs: usage context, outputs, limitations, and persistence behavior. No significant gaps remain.

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?

Though schema coverage is 100% and baseline is 3, the description adds meaning beyond the schema by clarifying that the pubkey parameter is for Solana (base58, 32 bytes) and that EVM registration requires a separate step. This extra context aids correct parameter usage.

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: registering a wallet to use swarm.tips tools that touch funds. It specifies the resource (wallet) and distinguishes from sibling tools by emphasizing its foundational role across games and shillbots.

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 guidance: call xchain_supported_chains first for EVM, explains the difference between Solana and EVM registrations, and mentions non-custodial nature. It also indicates that one registration covers multiple same-chain products, aiding in tool selection.

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

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

The description explains that results are relevance-gated, ordered by automated quality signals, no manual curation, and each hit discloses ranking_signals. It also covers filtering by automated provenance. Since readOnlyHint is already set, the description adds significant 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?

The description is well-structured, starting with the operation type, then main functionality, filtering options, and use case. Despite length, every sentence adds essential information with no redundancy. It is front-loaded with key 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 no output schema, the description mentions that each hit discloses ranking_signals for audit, but does not fully specify the return structure. However, it sufficiently covers behavior, filtering, and ranking logic, making it fairly complete for a search 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 has 100% coverage, but description adds value by explaining query behavior (e.g., BM25-ranked, omitting query gives browse mode), and clarifying category and tier filters with examples. This goes beyond the schema's core definitions, earning a score above baseline.

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

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

The description clearly states it is a BM25 relevance search over the MCP-server catalog, with specific examples (e.g., 'solana defi swap'). It differentiates from sibling 'discover_opportunities' by stating use for earn/spend opportunities. The purpose is unmistakable.

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

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

Explicitly says 'Use this when an agent needs an MCP server for a capability; for earn/spend opportunities use discover_opportunities.' Also instructs to omit query for browsing. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations set destructiveHint=true, and the description adds important behavioral context: it returns an unsigned transaction (client-side), the verification timeout behavior, and that only the original client can call. It does not contradict annotations and provides useful details beyond 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 concise despite being detailed. It front-loads the key purpose and workflow, then adds important behavioral notes and references to sibling tools. Every sentence adds value with 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?

Given no output schema, the description fully explains the return value (unsigned base64 Solana transaction) and the required follow-up action (shillbot_submit_tx). It also covers edge cases like network mismatch and timeout anchoring. Context is complete for a client-side approval step.

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 value by explaining the network parameter's default and behavior (forwarded to orchestrator, mismatch leads to accounts not found), and the task_id format. This exceeds 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 tool's purpose: 'Approve agent-submitted content for a Shillbot task you funded.' The verb 'approve' and resource 'agent-submitted content' are specific. It distinguishes from sibling tools like shillbot_reject_task and shillbot_list_pending_approval, and explains the client-side signing workflow.

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 tells when to use: after funding a task and when reviewing pending approvals. It mentions using shillbot_list_pending_approval to find tasks. However, it does not explicitly state when not to use, 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?

The description aligns with the readOnlyHint annotation by starting with '[READ]' and describing a read operation. It adds minimal new behavioral context beyond the annotation, such as the wallet registration requirement, but otherwise relies on the structured annotation for safety disclosure.

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

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

The description is three sentences long, front-loaded with the purpose, and efficiently provides all necessary information without extraneous content. 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers the key aspects: what it returns, prerequisites, and parameter options. It slightly lacks detail on error handling but is otherwise complete given the low complexity.

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

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

Schema description coverage is 100% for the sole parameter 'network', so the description adds little beyond the schema. It mentions the default value and options, but the schema already provides that information, resulting in a baseline score of 3.

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

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

The description specifies the verb 'Check' and resource 'earnings summary', listing specific items (total earned, pending payments, etc.) that distinguish it from sibling shillbot tools which involve actions like approving, claiming, or completing tasks.

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 prerequisite of a registered wallet and the optional network parameter with defaults, providing clear context for when to use the tool. However, it does not explicitly compare to siblings or state when not to use it, which would improve clarity.

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 destructiveHint=true. The description adds valuable context: non-custodial signing flow, that the server never sees the private key, and the need to submit via shillbot_submit_tx. This enhances transparency 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?

Single well-structured sentence with a clear front-loaded '[STATE]' tag. Every word earns its place, 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?

Given 2 parameters, no output schema, and destructive annotations, the description covers the core process, prerequisites, and return value (unsigned base64 Solana transaction). Slight gap: no mention of transaction format beyond base64, but sufficient for an 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?

Input schema has 100% coverage. Description adds meaning by specifying task_id format (from list_available_tasks) and explaining network default and mismatch consequences, enriching the schema's raw 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 tool claims a Shillbot task, distinguishes from sibling tools like shillbot_approve_task and shillbot_complete_task by outlining the unique process of returning an unsigned transaction for local signing.

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 prerequisite 'requires a registered wallet (call register_wallet first)' and explains optional network parameter. While it doesn't explicitly list alternatives or when not to use, the context is clear for a task claiming action.

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: mentions unavoidable external waits, wait actions with not_before timestamps, returns done when finalized, and network mismatch behavior. Consistent with readOnlyHint annotation.

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?

Well-organized and front-loaded with purpose. Every sentence adds value. 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?

Covers lifecycle, return types (next_action, wait, done), and re-call behavior. Lacks exact return structure details, but sufficient for an agent to 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?

Both parameters have schema descriptions with 100% coverage. Description adds value by specifying task_id format and default network behavior, and warns about network mismatch.

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 is a read-only wrapper that collapses the multi-step Shillbot task lifecycle into one loop. Distinguishes from sibling tools by describing itself as an orchestrator that returns the exact next tool to call.

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

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

Explicitly says to pass a task_id and re-call after each step or wait. Implicitly indicates use over individual tools, but does not explicitly state when not to use it or list 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?

Beyond the destructiveHint annotation, the description reveals that the tool transfers payment to the agent and protocol fee to treasury, closes the task account, and is permissionless. It also explains the required signing and submission process, adding context about what the tool does and how it behaves.

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 two sentences plus a brief note, all front-loaded with the core purpose. Every sentence adds value: first sentence summarizes the action, second covers permissionless and process, third clarifies optional parameter. 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?

Given no output schema, the description explains the outcome (transfers, account closure) and the required steps (sign, submit). It covers the necessary context for a tool with two parameters and a destructive hint. However, it could mention what the returned transaction object contains.

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

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

Schema coverage is 100%, so both parameters are already described. The description adds that network is optional and defaults to 'mainnet', and that task_id format comes from list_available_tasks. This provides minor additional context, but the schema already explains the parameters adequately.

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 finalizes a verified Shillbot task, transfers payment from escrow, and closes the task account. It uses a specific verb-resource combination and distinguishes from sibling tools like shillbot_approve_task or shillbot_claim_task by detailing the post-challenge finalization step.

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 when to use the tool: after the challenge window and deadline. It also notes the permissionless nature and instructs to sign the returned transaction then submit via shillbot_submit_tx. However, it does not explicitly state when not to use it or compare to alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with "[READ]" and "MCP does not sign." It adds behavioral details beyond annotations: re-reads the named PDA to verify, returns 409 if account is closed, and describes the capture window. 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?

Each sentence contributes unique information: purpose, parameter options, output shape, and behavioral caveats. No fluff or repetition. Front-loaded with the essential verb and resource. The structure flows logically from purpose to usage to output to behavior.

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?

No output schema exists, so the description compensates by listing all return fields. It also explains the capture window and 409 error. While it doesn't explain the purpose of attestation or verifier instructions, it provides enough context for an agent to use the tool correctly. A slightly higher score would require more depth on verification semantics.

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 already covers all parameters with descriptions (100% coverage). The tool description adds value by clarifying the relational constraint (exactly one of task_id/task_pda required), the default network behavior, and the return field list. This supplements the schema without redundancy.

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 "[READ] Fetch a portable AAS v0 attestation for a Verified Shillbot task." This clearly states the verb (fetch), resource (AAS v0 attestation), and context (for Verified Shillbot task). It distinguishes from sibling tools like shillbot_get_task_details or shillbot_check_earnings by focusing on attestation retrieval and detailing the two identifier pathways.

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 use task_pda (third-party) vs task_id (first-party) is provided, along with optional network parameter and default. The capture window constraint (between verify_task and finalize_task) and the 409 error for closed accounts are mentioned. While alternative tools are not explicitly contrasted, the description gives clear conditions for correct invocation.

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 the description reinforces with '[READ]' and details what information is returned (brief, blocklist, etc.). It adds value by specifying fields, but does not disclose additional behavioral traits beyond read-only nature.

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 concise sentences. First sentence provides purpose and scope, second adds usage guidance and parameter detail. 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 output schema, the description lists expected fields (brief, blocklist, etc.), providing a good sense of return values. Parameter count is low and well-documented. Could mention potential size of outputs, but overall complete enough.

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 schema: it states network default ('mainnet') and explains the consequence of mismatch ('on-chain accounts won't be found'). task_id is straightforward.

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 '[READ] Get full details for a Shillbot task' which clearly states the action and resource. It lists specific fields (brief, blocklist, brand voice, etc.) and explicitly distinguishes from siblings by advising to use this before calling shillbot_claim_task.

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 before calling shillbot_claim_task', providing clear guidance on when to use this tool. The optional network parameter is explained with default and behavior. No explicit when-not, but context is sufficient.

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 the description reinforces it with '[READ]'. It adds behavioral context about network mismatch ('Mismatched network = the on-chain accounts won't be found') and describes return fields. This is sufficient beyond the annotation, though more detail on rate limits or data freshness would raise the score.

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: three sentences that front-load the purpose and key details. Every sentence adds value: read indicator, return information, alternative tool guidance, and parameter note. 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 output schema, the description covers the key aspects: purpose, returned fields, parameter context, and sibling differentiation. It could mention pagination (though limit is in schema) or error conditions, but overall it is sufficient for a read-only list tool with good annotations.

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 value by clarifying the 'network' parameter's default value ('mainnet') and the consequence of mismatch. It also mentions optionality for 'min_price'. This goes beyond the schema descriptions, which are already present but less contextual.

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 action ('List open Shillbot marketplace tasks'), the resource ('Shillbot marketplace tasks'), and specifies returned data (task IDs, briefs, payment amounts, platforms). It also distinguishes from the sibling tool 'list_earning_opportunities' by noting that this is a deep query with Shillbot-specific details.

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 guidance on when not to use this tool: 'for cross-source aggregated discovery use list_earning_opportunities instead.' It also explains the optional 'network' parameter and its implications. However, it could be improved by stating explicit prerequisites or conditions for 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 the description reinforces this with '[READ] (CLIENT-SIDE)'. It adds valuable context: only shows tasks in 'submitted' state, requires the calling wallet to be the campaign client, and optional network parameter behavior. 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 two sentences, front-loaded with key purpose and state details. Every sentence adds value, and the structure is efficient with 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 the tool's simplicity (one optional parameter, no output schema), the description is complete: it explains what the tool returns (list of submitted tasks), prerequisites, and the optional filter. No missing info needed for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the optional network parameter ('mainnet' default, 'devnet' alternative) and its forwarding to the orchestrator for per-network state. This goes beyond the schema's 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 lists Shillbot tasks awaiting client review, specifies the 'submitted' state, and mentions the two possible follow-up actions (approve/reject). It effectively distinguishes from sibling tools like shillbot_approve_task and shillbot_reject_task.

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 when to use this tool ('to populate a review queue / inbox') and mentions a prerequisite ('requires a registered wallet'). It does not explicitly state when not to use it or provide alternatives beyond the implied distinction from sibling actions.

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 discloses that the tool is a stub, is marked as [READ] consistent with readOnlyHint: true, and explains the implicit reject path and return of expires_at. However, the tool name 'reject' suggests a write action, which creates some confusion despite the clarification.

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 verbose and includes multiple details (development status, roadmap, return field) in a single block. It could be more concise by separating the stub status from usage instructions.

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 it is a stub tool with no output schema, the description adequately covers the tool's behavior, limitations, and the return field expires_at. It provides sufficient context for an agent to understand 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?

Schema coverage is 100%, and the description adds meaningful context beyond the schema: it explains the network default, the task_id format, and that network mismatch leads to not finding on-chain accounts.

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 as rejecting agent-submitted content, even though it notes it is a v1 stub with an implicit reject path. It distinguishes from siblings like shillbot_approve_task.

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 some usage context, explaining that rejection is achieved by not calling shillbot_approve_task and letting the expire_task crank run. However, it lacks explicit when-to-use or when-not-to-use guidance compared to alternatives.

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

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

Annotations already mark destructiveHint, and the description adds context: it broadcasts on a chosen network, notifies the orchestrator, returns on-chain signature and confirmation, and warns of errors from cluster mismatch. 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 and front-loaded with the [STATE] label and main purpose. Every sentence adds value, though the labeling could be slightly clearer for new users.

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 purpose, usage, network specificity, error scenarios, and returns. Without an output schema, it could be more precise about return format, but overall it provides sufficient context 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 description coverage is 100%, so baseline is 3. The description adds significant value by explaining network parameter usage (default, mismatch error) and the relationship between build and submit tools, justifying a higher 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 the tool broadcasts a signed Solana transaction and lists specific actions (claim, submit, approve, verify, finalize). It distinguishes from sibling tools by noting those return unsigned transactions while this one submits the signed result.

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 pairing instructions with build tools (claim_task, submit_work, etc.) and warns about network mismatch causing errors. Also explains the optional network parameter with its default and the need to reuse the same network token from the build step.

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 discloses key behavioral traits beyond the destructiveHint annotation: it returns an unsigned base64 Solana transaction requiring local signing, explains the on-chain verification timeline (T+7d via Switchboard oracle), and notes that payment is released based on engagement metrics. It also highlights the impact of network mismatch.

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 that front-loads the purpose and earns its sentences with actionable details. It could be slightly more structured (e.g., bullet points) but is efficient and not 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 tool's complexity (3 parameters, destructive, no output schema), the description covers return value (unsigned transaction), workflow (sign locally, submit via other tool), and on-chain timeline. Some users might want examples of content_id values, but overall it is 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?

Schema coverage is 100% with descriptions for each parameter. The description adds value by clarifying content_id as 'YouTube video ID, tweet ID, game session ID, etc.' and specifying the format of task_id. The network parameter description is largely redundant with 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 starts with '[EARN: SOL] Submit completed work for a claimed Shillbot task.' which clearly identifies the action (submit completed work) and the resource (Shillbot task). It distinguishes itself from sibling tools like shillbot_claim_task and shillbot_approve_task by indicating this is the step after claiming, and references shillbot_submit_tx as a subsequent action.

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 a workflow: claim task, then submit work, then submit transaction via shillbot_submit_tx. It also warns about network mismatches. However, it does not explicitly state when not to use this tool or provide direct comparisons 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 declare destructiveHint=true, indicating a write operation. The description adds behavioral context (atomic oracle crank + on-chain verification, one fee) but does not fully disclose what on-chain state changes occur. It is consistent but could be more explicit.

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 and well-structured: starts with the core purpose and earnings opportunity, then prerequisites, steps, and parameter details. Every sentence provides value with 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?

Given the simple two-parameter schema and no output schema, the description covers the essential aspects: what the tool does, prerequisites, network options, and how to proceed. The return type (unsigned transaction) is implied. It could explicitly mention that the output is an unsigned transaction to be signed locally.

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 description adds value by specifying the task_id format (<campaign_id>:<task_uuid>) and explaining the network parameter's consequences (mismatched network leads to accounts not found).

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 builds an unsigned verify_task transaction bundled with a Switchboard oracle feed update. It uses specific verbs ('build', 'verify') and distinguishes from sibling tools like shillbot_approve_task and shillbot_claim_task by focusing on the verification step.

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 prerequisites: the verifier must have scored the task first and wait for a verification delay (5 min game-play, 7 days YouTube). It also instructs the next step: sign and submit via shillbot_submit_tx with action='verify'. However, it does not explicitly state when NOT to use this tool or list 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?

Discloses that it's a spending action ([SPEND]), returns an unsigned transaction, and details the output fields and required local steps. No contradiction with destructiveHint annotation.

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?

Well-structured and informative without fluff. Front-loaded with [SPEND] and covers all necessary details in a compact format.

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 output schema, description thoroughly explains return fields and usage, including value_wei as stake and EIP-1559 details. Also clarifies domain boundaries (EVM vs Solana).

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 parameter 'match' is described in both schema (100% coverage) and description. Description adds context on how to obtain the payload, slightly enhancing schema info.

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 builds an unsigned EVM createMatch transaction for funding a cross-chain match, and distinguishes from siblings like xchain_build_create_xmatch for Solana.

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 when-to-use: after receiving a matched status from xchain_find_match or xchain_match_status. Also specifies it's for EVM-leg players only, with alternatives mentioned.

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

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

Annotations show destructiveHint=true. Description adds cost (0.05 SOL), output format, and a security note about matchmaker not signing arbitrary input. Could mention reversibility or idempotency but overall strong for a mutation tool.

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

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

Single paragraph, front-loaded with cost and action, no redundancy, every sentence adds value. Structure logically flows from purpose to prerequisites to output to next step.

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 no output schema, description covers all needed aspects: purpose, when to use, output format, security note, and integration with sibling tool game_submit_tx. Fully addresses the complexity of a cross-chain build transaction.

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 in schema (100% coverage). Description adds context that no input is needed because it uses the current match state, and explains the output fields. Baseline for 0 params 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?

Clear verb and resource: 'Build the matchmaker-cosigned Solana create_xmatch transaction'. Distinct from siblings like xchain_build_create_match by specifying Solana-leg and cross-chain match context. Prerequisites (register wallet, only after matched) are stated.

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

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

Explicitly states when to call (after xchain_find_match returns 'matched'), who can use (Solana-leg players), and next steps (assemble and submit via game_submit_tx with action='create_xmatch'). Also warns against misuse (matchmaker only cosigns real pending match).

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 annotation destructiveHint: true is consistent with building a transaction that locks funds. Description adds behavioral context: operator's signature authorizes lock, no action needed, permissionless submission, return format indicating a transaction to sign. 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 a single efficient paragraph, front-loaded with '[STATE]' and each sentence adds necessary information. No redundancy or 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?

Despite no output schema, description fully specifies return fields. Explains flow, prerequisites, authorization, and leg restriction. Sufficient for an agent to correctly invoke the 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% with a description, but the tool description elaborates on the match payload's role and contents (operator signature, amount). This adds value beyond the schema, justifying a 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 clearly states the tool builds an unsigned EVM permissionless lockTranche transaction, specifying the resource and action. It distinguishes from sibling tools like xchain_build_settle and xchain_build_create_match by focusing on the lock step after funding.

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 prerequisites (both players have funded, pass match payload from xchain_find_match/status), when to use (before settle), and that lock is permissionless. Differentiates from Solana leg path and provides alternative 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?

Discloses beyond annotations: no args, resolves bound wallet, operator authorization, permissionless cranker, return format, and the order requirement (settle requires Locked). Annotations only provide destructiveHint=true, so description adds critical 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?

Description is informative but a bit long; however, every sentence adds value. Front-loaded with [STATE] and key action. Could be slightly tightened, but still efficient.

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

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

Despite no output schema, the description fully explains the return object and context. Covers prerequisites, leg specificity, permissionless nature, and next steps (sign and broadcast via game_submit_tx). 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?

No parameters, so schema coverage is 100%. The description confirms no args, which adds clarity but is not essential. Baseline 4 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 builds an unsigned permissionless Solana lock_xtranche transaction to lock the Solana leg's cross-chain payout tranche after both players have funded. It distinguishes from sibling tools like 'xchain_build_lock' by specifying the cross-chain context and a different action name 'lock_xtranche'.

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 (after both players funded), which leg (Solana-only), and alternatives (EVM players use xchain_build_lock). Also notes prerequisite: must land before settle.

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 destructiveHint=true, but the description adds that the tool builds an unsigned transaction and returns {to, data, value_wei, chain}, providing more detail. It also notes the refund is permissionless and EVM-leg only. This adds behavioral context beyond the annotation.

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 at ~80 words and front-loaded with the main purpose. It includes necessary details without fluff. However, the phrase 'EVM-leg only' could be implied and slightly redundant, 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?

Given the tool has 2 parameters and no output schema, the description covers input source, two kinds, permissionless nature, and return fields. However, it lacks error handling details or prerequisites for refundable state, leaving some gaps for a complete 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?

Schema coverage is 100% with descriptions for both parameters. The description goes further by explaining the meaning of each kind ('after claim window closes' for timeout, 'never locked certificate' for nocert) and implies the default value for kind. This adds value 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 the tool builds an unsigned EVM refund transaction to reclaim stake on the EVM leg of a cross-chain match. It specifies the verb 'Build', resource 'unsigned EVM refund transaction', and distinguishes from sibling tools like xchain_build_settle by focusing on refunds and referencing xchain_find_match/status as input.

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 pass the match payload from xchain_find_match/status and choose kind='timeout' or 'nocert' based on match state. It mentions the refund is permissionless and only costs gas, but does not explicitly state when not to use it or compare to the sibling tool xchain_build_refund_xmatch, leaving some 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 annotation already indicates destructiveHint=true. The description adds that the tool builds an unsigned transaction (not executed), is permissionless, and incurs only network fees. This contextualizes the destructive nature without contradicting the annotation, though it does not detail side effects.

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 structured with a clear opening statement of purpose, followed by parameter guidance, behavioral notes, and a summary of return value and next steps. It is slightly verbose due to the [STATE] tag and multiple clauses, but every sentence contributes useful 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 no output schema, the description compensates by explicitly stating the return format ({ unsigned_tx, blockhash, match_id }) and how to use the result (sign with Solana wallet, broadcast via game_submit_tx). All necessary context for invoking the tool is present.

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

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

Although schema coverage is 100% (baseline 3), the description adds significant context: it explains the source of the match payload (from xchain_find_match/status) and specifies when each kind value is appropriate (after claim window vs. never locked/cosigned). 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 (build), resource (unsigned Solana refund transaction), and purpose (reclaim stake on Solana leg of cross-chain match). It also explicitly distinguishes from sibling tools by noting that EVM players should use xchain_build_refund instead.

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 kind parameter (timeout after claim window, nocert for funded but never locked/cosigned), states the refund is permissionless, and directs EVM players to an alternative tool. This provides clear context for when this tool is appropriate 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?

Discloses that the operator never signs a user-supplied outcome and that the tool is read-only, consistent with readOnlyHint annotation. Explains return fields in detail.

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

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

A single dense paragraph; front-loads purpose but could be more structured. No wasted words, but slightly heavy for quick 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?

Despite no output schema, description lists all returned fields and explains the full workflow (signing, combining, settling on chains). Complete for a complex cross-chain operation.

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

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

No parameters, so baseline 3. Description adds value by detailing the return structure and subsequent actions expected from the outcome, exceeding 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 'Get the operator-cosigned OUTCOME of your cross-chain match, ready to settle' with specific verb and resource. It distinguishes from siblings by specifying after gameplay and handling equivocation via an alternate path.

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

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

Explicitly states when to call ('after gameplay') and when not ('equivocated match' use contested path). Provides clear context and alternative 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?

The description adds significant behavioral context beyond the destructiveHint annotation: it explains how to generate the preimage, that the commit must be kept secret, and that the function returns {both_committed}. It does not contradict the annotation.

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 (four sentences) and well-structured: [STATE] prefix, then purpose, method, return value, and next step. Every sentence adds 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's complexity in a cross-chain game, the description is comprehensive: it explains the preimage generation, submission, expected return, and next step (xchain_gameplay_status). No output schema is needed due to the described return.

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 already fully describes the 'commit' parameter with 100% coverage. The tool description repeats this information, adding limited new 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 the tool's purpose: 'Commit your guess for a cross-chain match.' It specifies the exact action (commit), the resource (guess for a cross-chain match), and the required preimage generation. It differentiates from siblings by mentioning the subsequent call to xchain_gameplay_status after both players commit.

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 clear sequential usage: after committing, call xchain_gameplay_status. It implies the correct context (first step of a two-step commit-reveal process) but lacks explicit when-not-to-use or alternative tool mentions.

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 have destructiveHint: true, and the description details the mutation: joining the queue, generating a session key, and co-signing. It discloses that the server never sees the private key and that it's testnet only, adding 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 a single dense paragraph but front-loads the purpose. Every sentence adds value; no wasted words. Could be slightly more structured but efficient.

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

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

For a tool with two parameters and no output schema, the description covers setup, process, return values (status and payload), and next steps. Adequate for complex cross-chain matching.

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

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

Schema coverage is 100%, and the description adds meaning: explains how to generate session_key and that tournament_id defaults to 1. It provides context not in the schema alone.

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

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

The description clearly states the tool's purpose: 'Join the cross-chain Coordination Game queue and get matched with a player on the opposite chain (Solana ↔ EVM).' It uses specific verbs and resources, and distinguishes from sibling tools like xchain_match_status and game_find_match.

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 usage context: requires a registered wallet, explains testnet only, and tells the agent to poll xchain_match_status when waiting. It lacks explicit when-not-to-use but gives clear guidance on prerequisites and follow-up.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool is read-only, returns specific checkpoint types, and instructs the agent to sign and submit via xchain_sign_checkpoint. This goes beyond a simple 'get status' and provides actionable 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 two sentences: the first states the purpose and what it returns, the second tells the agent what to do with the result. Every sentence earns its place with 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?

For a read tool with no parameters and no output schema, the description is fully complete. It covers the three possible states, the action to take on each, and the subsequent tool to call. No gaps remain.

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 zero parameters and 100% schema description coverage, so minimal burden on the description. The description adds no parameter details, which is acceptable since there are none. Baseline 4 applies.

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

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

The description starts with '[READ]' and clearly states it provides the 'what to sign next' view for cross-chain gameplay, listing specific checkpoints (step-2, revealed r_matchup, terminal). It distinguishes itself from sibling tools like xchain_match_status or xchain_sign_checkpoint by focusing on the game signing flow.

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 this tool ('once both players commit', 'once the step-2 checkpoint is stored', etc.) and what to do with the result (sign and submit). It does not explicitly mention when not to use it or list alternatives, but the context is clear enough for an 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?

Given readOnlyHint annotation, the description adds context: it is a polling operation, returns status with payload, requires a registered wallet. This provides behavioral insight beyond the annotation.

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 concise sentences, front-loaded with '[READ]'. No wasted words. Efficient and clear.

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

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

For a tool with no parameters and no output schema, the description fully explains the return values and usage context. It covers the prerequisite and requirement.

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 with 100% coverage, so baseline is 4. The 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?

The description clearly states the action (poll), the resource (cross-chain match), and the result ('waiting' or 'matched' with payload). It differentiates from the sibling 'xchain_find_match' by specifying 'Call after xchain_find_match returned "waiting".'

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 precondition: 'Call after xchain_find_match returned "waiting".' This guides the agent on when to use the tool. However, it does not mention when not to use it or list alternative tools.

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 destructiveHint=true, and the description reinforces the irreversible reveal action. It adds workflow context but does not elaborate on error cases or failure modes, which would enhance transparency further.

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 focused sentences plus a return note and follow-up steps. No redundant information, and the most critical precondition and action are front-loaded.

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 a cross-chain game reveal, the description covers precondition, input, output, and subsequent steps. No output schema, but the return format is described, making it sufficiently complete.

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

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

Schema covers 100% of the single parameter with a description. The tool description reiterates the same info without adding extra depth or constraints, so it meets the baseline but does not exceed it.

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 action (reveal your guess) and the specific context (cross-chain match after both players committed and co-signed step-2 checkpoint). It distinguishes from sibling tools like game_reveal_guess by specifying the cross-chain precondition.

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 (after both committed and co-signed step-2 checkpoint), what input to provide (preimage), expected return ({both_revealed}), and next steps (call xchain_gameplay_status then settle). This provides full guidance.

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

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

Annotations indicate destructiveHint=true. Description adds beyond annotations by detailing consequences of signing each step (releases r_matchup, makes match settle-ready) and return fields. 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?

Single sentence with clear [STATE] prefix indicating stateful action. Every word adds value. Well-structured and front-loaded.

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 steps: source of checkpoint, digest computation, submission format, return values. No output schema but return fields described. Sufficient for 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% and descriptions are already clear. Description reinforces relationship with xchain_gameplay_status but doesn't add significant new meaning 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?

Description clearly states verb 'co-sign' and resource 'cross-chain transcript checkpoint'. It distinguishes from sibling xchain_* tools by specifying the context of checkpoint steps 2 and 4 and reliance on xchain_gameplay_status.

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 steps: get checkpoint from xchain_gameplay_status, compute digest, sign with session key, submit. Explains meaning of steps 2 and 4 (release r_matchup, prepare settle). Lacks explicit when-not-to-use but context is sufficient.

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

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

Goes beyond readOnlyHint annotation by detailing return data structure (CAIP-2 id, native coin, etc.) and including a plain-language description of staking/settlement. Discloses testnet-only scope and mainnet gating. 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?

Well-structured with front-loaded '[READ]' indicator. Each of the 4 sentences adds value, though the list of return fields is slightly verbose. Efficient overall.

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 output schema, description fully enumerates return fields and provides plain-language context. Also includes usage guidance and limitations. Complete for a zero-parameter read-only 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?

No parameters required; schema coverage is 100%. Description compensates by explaining what the tool returns and its purpose, adding value 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?

Clear verb 'Discover' with resource 'chains'. Specifies return data and distinguishes from siblings by noting it should be called before register_wallet. Explicitly marks as read-only with no wallet required.

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 (before register_wallet) and provides context on testnet-only limitation. Does not mention when not to use or alternatives, but usage context is clear.

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