TWZRD Agent Intelligence

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

Beyond the readOnly and idempotent annotations, the description discloses meaningful return behavior: it returns full score objects, ranks by wash-discounted effective_score, returns 'tie' on equality, and returns null if a side is unavailable. This gives the agent important edge-case knowledge without needing to invoke the tool.

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

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

The description is compact, well-structured, and front-loaded with the core purpose. The parenthetical use case and return semantics are concise yet informative, with no filler or redundant restating of the tool name.

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 two-parameter, read-only comparison tool, the description covers the purpose, usage context, return value shape, ranking logic, tie behavior, and unavailable-side behavior. Combined with complete schema descriptions and an output schema, nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

The input schema already provides 100% parameter coverage with clear descriptions for wallet_a and wallet_b, including accepted formats (Solana base58 or Base 0x). The tool description does not add new parameter-level meaning, but the schema fully carries that burden, 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 identifies a specific operation—comparing two wallets—and clearly states the resource ('two wallets') and the output ('both full score objects' and rank). It also implies the distinguishing use case ('choosing between two candidate providers'), which differentiates it from single-wallet or batch siblings like score_wallet_for_intel and score_wallets_batch.

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

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

The description gives clear context: use this tool when you need side-by-side intelligence for exactly two wallets, such as comparing candidate providers. It does not explicitly name alternative tools or state when not to use it, but the 'two wallets' framing and the example make the intended usage unambiguous.

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

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

Adds substantial behavioral context beyond the readOnlyHint/idempotentHint annotations: decision semantics, wash_flagged hard-stops, price_kind caveats, and the important warning that 'unknown' is not a trust verdict because a seller can spoof non-402 responses. No contradiction with annotations; the revenue path reads as guidance for the agent, not as the tool itself making payments.

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 definition is front-loaded with a good summary and uses clear sections. However, key caveats are repeated multiple times: wash_flagged appears three times, the leftover/price caveat appears in both the opening and hard-stops, and teaser_url pricing appears twice. This redundancy makes it less concise than ideal.

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 decision interpretation, dangerous edge cases, price semantics, hard-stops, and the revenue path for warn outcomes. Since an output schema exists, return-value explanation is not needed. The only undefined notions like 'agent policy' and 'the cap' are external policy concepts rather than missing tool-invocation detail.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description mostly repeats price_usdc and resource_url semantics already present in the schema, and adds nothing new about method or agent_intent. 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 states a specific behavior: fetches resource_url, extracts the seller wallet from the 402 accepts array, runs TWZRD preflight, and returns a spending decision. It is clear and resource-specific, though it does not explicitly differentiate itself from sibling tools like low_level_preflight or twzrd_demo_gate.

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 action guidance for each decision value: allow, warn, block, unknown. Hard-stops and revenue-path instructions are also given. However, it does not state when not to use this tool or name alternatives, so some sibling-routing is left to inference.

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, idempotentHint), the description adds behavioral traits: it's a capped teaser, returns top-N by event count, includes 'capped' and 'total_distinct_merchants' fields, and mentions 'fail-open'. This adds context about data completeness and potential partial success.

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

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

The description is well-structured with a clear lead sentence and subsequent details. It is somewhat verbose but contains no wasted sentences. It front-loads the main purpose.

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

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

Given the tool has 2 parameters and an output schema, the description is complete. It explains the return format (per-edge details, capped/total fields), notes the paid alternative, and mentions failure behavior ('fail-open'). 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying the 'wallet' parameter is a payer and the 'limit' is a cap (teaser). It also provides context about the default and maximum. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool lists top-N merchants a wallet pays, with per-edge details. It uses specific verbs ('discover', 'list') and resources ('merchants', 'wallet'). However, it does not explicitly differentiate from sibling tools like get_merchant_card or get_provider_reputation, though the context suggests it's a counterparty discovery 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?

The description provides usage guidance: it's a free capped teaser, useful before trusting a counterparty, and notes that the full graph is paid. It implicitly suggests when to use (free discovery) and when not (if full graph needed). It does not explicitly mention alternative tools, 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 indicate readOnlyHint and idempotentHint. The description adds beyond these by specifying fail-open behavior (returns data_available=false on DB gap) and the exact data returned (facilitator_ids list plus tx/merchant context), which are not covered 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?

The description is concise with four sentences covering purpose, interpretation, and behavioral details. It is front-loaded with the main purpose and avoids fluff, though could be slightly more compact.

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

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

Given the tool has only one parameter and an output schema (exists but not shown), the description provides sufficient context: purpose, interpretation hints, and fail-open behavior. It is complete for the tool's complexity.

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

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

Schema coverage is 100% and the schema already fully describes the wallet parameter (format, base58). The description does not add any additional parameter semantics, so baseline score of 3 applies.

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

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

The description clearly states it provides discovery of which x402 facilitators a payer has settled through and their count, with a specific verb (discovery) and resource (facilitator footprint). It distinguishes from sibling tools like get_x402_directory by focusing on a specific payer's settled facilitators.

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

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

The description gives interpretive guidance (e.g., unique_facilitators = 1 indicates a thin/captive agent) and contextual hints for when to use the tool (to assess cross-rail activity). However, it does not explicitly state when not to use it or name alternatives.

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

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

ReadOnly/idempotent hints are backed and heavily extended by the prose: the card is down-only and never returns allow, wash_flagged is tri-state with refusal behavior, and reason collapses edge cases into the three decision values. This gives the agent actionable knowledge about the output that annotations alone cannot.

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 dense and long, but front-loaded with the purpose and inputs; decision semantics and special-value caveats are grouped at the end. It could be trimmed, but nearly every sentence carries domain-specific operational information rather than 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 an output schema exists and the tool is a read-only card, the description is complete: input resolution, default vs full behavior, key output fields, decision routing, tri-state flag semantics, and caveats about price fields are all covered. There are no obvious gaps that would prevent 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?

The schema already documents all three parameters at 100% coverage, and the description adds clarifying behavior on top: dual wallet/resource_id resolution via PR-3, full vs compact output surfaces, and what full=true does with catalog services. It does not add much syntax-level detail, but the extra meaning is useful.

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 first line names the exact resource ('merchant card') and the exact data observed ('inbound payment-graph quality around a Solana receive wallet'), so an agent immediately knows what this tool computes. It also adds negative scope ('Does NOT claim service quality') and a decision surface, distinguishing it from service-quality or business-attestation siblings.

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 gives clear invocation context: pass wallet and/or resource_id, default is compact, full=true pulls catalog services, and consumers should route on next_action.decision. It does not name sibling tools or provide an explicit when-not-to-use statement, so it stops short of full alternative routing 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 is highly transparent about edge-case behavior, including returning an error for unobserved wallets, Base wallets being marked wash_flag 'unknown', floors staying closed, and scores being 0.0 in those cases. This goes well beyond the readOnlyHint and idempotentHint annotations without contradicting them.

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

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

The description is heavily repetitive, restating the same floor/failure semantics multiple times with nearly identical phrasing (e.g., 'floors fail closed, never open' and 'never inverted'). While the structure is logical, the redundancy makes it less concise than it should be.

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?

Even though an output schema exists and return values need not be explained, the description covers important contextual edge cases such as unobserved wallets, Base-specific limitations, and the error path. It is complete enough for an agent to understand when and how the tool behaves.

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

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

The input schema already fully describes the wallet parameter as a payer wallet with Solana base58 or Base 0x formats, so the description adds little new parameter-level meaning. Since schema coverage is 100%, 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 that the tool scores a payer wallet for Proof of Economic Contribution and explicitly references the same x402 snapshot returned by score_wallet_for_intel, helping distinguish it from that related tool. It also mentions the alternative path for self-reported settlements via submit_contribution_claims.

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

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

The description gives usable guidance by contrasting this tool with score_wallet_for_intel's snapshot and explicitly routing self-reported settlements to submit_contribution_claims. It could more explicitly state when to choose this tool over other siblings, but the main alternatives are addressed.

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 readOnly/idempotent annotations, the description discloses critical runtime behavior: wash_flagged is tri-state where null means 'never evaluated, not clean', fail-open behavior on DB gaps returns an 'unevaluated' verdict rather than a clean one, and wash_flagged=true blocks preflight/buyer refusal. This is exactly the kind of non-obvious behavior an agent needs.

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 dense but purposeful: purpose, output semantics, fallback behavior, sibling contrast, and paid alternatives are all packed in without fluff. A few parenthetical asides make it slightly run-on, but every sentence earns its place and the core purpose is front-loaded.

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

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

For a single-parameter, read-only, idempotent tool with an output schema, the description is complete. It covers call semantics, failure behavior, pricing, and the relationship to the paid API, leaving no material gap in what an agent needs to invoke or interpret this tool correctly.

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

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

The schema already documents the sole parameter 'merchant' with 100% coverage, so the description does not need to carry much weight. It adds the useful nuance that the merchant is the pay_to address scored on 'inbound corpus reputation', but no new format or constraints 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 opens with a specific verb and resource: 'free discovery: corpus-backed SELLER reputation for a merchant/provider wallet.' It names the exact questions answered and the computed signals (wash_label, reputation tier, wash_flagged), and explicitly differentiates from score_wallet_for_intel as the seller-side complement to the payer side.

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 clearly frames this as the free seller signal, states that it complements score_wallet_for_intel, and names the paid upgrade paths with prices. It does not explicitly state when NOT to use it relative to siblings like is_wash_fleet or low_level_preflight, so exclusion guidance is slightly incomplete.

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 idempotentHint annotations, the description explains that the result is advisory, that decision=block means do_not_pay, that wash_flagged=true never soft-allows, and that trust_score is 'a free heuristic, NOT the full corpus.' It also discloses the optional next_action enrollment handoff and states the aop_bind registry 'never mutates decision / can_spend.' This is substantial behavioral context consistent with 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 long but well-structured with headers, a front-loaded purpose, and compact bullet lists. Some redundancy exists—'wash_flagged=true never soft-allows' and 'free'/'advisory' appear more than once—so it is not maximally concise, but the density and organization justify its length.

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

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

For a complex advisory tool, the description covers when to call it, hard stops, decision semantics, return fields, next-step handoffs, pricing, and safety caveats. An output schema exists, so full return-value documentation is not required in the description. Nothing needed to invoke it correctly appears to be 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?

Schema coverage is 100%, so the schema already documents all eight parameters. The description adds extra semantic guidance beyond the schema by saying 'Pass seller_wallet OR resource_name,' warning against pasting path templates as seller_wallet, and clarifying that 'Unlabeled leftover 0.05 / leftover=0 is not a unit price.' It does not restate every param, but it strengthens the most error-prone ones.

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 'PRIMARY free pre-spend gate (advisory)' and immediately specifies the action context: 'before any x402 payment to a seller/resource.' It states the tool returns a readiness assessment rather than executing payment, and differentiates itself from verify_receipt by saying that sibling is 'for signed receipts only.' This is a specific verb+resource with sibling differentiation.

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

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

Usage is explicit: 'When to use: before any x402 payment to a seller/resource.' It also gives a clear exclusion: 'When not to use: after you already decided to refuse; use verify_receipt for signed receipts only.' The description even routes follow-up behavior to verify_receipt and twzrd_watch_add, so an agent knows exactly when this gate applies.

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 idempotentHint=true. The description adds significant behavioral context: short-timeout hit, reports reachability, and mentions response fields (prod_key_configured, data_first_available, actionable note), which goes well beyond the annotations.

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

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

The description is concise (5 sentences) and front-loaded with the key purpose. Every sentence adds value, though minor tightening could be possible.

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 an existing output schema, the description fully explains the tool's purpose, usage guidance, and behavioral details. It is complete for the agent to decide when and how to use it.

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

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

There are zero parameters, so baseline is 4. The description does not need to add parameter info; it correctly focuses on the tool's purpose and behavior.

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 health probe for the Solana Market API data backend, using specific verb+resource ('Health probe') and explicitly distinguishes it from sibling tools by advising to call it before other get_solana_market_* tools.

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

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

The description explicitly tells when to use this tool ('Call this to gate or degrade gracefully BEFORE the other get_solana_market_* tools') and provides context about being a free discovery tool, giving clear guidelines.

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

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

The description goes beyond annotations (readOnlyHint, idempotentHint) by explaining the ranking mechanism: 'Ranks by the wash-discounted effective_score (single-counterparty fleets are demoted, not hidden).' This reveals important behavioral context for interpreting results.

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

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

The description is concise (three sentences), front-loads the main purpose, and avoids extraneous 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 simplicity (3 optional parameters, output schema exists), the description covers purpose, ranking logic, parameter intent, and a disclaimer about the data's nature. It is complete for effective usage.

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

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

Schema coverage is 100%, so baseline is 3. The description's parameter guidance ('suppress one-shot wallets', 'suppress dormant ones') largely repeats the schema descriptions, adding minimal new value.

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

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

The description clearly states it returns a 'Leaderboard of observed payer wallets in the x402 settlement graph, each with its intel score.' This distinguishes it from sibling tools like score_wallet_for_intel (single wallet) and get_counterparties (different aspect).

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 guidance on parameter usage: 'Set min_paid_calls to suppress one-shot wallets and max_days_since_last to suppress dormant ones.' It also includes a disclaimer about the nature of the data. However, it does not explicitly state when to use this tool versus alternatives like score_wallet_for_intel.

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 idempotentHint=true, and the description adds behavioral context beyond that: it mentions the wash overlay is Solana-only (the only wash graph), while Base and Polygon listings carry wash_unknown and remain wash_unknown. It also states the query parameters mirror GET /v1/intel/x402-directory, which signals expected API alignment. It doesn't fully describe output shape or pagination, but output schema exists and the behavioral semantics of filtering/overlay are clearly disclosed.

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 reasonably concise and front-loaded with the core purpose, but it includes some potentially over-technical detail (e.g., EIP-3009 corpus membership, settlement reputation on pay_to) that may be useful but somewhat dense. It earns its place because it explains the tool's role and exclusions, but several sentences could be tightened for clarity without losing meaning.

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

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

Given the tool has an output schema and full schema descriptions for its 3 parameters, the description provides adequate operational context: it clarifies the data domain, the indexing key (payTo), the wash-flag semantics across chains, and explicitly routes the caller away from the wrong endpoints. It doesn't mention response shape or error cases, but the output schema covers return values, and the description's exclusions plus schema are 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 description coverage is 100%, so the schema already documents all three parameters (limit, source, flagged_only) with defaults and ranges. The description adds high-level context that query params mirror the HTTP endpoint but doesn't add deeper semantics beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool's function: it provides a wash overlay on ingested PayAI/CDP/Agentic listings indexed by payTo, and explicitly distinguishes this from the HTTP GET /v1/intel/resources resource join surface and from GET /v1/intel/bazaar/offers (TWZRD Bazaar catalog) and 402 extensions.bazaar. This differentiates it well from sibling tools and gives an agent a specific action and resource.

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

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

The description gives explicit guidance: 'Use this tool when you need the ingested listing overlay indexed by payTo', and explicitly states what not to use ('Not GET /v1/intel/bazaar/offers (TWZRD Bazaar catalog) and not 402 extensions.bazaar'). It names alternatives (GET /v1/intel/resources) and gives the reason those alternatives exist, so an agent knows when this tool is appropriate.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds critical behavioral details beyond these: fail-open DB gap returns 'unknown', and Base-specific limitation where ring_events=0 means NOT EVALUATED. This transparently discloses edge cases and platform differences, going well beyond annotation coverage.

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

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

Front-loaded with purpose and then organized behavioral details. Each sentence adds value, no redundancy. The structure flows logically from what it does, to platform caveats, to what is not returned, making it efficient and 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?

Output schema exists, so return format is covered. The description covers edge cases (DB gap, Base behavior), what is not returned, and usage context. It gives an agent all necessary information to decide when to call and what to expect, with no missing critical details.

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

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

Schema covers 100% of parameter details (wallet formats). The description reinforces this and adds platform-specific behavior for the parameter, e.g., 'On Base the signal reads the high-confidence x402 rollup only, and 3-cycle ring detection does not run.' This adds meaningful context beyond the schema's type description.

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

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

The description clearly identifies the tool as a 'cheap circular-flow (wash) check for a payer wallet' with specific outputs (classification, is_circular bool, counts). It distinguishes itself from paid alternatives by noting the free discovery aspect and that the wash discount is not returned, 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 states 'Use as a fast Sybil/wash gate before trusting a counterparty.' It also clarifies what is not returned (paid wash factor), implying when to seek a paid alternative. However, it does not explicitly name a sibling tool as the alternative, so guidance is strong but not exhaustive.

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

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

Even with readOnlyHint and idempotentHint already present, the description adds materially useful behavior: wash_flagged=true never soft-allows and yields decision=block with no warn/allow/quick, and an unlabeled leftover 0.05 or leftover=0 is not a unit price. It also discloses pricing hints for the paid endpoints. These are non-obvious behaviors an agent needs to interpret results correctly.

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

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

The description is front-loaded with the core purpose and contains a clear 'Hard-stops' section, but it repeats 'wash_flagged=true never soft-allows' and 'Unlabeled leftover 0.05 / leftover=0 is not a unit price' in both the opening and the hard-stop list. The redundancy makes it less concise than it could be, though the length is still manageable.

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 low-level tool with 7 optional parameters and an output schema, the description covers the essential context: when to prefer the sibling, which output fields justify this tool, and what edge-case behaviors to expect. It points to the outputSchema for the readiness_card shape rather than duplicating it, so nothing critical 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?

Schema description coverage is 100%, so the schema already carries the parameter meanings, including the price_usdc leftover caveat. The description reinforces that caveat but does not add new per-parameter semantics beyond what the input schema provides. The 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 opening sentence names a specific operation—'low-level preflight check'—and states it returns a 'richer result object' with named fields such as paid_quick_endpoint and paid_trust_endpoint. It also distinguishes itself from get_readiness_card_tool by positioning itself as the lower-level variant that returns richer detail. This is enough for an agent to know what the tool does and how it relates to its siblings.

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 'Prefer get_readiness_card_tool for most callers' and then states exactly when to choose this tool: when max_spend_recommendation_usdc, full_report_hint, or suggest_full_report are needed. It even explains that the embedded readiness_card has the same shape as get_readiness_card_tool, providing clear routing between alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds rich behavioral detail: it discloses the transparent heuristic, states the exact formula is returned as `score_model`, lists all output fields including wash_flag/wash_factor, and describes the clean failure path for malformed pubkeys. It also reveals the Base-specific wash_flag behavior explicitly. This goes well beyond the annotations and provides exceptional 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 moderately long but well-structured, moving from core purpose to heuristic, output, and data source details. Each sentence provides useful information with no fluff. The purpose is front-loaded, making it easy to scan, though the length is above average. It earns a 4 for density and structure without being overly verbose.

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

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

With one parameter and an output schema present, the description covers the essential aspects: input types, scoring model, output fields, failure behavior, and data source. It also mentions optional paid endpoints for deeper verification. Minor ambiguity remains in the relationship between intel_score and effective_score, but overall it is complete enough for an agent to invoke correctly.

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

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

The schema already describes the 'wallet' parameter as a Solana base58 pubkey or Base 0x address, and the description reinforces this while adding meaningful nuance: it explains how a Base wallet is scored differently due to the lack of a wash graph, and that malformed pubkeys are cleanly rejected. This adds value beyond the schema's simple type description.

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

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

The description explicitly states the tool scores a wallet from 0-100 based on observed x402 payment history, listing exact inputs (paid calls, counterparties, volume, recency). It clearly focuses on a single wallet, differentiating it from the sibling 'score_wallets_batch', and specifies accepted wallet types (Solana base58 and Base 0x). The verb 'score' plus resource and score range make the 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?

The description provides context about the data source and notes it is a free discovery tool, with optional paid endpoints for signed receipts. However, it does not explicitly state when to prefer this tool over siblings like 'score_wallets_batch' or 'compare_wallets', nor does it mention exclusions or prerequisites. The guidance is implied from the singular-wallet focus and free nature, but not made explicit.

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 establish read-only and idempotent behavior. The description adds valuable behavioral context by disclosing the 25-wallet cap, the fact that truncation is disclosed via requested/capped fields, and that this is a 'Free discovery' operation. These details go beyond the annotations without contradicting them.

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

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

The description is compact and front-loaded, immediately stating the key value ('score up to 25 wallets in a single call'). Every clause adds relevant information: the model reference, the triaging use case, and truncation disclosure behavior. No filler 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?

With one fully-documented parameter, rich annotations, and an output schema, the description covers the remaining context an agent needs: batch size, relationship to the single-wallet tool, and truncation disclosure. Nothing critical is missing for selecting and invoking this tool correctly.

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

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

There is only one parameter, and the schema covers it fully, including wallet formats and the hard cap. The description adds a reference to the same transparent model as score_wallet_for_intel, but this is not essential parameter semantics. Since schema coverage is 100%, 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 scores up to 25 wallets in a single call, using the same model as score_wallet_for_intel. It names the resource (wallets), the action (score), and the batch-specific scope, making it easy to distinguish from the single-wallet sibling.

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 phrase 'Convenience for triaging a set of candidate counterparties at once' provides clear context for when to use this tool. It does not explicitly state when not to use it or directly recommend the single-wallet alternative, but the reference to score_wallet_for_intel and the batch framing make the intended use reasonably clear.

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

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

The description discloses extensive behavioral traits beyond annotations: unmatched claims are returned with a reason, cap of 25 with dropped extras, dedup behavior with duplicate handling, preview status with claimable always false, and chain value rejection. This goes far beyond the readOnly and idempotent annotations, adding valuable context for the agent.

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

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

The description is long but well-structured, opening with the core purpose, then detailing cross-check strength, preview status, cap, and dedup. Every sentence adds necessary information for correct invocation, and it is front-loaded with the most critical purpose.

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

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

Given the complexity of the tool, including dedup, caps, preview mode, and output schema, the description covers key behaviors: unmatched claims returned, cap behavior, dedup handling, preview status, and chain validation. It also references output fields like `capped`/`claims_requested` and `unverified`, ensuring the agent understands the complete response behavior.

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

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

The input schema already provides full descriptions for both parameters, so baseline is 3. The description adds extra semantics for transfer_index dedup key and how duplicates are reported, which goes beyond the schema. It also clarifies that chain values other than solana/base are rejected. This additional context elevates the score 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?

The description clearly states the tool's purpose: reporting settlement claims from one's own rails for cross-check against TWZRD's independent corpus. It uses a specific verb ('report') and resource ('settlements'), and distinguishes from sibling tools by explicitly noting 'not TWZRD's paid routes' and that it is a preview. This is specific and not a tautology.

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 for when to use this tool: for a real counterparty with settlement volume to feed PoECX, and explicitly notes it is a preview, not an unlock. It also indicates alternatives indirectly by stating 'not TWZRD's paid routes' and references the PoECX plan. However, it does not name specific sibling alternatives, so it gets a 4 rather than 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds rich behavioral detail: no wallet/signer contact, no USDC spend, ledger candidate surface with real inbound IP, and the requirement for non-VPS source_ip and run_id matching to promote a candidate to an EXTERNAL_RUN. This goes far beyond the structured annotations without contradicting them.

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

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

The description is front-loaded with the core purpose and safety characteristics, then moves to caveats and proof requirements. It is somewhat dense and technical, but every sentence contributes needed context and there is no 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?

With an output schema present, the description still covers behavior, side-effect-like attribution implications, safety, and proof verification steps. It fully explains the candidate-vs-run distinction and references the returned not_external_run_proof, making it complete for a tool of this complexity.

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

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

The input schema already provides 100% parameter coverage for run_id and integration. The description reinforces the semantic role of run_id in transcript correlation and mentions the integration id in the attribution ledger context, adding value 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 opens with a specific verb+resource statement: 'Runnable, no-spend proof of the TWZRD buyer-side x402 trust gate.' It then concretely states what happens (block path ABORTS, allow path would proceed, ok=true), clearly distinguishing it from sibling tools that perform other x402/intel operations.

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

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

The description clearly conveys when to use this tool: as a no-install, no-human, no-spend proof/demo of the gate. It adds important context about the EXTERNAL_RUN candidate versus a real EXTERNAL_RUN, but it does not explicitly name alternative tools or provide when-not-to-use instructions.

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

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

The description discloses behaviors beyond annotations: proactive re-checking when 'recheck_after_unix' elapses, posting to webhook on material changes, and returning the watch row with a timestamp. No contradiction with annotations (openWorldHint, idempotentHint, destructiveHint are all false, consistent with registration).

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 short paragraphs, front-loaded with the core action. Every sentence provides useful context: registration, lifecycle, return value. No redundant or vague language.

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

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

For a tool with 3 parameters, an output schema, and annotations, the description covers the registration process, follow-up behavior, and return details. It does not explain what a 're-call watch' is in depth, but the context is sufficient for an agent to understand its 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?

All 3 parameters are described in the schema (100% coverage). The description adds value by explaining the purpose of 'webhook_url' (optional, POST on staleness) and clarifying the role of 'payer_wallet' and 'seller_wallet'. It also notes the return value includes 'recheck_after_unix', enhancing understanding.

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

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

The description clearly states the tool registers a re-call watch on a seller wallet, using a specific verb ('Register') and resource ('watch on seller wallet'). It distinguishes itself from sibling tools like 'twzrd_watch_list' and 'twzrd_watch_remove' by focusing on creation.

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 what the tool does and its lifecycle (proactive re-check, webhook notification), but does not explicitly state when to use it vs. alternatives or when not to use it. This is adequate but 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?

Annotations already declare readOnlyHint and idempotentHint, yet the description adds substantial non-obvious behavior: it names the fields returned, flags recheck_after_unix as an untrusted V5/V6 hint, and explicitly warns not to treat due / shouldRecheck as a trusted allow. That untrusted-data warning is exactly the kind of guidance structured fields cannot convey for an agent deciding how to act on the output.

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 short sentences with the core purpose front-loaded and no filler. The terminology is dense but each sentence contributes: purpose, return fields, and the trust warning. Slightly more idiomatic phrasing for the evaluateRecall reference would tighten it further.

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?

Output schema exists, so return-value documentation is technically optional; the description nonetheless summarizes the key fields and, more importantly, warns about their trust level. Safety profile and return shape are both covered, so an agent has what it needs, though nothing addresses volume, ordering, or empty-result behavior.

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

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

The single parameter payer_wallet has 100% schema description coverage ("Your agent wallet address"), so the schema carries the burden. The description does not add syntax, format, or defaulting detail beyond it, making the baseline 3 appropriate.

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

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

States a specific verb and resource ("List active re-call watches") with an explicit scope ("for your agent wallet"). This cleanly distinguishes it from the watch-mutating siblings twzrd_watch_add and twzrd_watch_remove, so an agent can select it without opening the schema.

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 the tool is a read of existing watches, but it never explicitly states when to call it versus twzrd_watch_add, twzrd_watch_remove, or the scoring tools like get_poec_score. It does name evaluateRecall / shouldRecheckTrusted as the downstream consumer gate, which is helpful context, but that is semantic guidance rather than a when-to-use routing rule.

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 non-destructive behavior. The description adds the owner-matching constraint, which is useful behavioral context. However, it does not elaborate on side effects 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?

The description is a single sentence that directly states the purpose and key constraint with no extraneous words.

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

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

For a simple removal tool with an output schema, the description covers the essential information. It could mention return behavior, but the output schema likely handles that.

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

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

Schema description coverage is 100%, so the description adds little beyond what the schema provides. It reiterates the payer_wallet constraint, but the schema already includes that information.

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

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

The description clearly states the action ('Deactivate a re-call watch by ID') and includes a specific constraint. It distinguishes from sibling tools like twzrd_watch_add and twzrd_watch_list.

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

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

The description tells when to use (to deactivate a watch) and includes a prerequisite (payer_wallet must match owner). It does not explicitly mention when not to use or alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral details: offline, no DB/network/payment, returns multiple validity flags and errors, and warns about trust anchoring. Contradictions none.

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 bold opening statement. Information is front-loaded and each section adds value. Slightly verbose but not excessive.

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 inputs, trust model, return values (valid/leaf_valid/signature_valid plus leaf and errors). Output schema exists, so return details are not needed. Complete for a verification tool.

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

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

All four parameters have descriptions in the schema (100% coverage). The description adds value by providing source context for receipt, cross-referencing Python library/CLI for max_age_seconds, and usage guidance for require_signature.

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's purpose: offline verification of v5/v6 trust receipts. It specifies the actions (recomputes Keccak256 leaf, verifies Ed25519 signature) and distinguishes from sibling tools by focusing on receipt verification.

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

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

Provides explicit usage guidance: pass the full PaidReceipt object, trust anchored on published key, and explains optional parameters like max_age_seconds and require_signature. No explicit when-not-to-use, but sufficient for correct invocation.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is clear. The description adds 'via recompute logic' implying computation, but doesn't contradict annotations. Provides minimal extra context.

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

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

Extremely concise at two sentences with no waste. Could benefit from slightly more detail, but front-loads the core 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 100% schema coverage, output schema present, and annotations, the description is minimally adequate. However, it lacks contextual completeness for a verification tool that might need explanation of what verification entails.

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

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

Schema has 100% description coverage. The description adds nothing about 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 states 'Independent root verification' which identifies the tool's action and resource, but lacks specificity about what 'root' refers to and does not differentiate from sibling tools like verify_receipt.

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 guidance on when to use this tool versus alternatives (e.g., verify_receipt). The description provides no context for selection.

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