Xcatcher — Recent X Posts

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses specific side effects: 'changes task state' and 'refunds cost_points' on success. This adds meaningful context about the mutation and its financial implication, though it does not detail failure states or state transitions.

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: two sentences that front-load the action and then provide essential side-effect information. Every word adds value, and there is no redundancy or unnecessary detail.

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 one-parameter mutation tool, the description covers the core purpose, scope (queued), side effects, and financial outcome. The presence of an output schema means return values need not be explained. It could optionally mention failure behavior for non-queued tasks, but the current information is sufficient for an agent to use it correctly.

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

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

The input schema provides full coverage of the single parameter (task_id) with its own description. The tool description only repeats this as 'by task_id', adding no additional meaning beyond the schema. Baseline 3 is appropriate since the schema carries the parameter semantics.

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 ('Cancel a queued task'), the resource ('task'), and the method ('by task_id'). It also adds side effects, which fully defines the tool's purpose and distinguishes it from sibling tools like get_task_status or create_crawl_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 limits usage to 'queued task', providing a clear context and exclusion of non-queued tasks. It also mentions the refund condition, which implies success only for queued tasks. However, it does not explicitly name alternatives or state when not to use it, though no other sibling tool offers cancellation.

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

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

The description goes well beyond the annotations (which only say non-readonly, open-world, non-idempotent, destructive) by disclosing side effects (creates a task and consumes points), HTTP 402 payment behavior with error.code and payload details, and retry safety via idempotency_key. It also includes performance caveats and operational details like polling intervals, which are crucial for safe invocation.

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

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

The description is longer than some but is well-structured into labeled sections (Modes, Performance note, Batching, Reliability), making it easy to scan. Each sentence contributes valuable operational information, with no gratuitous filler.

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

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

The description covers the full lifecycle: creation, payment failure handling, mode selection, performance expectations, batching limits, and follow-up steps (polling and downloading). With an output schema present and rich annotations, the description is sufficient for an agent to invoke the tool correctly and handle common failure modes.

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 already covers all three parameters with 100% description coverage, including the mode enum and user array constraints. The description adds behavioral meaning: idempotency_key is recommended to avoid duplicate charges, and users should be batched with a MAX_USERS_PER_TASK upper bound of 500, enriching the schema's static definitions.

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

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

The description opens with 'Create a crawl task for one or more X (Twitter) usernames' – a specific verb ('create') and resource ('crawl task') – which clearly distinguishes it from sibling status, listing, and cancellation tools. It immediately conveys the tool's core function and differentiates from 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?

The description provides strong contextual guidance: when to use normal vs. deep mode, batching guidance with a suggested upper bound of 500 users, and a reliability workflow that points to get_task_status and get_result_download_url. It does not explicitly state when not to use this tool, but the guidance is clear enough for an agent to select it appropriately.

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

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

The annotation already declares readOnlyHint=true and destructiveHint=false, so the description need not repeat 'Read-only' but adds useful context about the API key scoping. No additional behavioral traits (e.g., caching, rate limits) are disclosed, but the tool is inherently simple.

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 with no fluff. The main functionality is front-loaded, followed by a practical usage hint. Every word earns its place.

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

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

For a zero-parameter, read-only tool with an output schema, the description fully covers purpose, usage scenario, and auth scope. No critical information is missing.

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

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

The tool has zero parameters, and the input schema is empty, so there is no burden on the description to add parameter meaning. The description clarifies that the balance is associated with the current API key, which is helpful.

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 ('Return') and the resource ('the account attached to the current Bearer API key and its points balance'). It is specific and distinguishes this tool from siblings that deal with tasks and payments.

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 context by advising to use before creating a task to estimate whether an x402 top-up is needed. It does not mention alternatives or when not to use, but for a simple read-only balance check, 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?

Discloses that the tool does not move funds and that the returned payment_required_b64 should be passed unchanged to an x402-compatible wallet/client. Clarifies that the live amount, asset, network, destination, and quoteId are authoritative, adding valuable behavior 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?

Four sentences, each carrying essential information: purpose, usage constraints, pricing behavior, and return handling. No redundant phrases or filler.

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

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

Given the output schema exists, the description covers the full workflow: when to use, how to prepare inputs, what the response contains, and how to interpret it. The pricing distinction between normal and deep mode is also explained, making it self-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% and includes detailed descriptions for both parameters, so baseline is 3. The description adds extra semantic value by instructing to deduplicate the handle list and quote it together, which is not explicitly in 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 creates a request-bound x402 v2 payment requirement for an accountless crawl. It differentiates from sibling tools by explicitly naming the accountless x402 path and contrasting with create_crawl_task for API-key accounts.

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

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

Provides explicit when and when-not to use: 'Use this only for the accountless x402 path after preflight_crawl; API-key accounts use create_crawl_task instead.' It also gives operational guidance about progressive batch pricing and quoting the complete deduplicated handle list.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context by noting the task must be completed, that the token is a secret, and that it returns structured JSON rows. This goes beyond the annotations without contradicting them, warranting a score above baseline.

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

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

The description is two concise sentences, front-loaded with the primary purpose, followed by alternative usage and parameter guidance. Every sentence contributes value with no redundancy.

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

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

Given the 4-parameter schema, output schema, and annotations, the description covers the essential context: when to use, how to paginate, token secrecy, and the structured return format. It fully equips the agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds a small but meaningful security note about treating task_token as a secret and explicitly mentions using offset for pagination, enhancing parameter 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 states 'Return structured JSON rows for a completed accountless paid crawl' with a clear verb and resource. It explicitly distinguishes from get_result_preview for API-key accounts, making the tool's specific purpose evident.

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

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

The description provides explicit guidance: 'Use this instead of get_result_preview for an accountless x402 task; API-key accounts use get_result_preview.' It also gives pagination and secret-handling usage notes, leaving no ambiguity about when to invoke 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?

Beyond the readOnlyHint and destructiveHint annotations, the description adds behavioral details: polling interval, expected fields (task.has_result), and terminal states (failed/cancelled). 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?

Three concise sentences deliver the necessary context without fluff. Every sentence contributes to understanding purpose, usage, or expected behavior.

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

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

With an output schema available, the description correctly avoids repeating return details. It covers the core use case, alternative tool, and polling behavior, providing complete context 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 provides complete descriptions for both parameters (task_id and task_token). The description only restates them without adding meaningful extra semantics beyond what the schema already covers, 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?

Description clearly states the verb 'Read' and resource 'accountless paid crawl', and distinguishes it from get_task_status by naming the alternative. This makes the tool's purpose specific and unambiguous.

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

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

Explicitly instructs to use this tool instead of get_task_status for accountless x402 tasks and provides polling cadence (every 5-10 seconds) and termination conditions. This gives clear when-to-use and how-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?

Beyond the readOnlyHint annotation, the description discloses specific behavior: the RESULT_NOT_READY error with HTTP 409 for unfinished tasks, and the requirement to use the same Authorization Bearer token for downloading. These are valuable context not captured in annotations.

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

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

The description is two sentences, front-loaded with the main purpose, and each sentence provides distinct value (purpose, error behavior, auth requirement). 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?

The tool is simple with one parameter and an output schema present, so return values are covered by the schema. The description adds the necessary operational context (read-only, error condition, auth) making it complete for an agent to use correctly.

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

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

The schema already fully describes the only parameter (task_id) with a minimum and a clear 'Must be completed (has_result=true)' note. The description does not add additional meaning about the parameter, so with 100% schema coverage 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's function with a specific verb and resource: 'Get an absolute download URL for a task result'. It also notes the read-only nature, distinguishing it from sibling tools like get_result_preview or get_direct_result_preview which likely return content rather than a URL.

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 contextual guidance by noting the tool is read-only and specifying that it returns an error if the task is not finished. It does not explicitly name alternatives, but the existence of sibling preview/status tools and the explicit 'download URL' focus make the intended use apparent.

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?

While annotations already declare readOnlyHint=true, the description adds valuable behavioral context: it does not download or parse XLSX, returns up to 100 rows, and is safe to use after has_result=true. These specifics go beyond what annotations convey, though auth details and rate limits are not mentioned.

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 (3 sentences), front-loaded with the core purpose, and each sentence adds distinct value (function, alternative, caveat). No redundant or filler 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 the presence of an output schema, the description covers return values implicitly. It handles pagination, preconditions, alternatives, and thread-safety (read-only) comprehensively. This is a complete picture for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% with detailed parameter descriptions (limit, offset, task_id). The description reinforces 'up to 100 rows' and 'offset/next_offset' but doesn't add substantive new meaning beyond what the schema already provides, so a 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 action (Return), resource (result rows from an API-key account task), and output format (native structured JSON). It explicitly distinguishes from sibling tools such as get_direct_result_preview for accountless x402 tasks, making it 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?

Provides explicit usage context: when to use (after has_result=true), when to avoid (accountless x402 tasks, use get_direct_result_preview), and alternative for complete XLSX (get_result_download_url). Also mentions pagination via offset/next_offset. This is comprehensive 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 adds meaningful context beyond annotations by explicitly stating no live X data is fetched, no account is needed, no task/quote is created, and no funds move. This clarifies the idempotent and read-only nature beyond the readOnlyHint and idempotentHint 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 two sentences: the first states the core function, the second enumerates clarifying negatives. Every word earns its place; no redundancy.

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

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

For a zero-parameter tool with an output schema, the description is complete. It explains what the tool returns, its safety profile, and its non-live nature, which fully addresses the context needed to invoke it.

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

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

The tool has zero parameters and the input schema has 100% coverage (empty schema). Description does not need to explain parameters; baseline for 0 params is 4.

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

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

The description clearly states the tool returns a stable synthetic example of Xcatcher's paginated result and coverage metadata. This specific verb+resource combination distinguishes it from siblings that fetch live data or create tasks.

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

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

The description provides clear context that this tool is for inspecting a free sample without live data, no account, and no side effects. It implies when to use it for safe testing, but does not explicitly name alternatives or 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 set readOnlyHint=true and destructiveHint=false. The description adds value by disclosing 'No points are consumed' (cost implication) and 'live capabilities' (freshness/dynamic data). No contradiction with annotations; the extra behavioral context beyond the structured hints is useful.

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

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

Three sentences, each serving a distinct purpose: purpose, usage guidance, and cost note. No filler or redundancy. The description is front-loaded with the primary action and remains highly scannable.

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

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

For a simple read-only info tool with an output schema, the description fully covers purpose, when to use it, and cost behavior. It doesn't need to explain return format because the output schema exists. The guidance to call it first is a complete workflow hint.

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 zero parameters, so the baseline is 4. The description compensates for the empty schema by listing what the tool returns (capabilities, prices, limits, endpoints, workflow), giving semantic meaning to the output.

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 Xcatcher's live capabilities, prices, limits, endpoints, and recommended agent workflow' – a clear verb (Read) and specific resource list. It clearly differentiates from sibling tools (task/payment management) by focusing on service-level info.

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 advises 'Call this first when planning a crawl or when cached documentation may be stale,' providing both a condition and a recommended workflow. This tells the agent exactly when to invoke this tool relative to other actions.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces read-only and adds valuable behavioral context by stating the return includes safe structured state, result metadata, and authenticated result URLs, and that server filesystem paths are never exposed. This goes beyond the 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?

The description is compact and well-structured: the first sentence defines purpose and alternative, the second explains return content and security. Every sentence earns its place with 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?

An output schema exists, so detailed return structure isn't needed. The description provides the alternative tool, polling interval, and a security guarantee, making it sufficiently complete for a read-only status lookup with good annotations.

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

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

The schema fully describes task_id as 'Task ID returned by create_crawl_task', giving 100% schema description coverage. The description only references task_id without adding new semantic detail, so the baseline score of 3 applies.

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

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

The description clearly states it gets crawl task status by task_id for API-key accounts, distinguishing it from get_direct_task_status for accountless x402 tasks. The verb 'Get' and resource 'task status' are specific and unambiguous.

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

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

Explicitly names get_direct_task_status as the alternative when the tool should NOT be used ('accountless x402 tasks... instead'), and provides a recommended polling interval (5–10 seconds until has_result=true). This gives clear when-to-use and how-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 discloses that the tool 'does not move funds' and instructs to ask the user before payment, adding valuable safety context beyond annotations. It also mentions the quote is short-lived. No contradiction with readOnlyHint=false since creating a quote is a stateful but non-payment operation.

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, efficiently front-loaded with the purpose and return value, followed by a critical user-safety instruction. Every sentence earns its place with no redundancy.

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

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

With an output schema present, the description covers the core aspects: what the quote is, what it returns (amount and chains), and its non-payment nature. The sibling tool set clarifies the payment flow. Minor gap: no explicit mention of quote expiry duration, but that is a detail likely covered by the output schema.

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

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

The schema fully documents the single 'points' parameter with range and an authoritative note about the live quote. The description adds no new parameter semantics, so the baseline of 3 applies per the rubric.

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 identifies the tool's action: creating a short-lived USDC quote for Xcatcher points. It specifies the returned values (live amount and Base/Solana payment requirements) and distinctly positions itself as a quote-only tool, differentiating from sibling x402_topup which likely handles payment.

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

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

The description implies usage before any payment by stating 'Ask the user before signing or sending any payment.' This provides contextual guidance, though it does not explicitly name alternatives or when not to use the tool. The sibling x402_topup is clearly the payment counterpart, making the intended flow 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description reinforces this by stating 'Read-only and does not consume points,' adding cost transparency. It also discloses the ownership scope ('owned by the current Bearer API key') and ordering ('newest first'), which are not in the annotations.

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

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

The description is exceptionally concise: two sentences that front-load the core purpose, then provide pagination and cost/safety details. Every clause adds value, with no filler or redundant information.

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

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

Given the tool's relative simplicity (list with pagination) and the presence of an output schema and annotations, the description covers all essential aspects: purpose, ownership, ordering, pagination, and read-only/cost behavior. It is complete for an agent to invoke the tool correctly without needing additional context.

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

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

The input schema has 100% coverage with descriptions for both 'limit' and 'before_id'. The description only adds the phrase 'Use next_before_id for cursor pagination,' which essentially restates the schema's 'before_id' description. Thus it does not significantly enhance parameter meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists recent tasks owned by the current Bearer API key, with a specific verb ('List') and resource ('recent tasks'). It also specifies ordering ('newest first') and distinguishes itself from sibling tools that handle individual tasks (e.g., get_task_status) or creation/cancellation.

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

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

Provides clear context of use: listing recent tasks for the authenticated API key. Includes pagination guidance ('Use next_before_id for cursor pagination'), implying when to use this tool. However, it does not explicitly mention when not to use it or alternatives for specific task status lookups, so it lacks explicit exclusions.

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

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

Beyond annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds concrete side-effect guarantees: 'requires no account', 'creates no quote or task', and 'moves no funds'. It also describes the normalization/deduplication behavior, which is not present in annotations.

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

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

Two sentences, each dense with information. The first lists core actions, the second clarifies safety and usage. No redundant or filler content.

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 an output schema exists, return values are already specified. The description covers the tool's purpose, when to use it, and its side-effect profile. For a 2-parameter tool with fully described schemas, this 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 already covers both parameters with detailed descriptions (mode pricing, users formats), and schema coverage is 100%. The description's mention of 'validate the mode' and 'preview cost' aligns with the schema but adds no new semantic detail beyond the parameter 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 uses specific verbs ('Normalize and deduplicate', 'validate', 'preview') and names the resource ('X handles' and 'modeled points/USDC cost'). It clearly distinguishes this tool from siblings like get_x402_quote or create_crawl_task by framing it as a preflight check that creates no quote or 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 'Use it before requesting a live x402 payment challenge', giving clear temporal guidance. Also notes 'requires no account' and 'creates no quote or task', implying when to use this instead of tools that require accounts or create tasks. However, it does not explicitly name alternative tools or 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?

The description discloses financial settlement ('may settle USDC'), the need for spending approval, and the resulting task_token with seven-day access. This goes beyond annotations by adding risk and post-success behavior, though it does not mention idempotent retry semantics already captured by 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, action-first, and includes essential warnings without any waste. 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?

Covers prerequisites, side effects, and post-action token handling. Lacks explicit error/retry guidance, but the output schema and annotations help fill some gaps, making it sufficiently complete for a payment 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 value by emphasizing that users/mode must exactly match get_direct_crawl_payment, reinforcing the contract, and provides protocol context for payment_signature_b64.

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 an action: submitting an x402 v2 PAYMENT-SIGNATURE that may settle USDC and create a crawl task. It distinguishes from siblings by tying to get_direct_crawl_payment and the accountless crawl concept.

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

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

It provides an explicit precondition: 'Call only after explicit spending approval.' It also references get_direct_crawl_payment for the exact users/mode, signaling when to use. However, it does not explicitly exclude alternative tools like create_crawl_task.

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 meaningful behavioral context beyond the annotations: it explains that polling is 'server-side', that it continues until a terminal state or timeout, and that it is read-only. The read-only claim aligns with the readOnlyHint annotation, and no contradictions exist. While it could detail what happens on timeout or cancellation (e.g., returned response), the output schema likely covers that, so this is sufficient.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and then adds the key differentiator ('read-only and cheaper'). Every clause earns its place, with no wasted words. It is concise yet 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 tool's moderate complexity, the presence of an output schema, and thorough annotations, the description is complete enough. It covers the core behavior (server-side polling until result, terminal state, or timeout), the read-only nature, and the cost benefit. It does not need to explain return values since an output schema is present. The description provides all necessary context for correct selection and invocation.

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

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

Schema description coverage is 100%, and each parameter has a detailed description in the schema (task_id with source, timeout_seconds and poll_interval_seconds with ranges and defaults). The tool description itself does not add parameter semantics beyond what the schema provides. Per the rubric, baseline is 3 when schema coverage is high, and the description adds no additional value for 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 uses a specific verb ('Poll') and clearly states the resource ('a crawl task server-side') and the termination conditions ('has a result, reaches a terminal failure/cancelled state, or the bounded timeout expires'). This distinguishes it from sibling tools like get_task_status, which likely performs a single status check rather than a server-side blocking wait.

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 when to use the tool: when you need to wait for task completion and want to avoid repeated manual polling, noting it is 'cheaper for agent context'. It does not explicitly name alternatives or exclusions, but the contrast with 'repeated manual polling' implies the alternative of using get_task_status in a loop. This provides clear usage context without being overly verbose.

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 states 'Side effects: credits points to the same Bearer key (no key rotation).' This is a purely additive operation. However, the annotations include destructiveHint: true, which directly contradicts the description's claim. This is a serious inconsistency that undermines 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 and well-structured, with a clear opening statement, an inputs list, a side-effects note, and a success return note. Every sentence adds value and there is no unnecessary verbosity.

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

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

The description covers the inputs, side effects, and success response, and mentions that the return shape depends on upstream. It provides sufficient context for an agent to understand when and how to invoke the tool. However, the contradictory destructiveHint flag in the annotations leaves a completeness gap, preventing a perfect score.

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 100% coverage for both parameters, each with a description. The tool description simply restates the same information (quote_id from PAYMENT-REQUIRED, payment_signature_b64 as base64 JSON) without adding new semantics. With full schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Top up points for the CURRENT Bearer key using x402 proof.' It uses a specific verb ('top up'), identifies the resource ('points for the current Bearer key'), and mentions the method ('x402 proof'). This distinguishes it from sibling tools like get_x402_quote and get_account_balance.

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 context: it says the quote_id is returned by PAYMENT-REQUIRED or /api/v1/x402/quote, implying the tool is used after obtaining a quote. It does not explicitly mention alternatives or exclusions, but the usage context is clear. A score of 4 reflects the absence of explicit 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.