Swarm Tips — Aggregated AI Agent Activities

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

The description adds significant behavioral detail beyond the `readOnlyHint` annotation: explains the read path (no cache), derived metrics, and null handling for missing PDAs. No contradictions with annotations.

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

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

Well-structured with a clear read tag, data sources list, derived metrics, edge cases, and parameter usage. Slightly verbose but every sentence is informative.

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

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

Given the complexity (two PDAs, derived metrics, optional parameters), the description is thorough. It explains return values adequately despite no output schema, covering null cases and metric formulas.

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 full description coverage, but the description enriches meaning by clarifying default behavior and querying options (omit wallet for own wallet, tournament_id defaults to 1). Adds value beyond the schema.

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

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

Starts with '[READ]' and explicitly states 'Trustless on-chain reputation lookup', making the purpose immediately clear. It distinguishes from sibling tools by emphasizing it reads directly from Solana, the source of truth.

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

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

Clearly explains that omitting `wallet` queries the caller's own wallet and that `tournament_id` defaults to 1. Provides guidance on handling missing PDAs (returns null). Could explicitly mention when not to use, but the context is sufficient.

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

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

Annotations only provide readOnlyHint=true. The description adds extensive behavioral context: partial-data tolerance, confidence metric, breakdown, on-chain reading, and future EigenTrust integration. No contradictions.

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

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

The description is front-loaded with the READ flag and core purpose. Every sentence adds value, though the EigenTrust note could be slightly trimmed. Efficient overall.

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

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

With 4 optional parameters, 100% schema coverage, and no output schema, the description fully explains inputs, behavior, and outputs (breakdown, confidence). It leaves no significant 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, but the description adds value by explaining optionality and defaults (e.g., wallet defaults to caller's wallet, tournament_id defaults to 1). It also contextualizes how agent_rank and curator_tier fold into the composite.

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 its purpose: 'Composite trust score (0..1) combining Shillbot reputation, Coordination Game win rate...' It distinguishes from sibling agent_profile by focusing specifically on trust score computation.

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

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

The description notes partial-data tolerance and optional parameters, guiding when to use. It also mentions EigenTrust as a separate future composition, providing context for alternatives. No explicit 'when not to use' but 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?

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?

The description starts with '[READ]' confirming read-only behavior, aligning with annotations (readOnlyHint=true). It adds context by explaining the returned vertical field and that it wraps two tools, providing transparency beyond annotations.

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

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

The description is three sentences, front-loaded with core purpose, and every sentence adds value. No redundant or wasted words.

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

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

Given the complexity of a unified search tool, the description covers purpose, usage, output hint (vertical field), and alternatives. Lacks details on error handling or edge cases but sufficient for typical use.

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

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

Schema coverage is 100% with descriptive parameter descriptions. The tool description does not add new semantic details beyond the schema for the parameters, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a unified search across earn and spend verticals, wrapping two underlying tools. It explicitly distinguishes from siblings by explaining its use case vs 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 states when to use: 'when you don't know whether you want to earn or spend yet, or when you want to keyword-search across both.' Also provides guidance on when not to use: 'For deep per-vertical control... use the per-vertical tools directly.'

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?

Discloses cost (0.05 SOL), locked ante, win/loss outcomes, negative-sum nature, and need for local signing. Adds detail beyond annotations (destructiveHint: true), no contradiction.

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

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

Concise and well-structured, front-loaded with cost and action, each sentence adds value without verbosity.

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

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

Covers end-to-end flow, prerequisites, parameter guidance, and game outcome. Adequate despite no output schema, as return value (unsigned transaction) is implied.

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 already describes tournament_id. The description repeats the schema info, adding no new semantics, meeting baseline for full coverage.

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

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

The description clearly states the tool builds an unsigned deposit_stake transaction to join matchmaking, with specific action and cost. It distinguishes from siblings like game_check_match and game_submit_tx.

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

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

Explicit prerequisites (register_wallet), step to sign locally and submit via game_submit_tx, and guidance on tournament_id (default to 1). Provides clear when-to-use 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 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?

Beyond the destructiveHint annotation, the description clarifies that the tool only broadcasts the transaction and does not determine funds movement, which adds valuable behavioral context. It could further mention potential failure modes or on-chain state changes, but the added transparency is effective.

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 long, front-loading the purpose and then adding clarifying context. Every sentence is informative with no redundant or unnecessary text, making it highly concise.

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

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

The description covers the core purpose and sequencing but omits details about return values (no output schema), error handling, or the requirement that the action must match the signed transaction. Given the tool's simplicity and schema coverage, it is adequate but not fully comprehensive.

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 description adds little beyond the input schema, which already fully describes both parameters (action and signed_transaction) with clear explanations. While it reiterates that the action corresponds to game steps, it does not provide new semantic information beyond what the schema offers.

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 the tool submits a signed Solana transaction for game steps, and distinguishes from the prior tool that builds the unsigned transaction. The description is specific about the verb (submit) and the resource (signed transaction), and lists the supported actions, making its purpose unambiguous.

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

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

Explicitly indicates that this tool should be used after a prior tool built the unsigned transaction, implying proper sequencing. However, it does not explicitly state when not to use it or name alternative tools, though the context is clear from the description.

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

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

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?

Description starts with [READ] confirming read-only behavior, consistent with readOnlyHint annotation. It adds behavioral details beyond annotations: explains the aggregation across sources, how claims work (first-party vs external), and the structure of output entries including the claim_via field. 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?

Description is well-structured, starting with a clear purpose, then details on sources and claiming mechanics. Every sentence adds value; no fluff. Length is appropriate for a complex tool.

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

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

Despite no output schema, the description fully enumerates the return fields (source, title, description, category, tags, reward, etc.) and explains the claiming process. Given the complexity and good annotations, it is complete for effective use.

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

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

Schema coverage is 100% with each parameter having a description. The description does not significantly add new parameter semantics beyond what is in the schema, though it reinforces the source filter by listing examples. 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?

Description clearly states it's an aggregated list of earning opportunities across the swarm.tips ecosystem, distinguishing it from per-source sibling tools like shillbot_list_available_tasks. It specifies the verb 'list' and resource 'earning opportunities', and explicitly names the sources included.

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

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

Description explicitly advises to 'prefer it over per-source listing tools when they exist', providing clear usage guidance. It also explains how to handle external bounties (claim off-platform) and first-party tasks (use claim_via field), giving both when and when-not usage context.

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

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

Annotations already declare readOnlyHint=true, description reinforces with '[READ]' and details the output fields, 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?

Concise, well-structured, front-loaded with purpose, includes scope, output details, and usage guidance without superfluous text.

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

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

Given no output schema, description compensates by listing output fields; simple tool with optional filters; complete for agent understanding.

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

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

All three parameters have descriptions in the schema (100% coverage), so description adds minimal extra meaning; baseline 3 is appropriate.

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

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

Description clearly states it provides an aggregated list of paid services for spend, distinguishes from sibling 'list_earning_opportunities', and specifies scope (v1 first-party services) with examples.

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 (to discover spending opportunities) and gives follow-up actions: for first-party use the named spend_via tool, for external navigate to URL.

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

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

With no annotations, description fully discloses behavioral traits: non-custodial, return value, session-id to wallet binding persisted to Firestore surviving pod restart. 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?

Five sentences, each adding value: purpose, input requirement, non-custodial note, return value, coverage, persistence. Well-structured but 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?

Complete for a registration tool with one parameter and no output schema. Explains necessity, return, and persistence. Addresses cross-product sharing and pod survival.

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 'pubkey' has a good description. Description adds minimal value beyond schema (repeats base58 format and non-custodial). 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?

Description clearly states the tool registers a Solana wallet for using swarm.tips tools that touch funds. It specifies the action, resource, and provides context of base58 public key. Distinguishes from sibling tools by being a setup/registration tool.

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 use before any fund-touching tool, and states one registration covers all products. Does not provide negative examples or alternatives, but context is clear.

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

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

Annotations declare readOnlyHint=true, and description is consistent. Adds behavioral details: directory size (30 entries), tier sorting (first-party → vetted → discovered), and that it powers the public discover page.

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 ~150 words, well-structured with clear purpose first, then details on tiers, filtering, sorting, and usage guidance. 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?

With 4 parameters, no output schema, and read-only annotation, description covers directory scope, tier definitions, filtering mechanisms, sorting, and sibling tool reference. Fully sufficient for correct agent invocation.

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

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

Input schema provides full descriptions for all 4 parameters (100% coverage). Description adds context: query as substring match, category as substring, tier returning zero for unknown values. Baseline 3, but extra context raises to 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?

Description starts with '[READ]', specifies exact resource (Layer 3 curated directory of MCP servers), and distinguishes from sibling 'discover_opportunities' by contrasting capability vs opportunity search. Verb 'Search' is clear and specific.

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 (find MCP server for a capability) and when not to (use 'discover_opportunities' for opportunities). Also explains filtering options and sorting order.

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 thoroughly explains the return of an unsigned base64 Solana transaction, the signing workflow, and the crucial timeout behavior (anchored on submitted_at, not approved_at) to prevent freeze attacks.

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 adding essential information. The description is front-loaded with purpose and state, with no wasted words.

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

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

Completely covers the tool's purpose, return value, workflow, constraints, and edge-case behavior (timeout). No output schema exists, but the description compensates fully.

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

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

The single parameter task_id is fully described in the schema (format: <campaign_id>:<task_uuid>). The description adds only that it's returned by list_available_tasks, which is helpful but not essential. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool approves agent-submitted content for a Shillbot task, specifying the verb (approve), resource (content), and context (Phase 3 blocker). It distinguishes from siblings like shillbot_reject_task.

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

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

Explicitly states that only the original task client may call this due to on-chain wallet enforcement. Points to shillbot_list_pending_approval as the prerequisite to find tasks awaiting approval.

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

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

The description starts with '[READ]' aligning with the readOnlyHint annotation. It adds behavioral context beyond the annotation by specifying the requirement for a registered wallet and listing the contents of the summary, which sets accurate expectations.

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 sentence with a prerequisite note. It is front-loaded with the purpose and avoids unnecessary text, making every sentence valuable.

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

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

Despite no output schema, the description fully explains the return value (earnings summary with specific items) and a prerequisite. The tool is simple with no parameters, and the description is 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?

With zero parameters, the baseline is 4. The description adds meaning by explaining what the tool returns, compensating for the lack of parameters.

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

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

The description clearly states the tool checks a Shillbot earnings summary, listing specific items (total earned, pending payments, claimed tasks, completed tasks). It distinguishes from siblings like shillbot_list_available_tasks by focusing on earnings rather than task lists.

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 a clear prerequisite: requires a registered wallet, and directs to register_wallet first. It does not explicitly state when not to use, but the context is clear for a simple read operation.

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

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

Annotations provide destructiveHint=true, and description adds 'non-custodial' and explains local signing flow, complementing annotations 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?

Concise 3-sentence description, front-loaded with main action, 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 full flow: claim returns unsigned tx, requires local signing, next step with submit_tx, prerequisite register_wallet. Complete for a non-trivial multi-step operation.

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

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

Input schema has 100% coverage with detailed description of task_id format. Description adds context about source (list_available_tasks), which exceeds schema info.

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

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

Description clearly states 'Claim a Shillbot task' with specific verb and resource. Distinct from siblings like shillbot_submit_tx which is for 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 says to sign locally then submit via shillbot_submit_tx with action='claim', and mentions prerequisite register_wallet. Provides clear when-to-use and next steps.

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 expands on annotations (readOnlyHint=true) by detailing that it reads on-chain and Firestore state, determines role, and returns a next_action block. It also discloses unavoidable waits and lifecycle steps, providing full behavioral context without contradiction.

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

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

The description is focused and each sentence adds value, but it is slightly verbose (4-5 sentences). It front-loads the key purpose well, though minor trimming could improve 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 no output schema, the description thoroughly explains the return (next_action, wait, done), lifecycle stages, roles, and re-calling. It covers all necessary context for an agent to use the tool effectively.

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

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

The input schema already provides full coverage (100%) with a clear description for task_id format and source. The description does not add additional parameter semantics beyond the schema, so baseline 3 applies.

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

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

The description clearly states it is a 'what do I do next?' wrapper that collapses the multi-step Shillbot task lifecycle into a single loop, reading state and returning the next action. It distinguishes itself from siblings by being an orchestration layer, not a specific task action.

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

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

The description explains when to use (pass a task_id, re-call after each step or wait) and mentions external waits. However, it does not explicitly contrast with alternatives like shillbot_approve_task or shillbot_submit_work, but the orchestration role is implied.

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

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

Annotations indicate destructiveHint=true, and the description confirms the tool transfers payments and closes the task account. It adds behavioral context like signing locally and submitting via another tool. No contradiction with annotations.

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

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

The description is three sentences, concise, and front-loaded with the core action. Every sentence adds value without unnecessary details.

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

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

Given the single parameter with full schema coverage and destructiveHint annotation, the description is mostly complete: it explains the payment flow, permissionless nature, and required follow-up action. Minor gaps exist (e.g., error handling for invalid task_id).

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

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

There is only one parameter (task_id) with 100% schema coverage, so the baseline is 3. The description does not add extra meaning beyond what the schema already provides (format and example).

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: finalizing a verified task, transferring payment from escrow, protocol fee, and closing the task account. It uses specific verbs and resources, distinguishing it from siblings like shillbot_claim_task or shillbot_submit_work.

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

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

The description explicitly says it is permissionless and should be called after the challenge deadline. It also instructs to sign the transaction locally and submit via shillbot_submit_tx. However, it does not compare to alternatives or explain when not to use it.

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

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

Annotations already declare readOnlyHint=true, but the description adds important behavioral details: returns 409 for unverified tasks, server does not sign, on-chain account is source of truth, and lists all return fields. These go beyond annotations and give full transparency.

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

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

The description is concise (single paragraph) and front-loaded with a read indicator. Every sentence provides value: action, conditions, return data, error behavior, use cases. No redundancy or fluff.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all necessary context: what it does, when it works, what it returns, error handling, and intended use. Combined with annotations and schema, it is fully informative.

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

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

Schema coverage is 100% with a single parameter task_id that has a clear description. The description does not add additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states it fetches a portable attestation for a Shillbot task that is Verified or Finalized. It distinguishes from siblings like shillbot_get_task_details by emphasizing the attestation's role in off-chain verification and the specific conditions for use.

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

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

The description specifies the precondition (task must be Verified or Finalized), provides explicit use cases (handing proof to third parties, feeding reputation systems), and documents the 409 error for non-Verified tasks. No explicit when-not-to-use or alternatives, but the context is clear.

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

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

Annotations set readOnlyHint=true, and the description reinforces this with '[READ]' and 'Get full details'. It adds value beyond annotations by listing returned fields and suggesting a prerequisite relationship with claim_task.

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

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

Two concise sentences: first states purpose and fields, second gives usage hint. No wasted words, 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?

For a simple read tool with one parameter and no output schema, the description covers what the tool does, what fields are returned, and when to use it. Sufficient for correct invocation.

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

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

Schema coverage is 100%, and the schema already describes task_id as 'The unique task identifier.' The description does not add further semantics but provides context that it's a Shillbot task. 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 starts with '[READ]' and specifies 'Get full details for a Shillbot task', listing specific fields (brief, blocklist, brand voice, etc.). It distinguishes from sibling tools like shillbot_claim_task by stating when to use it.

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

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

Clearly states 'Use this before calling shillbot_claim_task', providing explicit when-to-use guidance. No explicit when-not-to-use, but the tool is simple and context is clear.

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

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

Annotations already declare readOnlyHint=true; description adds value by detailing return fields (task IDs, briefs, payment amounts, platforms) and mentions on-chain escrow context. No contradiction but does not address rate limits or auth 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?

Two sentences, front-loaded with purpose and [READ] tag, 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?

Given no output schema, description adequately lists return fields and distinguishes from sibling. Lacks mention of ordering or default behavior beyond schema (e.g., limit default), but overall sufficient for agent decision-making.

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

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

Schema coverage is 100% with detailed parameter descriptions (limit, min_price). Description does not add information beyond what schema already provides; baseline of 3 applies.

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

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

Description clearly states 'List open Shillbot marketplace tasks' with a specific verb and resource, and differentiates from sibling tool 'list_earning_opportunities' by specifying Shillbot-specific details.

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

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

Explicitly tells when to use (browse content creation opportunities) and when not to use (use list_earning_opportunities for cross-source aggregated discovery), providing a direct alternative.

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

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

Annotations already declare readOnlyHint=true. Description adds that it is client-side and requires a registered wallet, providing useful behavioral context without contradiction.

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

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

Very concise: two sentences with a clear state definition, no unnecessary words, and front-loaded with '[READ]' and purpose.

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

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

Given zero parameters, no output schema, and annotations present, the description fully covers purpose, usage, state semantics, and authentication requirements.

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

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

No parameters exist in the input schema, so description need not add parameter info. Baseline 4 applies as schema coverage is 100%.

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 lists pending approval tasks from the client's perspective, specifying the 'submitted' state and differentiating from sibling tools like shillbot_list_available_tasks and shillbot_approve_task.

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

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

Explicitly says 'Use this to populate a review queue / inbox' and implies workflow with approve/reject tools. Lacks explicit when-not-to-use but 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 indicate readOnlyHint=true, and the description confirms it is a READ operation (CLIENT-SIDE). It discloses that this is a stub, explains the actual on-chain behavior (expire_task), and describes the return values (guidance and timestamp). 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 a single paragraph that front-loads the purpose and provides necessary context, but it is somewhat lengthy. Every sentence adds value, so it earns a 4.

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

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

Despite no output schema, the description explains what the tool returns (guidance and timestamp) and provides context about the stub status and future evolution. The tool is simple and the description is 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?

The input schema has full coverage for the single parameter with its description. The description repeats the schema's description but adds no new semantic information. 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 action ('Reject agent-submitted content') and the resource, and distinguishes from the sibling tool 'shillbot_approve_task' by noting it is the alternative path.

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

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

The description explicitly explains when to use this tool (client-side, v1 stub) and the alternative implicit reject path (not calling approve_task). It also mentions a future update with a first-class instruction.

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

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

The description aligns with the destructiveHint annotation, confirming a state-changing operation. It adds context: notifying the orchestrator and returning both signature and confirmation message.

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 are efficiently structured: first states the core action, second describes returns, third gives pairing guidance. 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?

Despite no output schema, the description specifies return values. All necessary context is provided: purpose, usage, returns, and related tools.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no additional parameter details beyond what the schema already provides.

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

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

The description clearly states the tool broadcasts a signed Shillbot Solana transaction to mainnet and notifies the orchestrator. It distinguishes from sibling tools by noting that related tools 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 advises pairing with claim_task, submit_work, verify_task, or finalize_task, which return the unsigned transaction. This guides when to use this tool vs. alternatives.

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

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

Beyond the destructiveHint annotation, the description reveals detailed behavioral traits: returns an unsigned base64 transaction, requires local signing, separate submission, and explains the verification and payment process. No contradictions with annotations.

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

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

The description is informative and front-loaded with purpose, but the single paragraph is somewhat dense. Could be slightly improved with shorter sentences for better readability, but still efficient.

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

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

Despite lacking an output schema, the description fully explains the return value (unsigned base64 transaction) and the overall workflow prerequisites and subsequent steps, making it complete for a tool involved in a multi-step process.

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 already cover both parameters (100% coverage). The description adds value by explaining the content_id examples (YouTube video ID, tweet ID) and clarifying the task_id format, making the semantics richer.

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 completed work for a claimed Shillbot task, with specific verb and resource. It distinguishes from siblings like shillbot_submit_tx and shillbot_claim_task by detailing the exact step in the workflow.

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

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

Provides explicit guidance on when to use (after claiming a task) and the follow-up step (sign and submit via shillbot_submit_tx). Mentions on-chain verification timeline, but could be stronger on when not to use vs. 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 set destructiveHint=true. The description adds behavioral context: the transaction is atomic, requires an oracle feed update, and incurs one fee. 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 a single, dense paragraph. It contains all necessary information but lacks structure (e.g., bullet points). Could be more scan-friendly.

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 (oracle feed, atomic verification, two-step process), the description covers prerequisites, process, and next steps. No output schema exists, but the return type (unsigned transaction) is implied.

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 with a single parameter task_id including a description pointing to list_available_tasks. The description reinforces this format slightly, adding marginal value beyond the schema.

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

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

The description clearly states the tool's purpose: building an unsigned verify_task transaction bundled with a Switchboard oracle feed update. It specifies the verb 'Build' and the resource 'verify_task transaction', with distinct prerequisites and follow-up actions.

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

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

Explicit when-to-use guidance: the verifier must have scored the task first and waited for the verification delay (5 min for game-play, 7 days for YouTube). Also points to the next step: sign locally and submit via shillbot_submit_tx with action='verify'.

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