Swarm Tips — Aggregated AI Agent Activities

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 explains the read behavior: reads directly from Solana via getAccountInfo, no cache, returns derived metrics, and mentions that either PDA may be absent (null). This provides 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 informative without being overly verbose. It uses a structured format with tags like [IN DEVELOPMENT] and [READ], and lists fields clearly. However, the list of fields could be slightly trimmed without losing crucial info.

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 no output schema and two optional parameters, the description adequately explains the return values (derived metrics, null for absent PDAs) and the data sources. It covers the complexity of the on-chain lookup.

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 value by explaining the usage of wallet (omit for own wallet) and tournament_id (defaults to 1, per-tournament). This adds meaning 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 tool's purpose: 'Trustless on-chain reputation lookup'. It specifies the data sources (AgentState and PlayerProfile) and the derived metrics returned. This distinguishes it from siblings like agent_trust_score by detailing the on-chain accounts and metrics.

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 usage context: 'Pass `wallet` to query an agent; omit for your registered wallet' and 'tournament_id defaults to 1'. However, it does not explicitly mention when not to use this tool or compare it with siblings like agent_trust_score.

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

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

Annotations already declare readOnlyHint=true. The description adds substantial behavioral context: in-development status, partial-data tolerance, confidence metric, auditability via breakdown, and same on-chain read path as agent_profile. 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 informative and structured, front-loading the purpose and key behavioral traits. It includes a development marker, which adds length but is useful context. Could be slightly more concise, but overall 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?

Given the tool has 4 optional parameters, no output schema, and moderate complexity, the description provides sufficient context: return fields (breakdown, confidence), tolerance of partial data, and integration status. Completeness is good but not exhaustive.

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. The description adds meaning beyond schema: clarifies wallet omission defaults to caller's wallet, agent_rank integration status, curator_tier as optional folder, and tournament_id default. This aids correct invocation.

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) combining multiple signals, and distinguishes it from siblings like agent_profile (profile data) and shillbot tasks. The verb 'Composite' and listing of signals provide specificity.

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 (obtain composite trust score) and provides context on optional parameters. It mentions EigenTrust as a separate task, hinting at an alternative, but does not explicitly state when not to use this tool.

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

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

The description adds behavioral context beyond the readOnlyHint annotation by detailing the possible return values ('generating', 'complete' with video_url, 'failed'). However, it could mention that the tool is idempotent and suitable for polling.

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 exceptionally concise, using two sentences to convey purpose, usage hints, and return values with no unnecessary words or repetition.

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

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

For a simple read tool with one parameter and an output schema not provided, the description adequately covers the return values and purpose. It could be slightly more detailed about the polling context, but overall it is 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?

The input schema covers the single parameter with a description, and the description does not add further semantic meaning beyond what the schema already provides. The baseline is 3 due to high schema coverage.

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

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

The description clearly states the verb 'Check' and the resource 'video generation request', with a purpose that distinguishes it from sibling tools like generate_video. The '[READ]' prefix further clarifies it as a read operation.

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?

While the description implies usage after calling generate_video (by referencing 'session ID returned by generate_video'), it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or best practices.

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 is a read operation ([READ]), wraps two list tools, and returns entries with a 'vertical' field for routing. Annotations already indicate readOnlyHint=true, and the description adds substantial behavioral context beyond that.

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

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

Two sentences front-loaded with purpose and usage. No redundant text. The '[IN DEVELOPMENT]' prefix is a minor signal but does not detract from conciseness.

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

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

Given full schema coverage and annotations, the description is complete: it explains the tool's purpose, usage guidance, key behavioral traits (wrapping, vertical field), and appropriate alternatives. No gaps for a search tool without output schema.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). The description adds minimal extra meaning beyond what is already in the schema (e.g., keyword matching details), 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?

Clearly states it is a unified search across earn and spend verticals, using specific verbs and resources. Distinguishes from siblings by naming the wrapped tools (list_earning_opportunities, list_spending_opportunities) and the alternative per-vertical tools.

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

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

Explicitly tells when to use this tool (when unsure of vertical or wanting cross-vertical keyword search) and when not to (for deep per-vertical control, use 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 declare readOnlyHint=true, and the description confirms it is a READ operation. Adds important behavioral details: return states ('queued' vs 'in_game'), polling interval, and dependency on prior call to game_find_match.

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

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

Two sentences, no filler, front-loaded with purpose and immediate actionable guidance. 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?

For a zero-parameter, no-output-schema tool, the description fully explains purpose, expected return values, usage context, and polling frequency. Nothing is missing given the tool's simplicity.

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

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

Input schema has no parameters and 100% description coverage. The description does not need to add parameter details. Baseline for zero parameters is 4, and no additional explanation is required.

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 for a match with an opponent and specifies the return values ('queued' or 'in_game' with game_id). This distinguishes it from sibling tools like game_find_match and game_get_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 polling guidance: 'Poll every 2-3 seconds after calling game_find_match.' Clearly instructs when to use this tool and how to use it correctly.

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. Description adds that the tool returns an unsigned commit transaction and that stake was locked previously. No contradiction, but could mention permissions or reversibility.

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 with no wasted words. Action and meaning in first sentence, workflow and clarification in second.

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?

Simple tool with one parameter, description fully explains the commit workflow, next steps, and financial implications. No output schema needed as return type is 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?

Schema covers the only parameter with description. The description adds context by explaining the meaning of 'same' (opponent is same type) and 'different', going beyond the schema's generic text.

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

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

The description clearly states the action: 'Commit your guess on-chain' with explicit options 'same' or 'different'. It distinguishes from siblings like game_reveal_guess and game_submit_tx by specifying the return of an unsigned commit transaction.

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 a clear workflow: commit guess, then sign and submit via game_submit_tx, then poll game_reveal_guess. Also clarifies that no funds move at this step, which sets expectations correctly.

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 discloses the locked ante, win/loss financial outcomes, and negative-sum nature. 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?

Two packed sentences with front-loaded action. Every sentence is informative, though the first sentence is slightly long. 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 usage flow, financial implications, prerequisites, and parameter defaults. Given 2 parameters and no output schema, it is largely complete. Could mention that the transaction is unsigned.

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 contextual meaning: network defaults, tournament_id behavior, and warnings about mismatched networks. Adds value beyond raw schema.

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

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

The description clearly states the tool builds an unsigned deposit_stake transaction to join the matchmaking queue, with a specific verb and resource. It distinguishes from siblings like game_submit_tx by outlining the intended 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?

Explicitly instructs to sign locally and submit via game_submit_tx, and notes prerequisite (register_wallet). Provides guidance on tournament_id (omit unless needed). Could be improved with an explicit 'when not to use' statement.

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

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

Annotations declare readOnlyHint=true, and the description aligns with '[READ]'. It goes beyond by explaining the scoring formula (wins^2 / total_games), adding value. No contradiction. Does not discuss rate limits or auth, but for a read-only tool this is acceptable.

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

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

Two sentences, no wasted words. First sentence states core purpose and key detail (scoring formula). Second sentence provides critical parameter guidance. Very 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?

The tool has no output schema, but the description compensates by stating it shows 'top players ranked by score (wins^2 / total_games).' It does not mention default limit of 20 or max 100, but those are in the schema. Overall, it provides enough context for an agent to understand what the tool returns and how to use it.

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

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

Schema description coverage is 100% (both limit and tournament_id have schema descriptions). The description adds extra context: 'Tournament ID defaults to 1 (the only active tournament; omit unless you know what you're doing),' which is more helpful than the schema alone. This justifies a score above the baseline 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 explicitly states 'Get the tournament leaderboard for the Coordination Game' with a specific verb (READ) and resource (leaderboard). It includes the ranking formula (wins^2 / total_games), clearly distinguishing it from sibling mutation tools like game_commit_guess or game_reveal_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?

Provides good guidance on the tournament_id parameter: 'Defaults to 1 (the only active tournament; omit unless you know what you're doing).' This helps agents avoid unnecessary parameter specification. However, it does not explicitly mention when to prefer this tool over other game tools, though the purpose is distinct enough.

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

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

Annotations already indicate readOnlyHint=true; the description adds that messages are drained (each returned once) and implicitly scoped to the active game, which provides useful 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 three concise sentences, front-loaded with the key verb [READ], and every sentence adds value without 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?

For a tool with zero parameters and no output schema, the description adequately explains the drain behavior and session scoping; however, it could hint at the return format (e.g., array of strings).

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

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

With zero parameters and 100% schema coverage, the description confirms no parameters are needed and adds meaning by explaining the implicit session-based scoping.

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 operation to get chat messages from the opponent since the last call, and distinguishes from siblings like game_send_message by highlighting the drain behavior and implicit scoping.

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 explains when to use (get new messages) and mentions the message buffer drain, but does not explicitly exclude use cases or compare with related tools like game_send_message.

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 annotations by stating the tool returns on-chain game state including both players' guesses and resolution status. Annotations already mark it as read-only (readOnlyHint=true), so the description supplements with detailed behavioral info without contradiction.

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

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

The description is two sentences, front-loaded with '[READ]' to indicate operation type. Every sentence is meaningful with no wasted words, making it 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 the tool's simplicity (no parameters, no output schema), the description adequately explains what it does and what it returns (on-chain game state, guesses, resolution status). It is complete enough for an AI agent to understand its purpose and output.

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

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

The tool has no parameters (0 param count, 100% schema description coverage), so the baseline score is 4. The description does not need to add parameter details, and it correctly omits them.

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

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

The description clearly states the tool retrieves the result of the current or most recent game, specifying it returns on-chain game state including both players' guesses and resolution status. It uses a specific verb ('Get') and resource ('result of your current or most recent game'), distinguishing it from sibling tools like game_reveal_guess 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?

The description indicates the tool is for getting game results, but provides no explicit guidance on when to use it versus alternative tools (e.g., game_reveal_guess or game_check_match). Usage is implied but not elaborated.

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 tool returns an unsigned transaction to be signed and submitted, and that it resolves the game. While annotations give destructiveHint=true, the description does not explicitly state the action is irreversible, but 'resolves the game' implies finality.

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

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

Four sentences efficiently convey the state-checking polling logic, signing instructions, and game outcome implications. 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 and no output schema, the description thoroughly covers the tool's behavior: polling, signing, submission, and consequences. It also mentions the negative-sum nature of the game.

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

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

No parameters exist, so the description has no burden to explain parameters. The baseline score of 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?

Description clearly states the tool checks if both players committed and returns an unsigned reveal transaction. It distinguishes itself from related tools like game_commit_guess and game_submit_tx by specifying its role in the game 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?

Provides explicit guidance: poll every 3-5 seconds if waiting, then sign the returned transaction and submit via game_submit_tx with action='reveal_guess'. Also explains the consequences of correct vs. wrong guesses.

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?

No annotations provided, so description must disclose behavioral traits. It explains implicit session scoping and resolution chain, but omits details on rate limits, error handling, or response behavior.

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

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

Two sentences with no waste. Purpose is front-loaded, and every sentence adds necessary context. Highly 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 simple send operation, the description covers purpose, parameter style, and session scoping. Lacks output details, but no output schema exists. Minor gap 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?

Input schema has 100% coverage for the 'text' parameter. Description adds value by advising to keep messages casual and human-like, extending beyond the schema's basic type 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 the tool sends a chat message to an anonymous opponent during the game. It uses a specific verb ('send') and resource ('chat message'), and distinguishes itself from siblings like game_get_messages.

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

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

No explicit guidance on when to use this tool vs alternatives. The description includes style advice ('keep messages casual') but no exclusions or comparisons to sibling 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 confirms the broadcasting behavior. It adds specificity about the action parameter, but no extra behavioral details like side effects or permissions.

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 very concise, consisting of two sentences that front-load the purpose. Every word is necessary and no information is repeated.

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

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

The tool has no output schema, and the description does not explain return values or error conditions. It adequately explains the input context but lacks completeness for expected outcomes.

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 adds no additional semantic meaning for individual parameters 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 submits a signed Solana transaction for game steps, listing all five possible actions. It distinguishes from siblings by noting it merely broadcasts a transaction built by a prior tool 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?

The description explains the tool is used after building the unsigned transaction, providing clear context. However, it does not explicitly state when not to use it or mention 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?

Discloses cost (5 USDC), payment protocol (x402), two-phase flow, and that it returns a session_id for polling. The destructiveHint annotation aligns with spending money, and no contradictions exist.

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?

While the description is a single paragraph, it is information-dense and efficient. It could be slightly more structured (e.g., bullet points), but every sentence adds necessary value and front-loads purpose and cost.

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 the full flow: payment, generation, polling, and earning opportunity. Lacks some details like exact response structure and video constraints, but given the complexity and absence of output schema, it is reasonably complete.

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

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

Schema description coverage is 100%, but the description adds significant context: explains the two-phase flow, that tx_signature is omitted on first call, payment details, and the tip. This goes well 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 'Generate a short-form video from a prompt or URL', specifying the action, resource, and inputs. It distinguishes from sibling tools like check_video_status and shillbot_submit_work through the payment and submission 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?

Provides explicit step-by-step instructions: first call without tx_signature for payment instructions, then pay and call again with tx_signature. Includes tip about submitting to Shillbot to earn back, and references sibling tools for polling and submission.

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

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

Annotations already indicate readOnlyHint=true. The description adds that it is in development and read-only, describes the data included (source, title, reward, etc.), and clarifies that swarm.tips does not mediate external claims. This adds useful 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 informative and well-structured, starting with status labels then explaining purpose and details. It is somewhat dense but each sentence adds value, though it 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?

The description fully covers the tool's purpose, what each entry contains, and how to interpret results (including the claim_via field). Given no output schema and all parameters documented, it is complete for an aggregated listing 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?

All parameters have descriptions in the schema (100% coverage). The description adds extra context, such as that listings without a USD estimate are excluded when min_reward_usd is set, and implies valid source values. This enhances understanding beyond the schema.

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

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

The description clearly states it is an aggregated list of earning opportunities across the swarm.tips ecosystem, specifying included sources (Shillbot tasks and external bounties) and entry fields. It distinguishes itself as the universal entry point, differentiating from per-source listing tools.

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

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

The description explicitly advises preferring this tool over per-source listing tools when they exist. It explains how to claim tasks: for first-party sources via the claim_via field, and for external sources through the source platform. This 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?

The description explicitly marks the operation as [READ], consistent with readOnlyHint=true, and adds behavioral context such as returning empty on clusters without the extension-registry deployed, which goes 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 with four sentences, each providing essential information: purpose, optional filters, return format, and edge case. No redundant or vague phrasing.

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

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

Despite lacking an output schema, the description fully specifies the return format ({ extensions: [{ extender, recipient, bond_lamports }], count }) and documents the empty cluster behavior, making it complete for a simple list tool.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds minor context like 'optionally' and confirms base58 format, but does not significantly enhance parameter meaning 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 lists active extension-credit obligations with a specific verb ('List'), resource ('extension-credit obligations'), and details about structure (extender, recipient, bond_lamports) and optional filters, distinguishing it from any sibling tools.

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

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

The description indicates when to use the tool (to list extension-credit obligations) and mentions optional filters, but it does not provide explicit exclusions or alternative tools. Given the unique purpose and no similar sibling tools, this is clear enough.

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

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

Annotations show readOnlyHint=true; description adds behavioral context: it's an aggregated list with v1 focus on first-party services, external spend sources deferred. 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?

Single paragraph is well-structured and front-loaded with flags '[IN DEVELOPMENT] [READ]'. Contains necessary detail without excessive length.

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

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

With no output schema, the description fully explains what each entry contains (title, description, source, category, cost, USD estimate, redirect URL, spend_via). Complete for discovering spending opportunities.

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 3 parameters with descriptions (100% coverage). Description adds overall context but no extra meaning for individual parameters beyond what schema provides. Baseline 3 appropriate.

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

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

Clearly states it returns an aggregated list of paid services agents can spend on, distinguishing v1 first-party scope and mentioning specific fields like 'spend_via'. Differentiates from sibling 'list_earning_opportunities'.

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 ('discover where to spend') and what to do next: for first-party services use the named 'spend_via' tool, for external navigate to URL. Also notes development status and scope limitations.

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 substantial behavioral context beyond the readOnlyHint annotation: it explains the computational method (EigenTrust anchored to trusted root), the gating condition (>=1 received extension), and edge cases (empty/0 on clusters without extension registry). This fully discloses the tool's behavior.

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

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

The description is concise and well-structured: four sentences that front-load the main purpose, then provide technical details, return value summary, and edge case. 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?

The description covers the return fields, computation, and edge cases, making it complete for a simple tool with one optional parameter and no output schema. Minor improvement could include a note about the output format or example, but it is 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?

The input schema has 100% description coverage with a clear explanation of the single optional parameter (wallet). The description does not add any additional meaning or usage tips beyond the schema, so the 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 the tool performs a READ operation to retrieve an agent's credit web position (0..1), specifying the computation method (EigenTrust) and condition (>=1 received extension). It mentions the return fields, but does not explicitly distinguish from sibling tools like agent_trust_score, relying on implicit differentiation.

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

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

The description provides context by noting that this signal feeds agent_trust_score, implying a relationship, but does not give explicit guidance on when to use this tool versus alternatives. There are no when-to-use or when-not-to-use instructions.

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?

In the absence of annotations, the description fully discloses behavior: non-custodial nature, return values for Solana (address + balance) and EVM (CAIP-10 only), and Firestore persistence. No contradictions with annotations exist.

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

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

The description is front-loaded with the purpose and includes necessary details like key formats and cross-chain guidance. It is somewhat verbose with examples and repeated statements (e.g., non-custodial) 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?

Given one parameter and no output schema, the description covers registration process, key types, return values, and persistence. It lacks error handling details but is otherwise complete 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?

The input schema describes 'pubkey' as Base58-encoded Solana, but the description adds that it can also be an EVM 0x address, resolving a schema limitation. This additional context compensates for the schema's incomplete 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's purpose: to register a wallet for using swarm.tips tools that handle funds. It specifies supported key types (Solana base58 or EVM 0x) and distinguishes between same-chain and cross-chain use cases, providing clear differentiation from sibling tools.

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

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

The description advises calling xchain_supported_chains first for cross-chain and notes that one Solana registration covers all same-chain products. It implies when to use (before fund-touching tools) but does not explicitly state when not to use it.

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

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

Annotations already provide readOnlyHint=true; description adds '[IN DEVELOPMENT]' (important for reliability), explains the 30-entry directory with three tiers, sorting order, and that it programmatically exposes the same directory as swarm.tips/discover. Provides 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?

Description is somewhat lengthy but each sentence adds value. It is well-structured: starts with status and purpose, then details filters and sorting, ends with usage guidance. Could be slightly more concise but still 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?

Given no output schema, the description does not explain return values. However, it covers directory size, tiers, ordering, and relationship to website. This is adequate for a search tool but could include output format hints.

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 descriptions cover all 4 parameters (100% coverage). Description adds context: mentions substring matching for query and category, and clarifies sorting order (first-party → vetted → discovered). This adds meaning 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 it searches a curated directory of MCP servers, specifies the source (Layer 3), three vetting tiers, and filtering options. It differentiates from sibling 'discover_opportunities' by noting this tool is for finding servers, not opportunities.

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: 'Use this when an agent needs to find an MCP server for a capability... instead of an opportunity (which discover_opportunities covers).' Also notes it is in development and read-only.

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=true. The description adds that the tool returns an unsigned transaction for local signing, explains the verification timeout anchoring to prevent freeze attacks, and clarifies on-chain wallet match enforcement. It provides good context but could be more explicit about immediate 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 long but efficient, with every sentence providing value. It front-loads the main action and groups related information. Minor redundancy could be trimmed.

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

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

Given the tool's complexity (multi-step workflow, network constraints, security concerns), the description covers all essential aspects: prerequisites, return value, network handling, follow-up action, and references to sibling tools. No output schema exists, but the return value is 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?

Schema coverage is 100%, so baseline is 3. The description adds extra context: network default and the effect of mismatch ('on-chain accounts won't be found'), and clarifies task_id format as '<campaign_id>:<task_uuid>'.

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 action: 'Approve agent-submitted content for a Shillbot task you funded.' It specifies the return of an unsigned transaction and distinguishes from sibling tools like shillbot_reject_task and shillbot_list_pending_approval.

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 that only the original task client may call, recommends using shillbot_list_pending_approval to find tasks, mentions the optional network parameter, and explains the follow-up step of submitting the transaction via shillbot_submit_tx.

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 wallet requirement and network forwarding behavior, providing useful 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?

Two sentences front-load purpose and contents, then prerequisite and parameter. No fluff, 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?

Description covers what the tool returns (fields listed), prerequisites, and parameter. Lacks output schema but fields are described; no mention of pagination or limits, but adequate for a simple read tool.

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

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

Schema coverage is 100%, so description adds marginal value. It reiterates default and possible values for network, and explains forwarding behavior, but schema already says similar.

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 verb 'Check' and resource 'Shillbot earnings summary', listing included fields (total earned, pending payments, etc.). Distinct from sibling tools like shillbot_get_task_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?

Specifies prerequisite of registered wallet and default network value. Does not explicitly state when not to use or compare to alternatives, but the purpose is self-evident.

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 non-custodial nature ('MCP server never sees your private key') and that it returns an unsigned transaction for local signing. Annotations only have destructiveHint=true; description adds key state and security 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?

Concise, front-loaded with state and action. Every sentence adds value: workflow, prereqs, optional param, security. 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 the entire flow: what it does, what it returns, next steps (submit_tx), prerequisites, and network choice. No gaps given the tool's role in the broader suite.

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 description adds valuable context: explains task_id format and network options with default. Goes beyond schema by describing expected values and sources.

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+resource ('Claim a Shillbot task') and specifies it returns an unsigned transaction. Distinguishes from siblings by outlining the claim-then-submit 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?

Explicit prerequisite: 'Requires a registered wallet (call register_wallet first).' Describes the two-step process and optional network parameter with default. Lacks explicit when-not-to-use but sufficient 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 have readOnlyHint=true, and the description declares '[READ]' and explains it reads on-chain and Firestore state to return next_action. It does not claim to modify state. It details behaviors like returning wait actions with timestamps and handling network mismatches.

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: starts with a summary, then explains lifecycle, waits, and recall pattern. Every sentence adds value, and it is front-loaded with '[IN DEVELOPMENT] [READ]'. It is appropriately sized for the complexity.

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

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

No output schema exists, so the description compensates by detailing return values: a structured next_action block with tool/arguments, wait with not_before timestamp, or done. It covers the lifecycle and external waits 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 coverage is 100%, and the description adds meaning: it explains task_id format and that network is optional with default 'mainnet', and warns that mismatched network leads to accounts not found. This goes beyond the schema.

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

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

The description clearly states it is a 'single-call wrapper' that collapses the multi-step Shillbot task lifecycle into a loop. It specifies the action: pass task_id, get next_action. It distinguishes from siblings by being the orchestrator that determines the next step, unlike specific action tools like 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?

It explicitly describes when to use: to get the next step in a task lifecycle. It explains return types (next_action tool/wait/done) and instructs to 'Re-call after each step (or after the wait elapses).' It also mentions unavoidable waits, guiding the agent on expected delays.

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 matches destructiveHint annotation and adds valuable context: it is permissionless, requires signing and separate submission, and includes 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?

Three sentences, front-loaded with purpose, no redundant information. 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 2-parameter tool without output schema, the description covers purpose, usage, parameters, follow-up actions, and trust model. Could mention error conditions or return value, but overall 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?

Schema coverage is 100%. Description adds meaning by explaining network optionality, default, and forwarding behavior; task_id format from list_available_tasks is also clarified.

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 'Finalize a verified Shillbot task' and details the actions (transfers payment, protocol fee, closes account), distinguishing it from related tools like shillbot_claim_task or shillbot_complete_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?

Explicitly states 'Permissionless — anyone can call after the challenge deadline.' Provides instructions to sign and submit via shillbot_submit_tx. Does not explicitly list alternatives but context makes the timing clear.

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

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

Annotations declare readOnlyHint=true, and the description adds that it is a READ operation, does not sign, and describes error conditions (409 for closed accounts). Aligns with and supplements annotations.

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

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

The description is fairly long but well-structured, starting with tags, then parameters, then notes. Each sentence adds value, though some redundancy with schema exists. Not overly verbose given complexity.

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

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

No output schema, but description lists all returned fields and covers error cases, timing constraints, and network handling. Comprehensive for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema: explains canonical nature of task_pda, use cases for each identifier, and behavior on network mismatch. Adds meaningful value.

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

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

The description clearly states it fetches a portable AAS v0 attestation, specifying the two identifiers (task_pda or task_id) and optional network. It distinguishes from sibling tools like shillbot_get_task_details and shillbot_verify_task by focusing on attestation retrieval.

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

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

Explicitly explains when to use task_pda (third-party) vs task_id (first-party), requires exactly one, and notes the capture window between verify_task and finalize_task. Provides clear context for selection.

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

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

Annotations already mark readOnlyHint=true, and the description reinforces this with '[READ]'. It adds valuable behavioral context by warning that a mismatched network means 'the on-chain accounts won't be found', which goes 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 two sentences: first states purpose and outputs, second gives usage tip and parameter note. It is front-loaded and 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?

No output schema exists, so the description compensates by listing the returned fields (brief, blocklist, brand voice, platform, payment amount, deadline). It also covers the optional network parameter. This is sufficient for an agent to understand what the tool returns and how to use it.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds the default value for 'network' ('mainnet' or 'devnet') and the consequence of mismatch, enhancing the schema 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?

The description begins with '[READ]' and clearly states 'Get full details for a Shillbot task' followed by a list of returned fields. It distinguishes itself from sibling tools like shillbot_list_available_tasks by focusing on full details for a specific 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 advises 'Use this before calling shillbot_claim_task', giving clear contextual guidance. It does not mention when not to use or alternatives besides the implied sibling relationship, but the provided usage 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 indicate readOnlyHint=true; description adds context that it's a read operation on on-chain escrow, returns specific fields, and that network parameter affects account lookup. No contradictions, but could mention idempotency or rate limits.

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

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

Every sentence adds value: read indication, purpose, return info, sibling differentiation, network parameter. Front-loaded and 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 mentions return fields (task IDs, briefs, etc.). Covers main features, optional parameters, and network behavior. Sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, baseline 3. Description adds meaningful context for the network parameter (orchestrator dispatch, mismatched network behavior) beyond the schema description. Limit and min_price are adequately described in 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 'List open Shillbot marketplace tasks' with a specific verb-resource pair and distinguishes itself from the sibling list_earning_opportunities by noting this is a Shillbot-specific deep query versus cross-source aggregated discovery.

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 provides when-to-use guidance by contrasting with list_earning_opportunities, directing agents to use that sibling for aggregated discovery. Also explains the optional network parameter with default and effect of mismatch.

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 adds behavioral context: it's a read of 'submitted' state tasks, client-side, requires client wallet. It outlines the state lifecycle and the calling wallet constraint, which are critical behaviors beyond annotations.

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

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

Three sentences, each providing essential information: purpose, state/requirements, and optional parameter. No filler. The development status and read hint are front-loaded. Every sentence earns its place.

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

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

For a simple list tool without output schema, the description covers purpose, state, prerequisites, and parameters. However, it lacks details on the output structure (e.g., fields of each entry) or pagination/limits. Given the annotations and schema completeness, this is a minor gap but still functional.

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

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

Schema coverage is 100% for the single parameter 'network'. The description adds value by explaining the default ('mainnet') and alternative ('devnet'), and its purpose: 'forwarded to the orchestrator which dispatches 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 specifies the verb ('list') and resource ('Shillbot tasks awaiting your client review'), distinguishes from sibling tools like shillbot_approve_task and shillbot_reject_task by stating the task state ('submitted') and the action required. It also mentions the requirement for a registered wallet, adding specificity.

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: 'populate a review queue / inbox'. Implicitly excludes use for approved/rejected tasks via mention of shillbot_approve_task and shillbot_reject_task. Also states prerequisites (registered wallet, calling wallet must be client) and optional network parameter with defaults.

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 in development, a stub, and read-only (though annotations already declare readOnlyHint=true). It explains the implicit reject mechanism and the `expires_at` response. However, there is a contradiction: the description says 'Reject agent-submitted content' but annotations mark it as read-only. This contradiction undermines transparency, as the description implies a write operation while the annotations indicate no state change.

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

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

The description is front-loaded with development status and read-only hint, which is helpful. However, it is relatively verbose, including roadmap details and explanation of the implicit mechanism. While every sentence provides information, the length could be reduced without losing essential guidance. The structure is clear but not maximally 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 stub status and lack of output schema, the description provides a reasonable amount of context: it explains the implicit rejection, the `expires_at` response, and the development state. However, the contradiction between the name/description and annotations reduces completeness, as an agent might be misled about the tool's actual capabilities. The sibling tools list includes many shillbot_* tools, but the description does not differentiate from them sufficiently.

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

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

The input schema covers both parameters with descriptions (100% coverage). The description adds value by clarifying that `network` is optional with default 'mainnet', and that mismatched networks will fail to find on-chain accounts. This additional context helps the agent use the parameters correctly. The description also mentions the `expires_at` field in the response, which is not in the schema but adds utility.

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 it is a stub for rejecting agent-submitted content but clarifies that the reject path is implicit in v1. It does describe that the tool returns an `expires_at` timestamp. However, the purpose is muddled by the contradiction between the name (reject_task) and the actual behavior (currently a read-only endpoint). The distinction from sibling tools like shillbot_approve_task is implied but not explicit.

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

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

The description explains the implicit rejection mechanism (don't call approve_task) and notes that a first-class instruction is on the roadmap. It mentions that the response includes `expires_at` for scheduling. However, it does not clearly state when to use this tool versus the alternative of simply not approving. The sibling context includes shillbot_approve_task, but the description lacks explicit guidance on tool selection.

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

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

Annotations indicate destructiveHint=true. Description adds that it notifies orchestrator, returns on-chain signature and confirmation message, and gives error conditions. 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?

Single dense paragraph that front-loads main purpose. Could be slightly more structured but 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?

Explains return values (signature, confirmation) and error conditions. No output schema, but description covers key behavioral aspects. Complete for a submission 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 covers 100% of parameters, but description adds context like network mismatch error details and usage hints for action field. Enhances understanding beyond schema.

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

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

The description clearly states it broadcasts a signed Shillbot Solana transaction and returns signature and confirmation. It identifies specific actions (claim, submit, approve, verify, finalize) and distinguishes from sibling tools that return 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?

Explicitly says to pair with unsigned-transaction tools and submit the signed result. Warns about network mismatch errors and advises to use the same network token as the build tool.

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

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

The description adds significant behavioral context beyond the destructiveHint annotation: it returns an unsigned transaction, requires local signing, and details on-chain verification after 7 days with Switchboard oracle. It also warns about network mismatch errors.

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

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

The description is a single paragraph but well-organized, starting with an incentive, then the action, then the workflow. It is concise and front-loaded with key information.

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

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

For a tool with 3 parameters and no output schema, the description is remarkably complete. It explains the return value, the follow-up action, the verification process, and payment conditions, leaving no major gaps.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by providing examples (YouTube video ID, tweet ID) for content_id and clarifying the task_id format and network options.

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 completed work for a claimed Shillbot task. It uses a specific verb ('submit') and resource ('completed work'), and distinguishes it from sibling tools by explaining the need for a subsequent transaction via shillbot_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 (after claiming a task), what parameters to provide, and the next step (sign and submit via shillbot_submit_tx). It also notes the optional network and default. While it doesn't explicitly list when not to use, the context is clear.

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

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

Annotations only have destructiveHint: true, which is mild. Description adds value by clarifying the tool builds an unsigned transaction (non-destructive) but is part of a destructive chain. It also discloses atomic oracle update. Could mention error handling or permission requirements.

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 5-6 sentences, front-loaded with core purpose. Every sentence adds value. Slightly dense 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?

No output schema, but description clearly explains the output is an unsigned transaction to be signed locally. Combined with clear steps and prerequisites, the description fully equips the agent to use the tool correctly.

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

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

Schema coverage is 100% and parameter descriptions are present. Description adds extra context: task_id format (campaign_id:task_uuid) and network default (mainnet). This aids correct usage beyond schema.

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

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

The description starts with a specific verb (Build) and resource (unsigned verify_task transaction) and clearly differentiates from sibling tools like shillbot_submit_tx by explaining the tool builds a transaction for later submission.

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 scoring and waiting delay (5 min/7 days). Provides explicit steps: sign locally then submit via shillbot_submit_tx with action='verify'. Also covers network parameter behavior.

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 includes the [SPEND] tag and details the output format ({ to, data, value_wei, ... }) beyond the destructiveHint annotation. It explains that value_wei is the stake sent as native ETH, adding behavioral context. The destructiveHint annotation already signals mutation, so the description adds useful but not fully necessary 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 paragraph with four clear sentences: purpose, input requirement, output description, and usage limitation. No wasted words; every sentence adds value and information is 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 one parameter, no output schema, and a destructiveHint annotation, the description covers input, output, and limitations. It could mention prerequisites like having a wallet, but the instruction to 'fill gas/nonce/chainId locally' implies the user is already in a wallet context. Overall, it is sufficiently complete for the tool's complexity.

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

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

The only parameter 'match' is described in the schema, but the description adds essential context: it must come from specific tools and only when status is 'matched'. With 100% schema coverage, this extra guidance elevates the score above baseline 3.

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

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

The description clearly states the tool builds an unsigned EVM createMatch transaction to fund a leg of a cross-chain match. It uses a specific verb ('build') and resource ('unsigned EVM createMatch transaction'), distinguishing it from sibling tools like xchain_find_match and xchain_match_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?

Explicitly tells the agent to pass the 'match' payload from xchain_find_match or xchain_match_status (when status is 'matched'). Also specifies that this is for EVM-leg players only, with an alternative path for Solana, providing 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?

Discloses SOL spend (0.05 SOL), return format, and importantly notes that the matchmaker only cosigns for the real pending match, not arbitrary input. This adds significant context beyond the 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?

Description is efficient and front-loaded with key information (spend, purpose), but the single paragraph structure could be improved with bullet points or clearer separation of steps.

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 covers prerequisites, inputs (none), return values in detail, and next steps. Includes a security note about matchmaker cosigning, making it highly complete for a zero-parameter 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 exist; schema coverage is 100%. The description adds value by explaining the tool's behavior and output, which is appropriate for a no-parameter tool.

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

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

Description clearly states it builds a transaction to fund a cross-chain match, specifies Solana-leg players only, and enumerates the return fields. It implicitly distinguishes from sibling xchain_build_create_match by focusing on Solana leg.

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 call after xchain_find_match returns 'matched', and provides step-by-step instructions including assembling and broadcasting via game_submit_tx. Also mentions prerequisite of registering a Solana wallet.

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, and description confirms building a lock transaction. It discloses permissionless nature (anyone submits, pays gas), output structure, and prerequisites. No contradiction with annotations.

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

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

Description is a single paragraph with multiple sentences covering all key points. It starts with a clear state tag and is well-organized, though could benefit from slight structuring.

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 prerequisites, output, constraints (EVM leg only), and references sibling tools. No output schema exists, so description adequately describes return values. Very complete given tool 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?

The schema describes 'match' as the payload from xchain_find_match/status, but the description adds context: the payload contains operator's signature and the locked amount is from the signed cert. This enriches understanding beyond the schema's brief 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's purpose: 'Build the unsigned EVM permissionless lockTranche transaction to lock your leg's cross-chain payout tranche after both players have funded.' It uses specific verbs and resource, and distinguishes from siblings by specifying EVM leg only and referencing related tools.

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

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

Provides explicit guidance: use after both players have funded, before settle (requires Locked status), and that Solana leg uses a different path. It specifies the input source (match payload from xchain_find_match/status) and notes no operator action needed.

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 include destructiveHint: true, indicating potential mutation. The description adds that the refund is permissionless and the user only pays gas, and returns to, data, value_wei, chain for signing. This provides behavioral context beyond annotations, though it could also mention that the returned transaction needs to be signed and submitted separately.

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 purpose. Every sentence provides value, including the state indicator, conditions, permissionless note, and output format. It could be slightly more structured, but no filler is present.

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

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

Given two parameters (both fully described in schema), no output schema, and a destructive annotation, the description covers the purpose, usage conditions, output structure, and constraints (EVM-leg only). It equips an agent sufficiently to decide when to invoke this tool and understand the result.

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 schema describes both parameters (match and kind) with descriptions. The tool description adds crucial context: the match parameter must come from xchain_find_match/status, and kind options (timeout/nocert) are explained with their conditions. This adds significant meaning 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's purpose: building an unsigned EVM refund transaction to reclaim stake on the EVM leg of a cross-chain match. It specifies the action (build), resource (stake), and differentiates from siblings like xchain_build_create_match by focusing on refund scenarios.

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 conditions for use: after the claim window closes (kind='timeout') or for a funded match that never locked/cosigned a certificate (kind='nocert'). It also mentions that the match payload comes from specific sibling tools, guiding the user on prerequisites. While no explicit 'when not to use' is stated, the context implies it's only for refund, not normal claiming.

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 include destructiveHint: true, and the description adds context that the refund is permissionless, returns unsigned_tx/blockhash/match_id, and requires signing and broadcasting. It appropriately complements annotations without contradicting them.

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

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

The description is a single well-structured paragraph that efficiently conveys purpose, parameter usage, return value, and platform constraints. No extraneous content, though it could be slightly more compact.

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 cross-chain refund complexity and lack of output schema, the description covers key aspects: what it does, inputs, return type, and platform restriction. It could explicitly mention the default for 'kind' but is otherwise 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 the description adds meaning beyond the schema: it explains when to use each 'kind' value ('timeout' vs 'nocert') and clarifies that 'match' comes from specific tools. This aids correct parameter selection.

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 Solana refund transaction to reclaim stake on the Solana leg of a cross-chain match. It differentiates from sibling tools like xchain_build_refund (for EVM) and specifies the verb 'build' and resource 'unsigned Solana refund transaction'.

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: pass the match payload from xchain_find_match/status and kind='timeout' after claim window or kind='nocert' for never-locked matches. It also states 'Solana-leg only; EVM players use xchain_build_refund', giving a clear alternative when not to use this tool.

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

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

Discloses that the operator derives outcome from relayed transcript and never signs user-supplied outcome, which is beyond the readOnlyHint annotation. No contradiction; behavior is consistent with read-only query.

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 with clear front-loaded purpose, followed by preconditions, output fields, and post-actions. Slightly verbose but 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 zero-parameter tool with no output schema but with annotations, the description is exceptionally complete. It lists all returned fields, preconditions, and related follow-up actions, leaving no ambiguity.

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 description does not need to explain parameters. It adds context about when the tool is called (post-gameplay), which compensates for lack of params.

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

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

The description clearly states the tool retrieves the operator-cosigned outcome of a cross-chain match for settlement. It distinguishes from sibling tools by specifying preconditions and mentioning the contested claim path for equivocated matches.

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 both players' co-signed checkpoints are relayed) and when not to use (equivocated matches should use contested claim path). Provides clear context.

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

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

Annotations only provide destructiveHint: true, indicating the tool may have side effects. The description goes beyond by detailing the process: generating a local session key, server never seeing private key, operator co-signing match certificate. It discloses what happens during the call and the response format, adding significant value 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 well-structured, starting with the main action and then detailing process, prerequisites, return types, and defaults. Every sentence adds value. The use of '[STATE]' is unclear but does not detract from conciseness. It is appropriately sized for the tool's complexity.

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

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

Given no output schema, the description explains return types and payload details (both legs' contracts, stakes, deadlines, operator signature). It covers environment (testnet) and defaults. However, it does not discuss error conditions, timeouts, or what happens if the queue is full. Slightly incomplete for a complex matching tool.

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

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

Schema description coverage is 100% (both parameters documented). The description reinforces the session_key meaning: 'You first generate a per-match secp256k1 session key locally... pass its 0x address here.' It also repeats that tournament_id defaults to 1. Since the schema already provides clear descriptions, the description adds minimal new detail, warranting 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 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 a specific verb ('join', 'get matched') and resource ('queue', 'player on opposite chain'), distinguishing it from sibling tools like xchain_match_status (polling status) and xchain_build_create_match (likely building a 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 mentions prerequisites: 'Requires a registered wallet (register_wallet — Solana base58 or EVM 0x).' It also explains the return values: 'waiting' (poll xchain_match_status) or 'matched' with payload. It specifies default tournament_id and testnet environment. However, it does not explicitly exclude when not to use this tool or mention alternatives beyond xchain_match_status.

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

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

Annotations already mark readOnlyHint=true. Description adds poll behavior and return types. No contradiction. Lacks detail on rate limits but acceptable for a poll 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?

Two sentences, zero waste. Front-loaded with [READ] tag. Every sentence adds distinct 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?

Covers purpose, timing, prerequisites, return types. No output schema but description explains return values. Complete for a simple poll 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 – baseline 4. No additional info 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 tool polls for a cross-chain match and returns 'waiting' or 'matched' with payload. It distinguishes from sibling tool xchain_find_match by specifying call order.

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

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

Explicitly states when to call (after xchain_find_match returns 'waiting') and prerequisite (registered wallet). Could add guidance on polling frequency or timeout, but adequate.

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 significant behavioral context: what data is returned, that no wallet is required, and the testnet limitation. No contradiction with annotations.

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

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

Description is one paragraph but front-loaded with '[READ]' and clear structure. Every sentence adds value, though slightly verbose. Could be more concise but acceptable.

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, no output schema, and annotations with readOnlyHint, the description is very complete. It explains return data, usage order, and limitations (testnet only, mainnet gated). 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 exist, and schema coverage is 100%. The description adds value by explaining the return data and usage context beyond the empty schema. Per guidelines, 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 it's a READ operation to discover supported chains for cross-chain Coordination Game. It specifies the exact data returned (CAIP-2 id, native coin, stake, etc.) and distinguishes from sibling tools like register_wallet and game_* tools.

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

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

Explicitly says to call before register_wallet to decide which wallet to register. Provides context that it's read-only, no wallet required, and testnet-only with mainnet gated. Lacks explicit when-not-to-use statements but gives clear usage guidance.

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