TWZRD Agent Intelligence

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

Annotations already declare readOnlyHint and idempotentHint, yet the description adds substantive behavior: it never authorizes a payment (authorizes_spend is always false) and spells out exactly when needs_approval is true, including edge cases like an advertised card with no price or a below-advertised declared price. These are decision rules an agent cannot derive from readOnlyHint alone.

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 the purpose and safety posture in the first sentence, then result semantics. The needs_approval sentence is long and nested ('advertises nothing, advertises no price, cannot check the declared price...'), which taxes readability, but nearly every clause carries decision-relevant 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?

Covers purpose, safety guarantees, and result/approval logic thoroughly for a 6-parameter check tool, and an output schema exists so return-value structure need not be restated. The remaining gap is routing among numerous plausibly overlapping siblings, which the description does not address.

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 market/product/variant/merchant matching rules, product_url normalization, and declared_unit_price parsing. The description does not add parameter-level syntax or constraints beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Pre-spend check of one product against the published listing cards,' plus scope qualifiers 'Free, read-only.' The purpose is unambiguous, but it never names or contrasts a sibling (e.g. get_shopping_check, get_merchant_card, get_publication), so an agent must infer the division of labor itself.

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?

Gives clear context of use ('the store product URL the agent is about to buy from') and explicit boundaries ('does not fetch the store page, open a checkout or move money'). It stops short of naming alternative tools for adjacent jobs, so there is no explicit when-to-use-something-else 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 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?

Discloses the key side effect (a live 402 observation is upserted into the service catalog, explicitly 'not read-only'), which is exactly the kind of context annotations cannot convey. It also spells out hard-stops (wash_flagged, price_kind=exact) and warns that 'unknown' is not a trust verdict, adding genuine behavioral depth.

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-loads purpose well and uses a scannable decision table, but several lines are verbatim repeats ('wash_flagged=true never soft-allows' and the 'Unlabeled leftover 0.05 / leftover=0' caveat each appear twice). The redundancy costs space without adding 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?

An output schema exists, so return values need not be described, and the prose still covers the side effect, decision semantics, hard-stops, and the follow-up revenue path. Nothing an agent needs to invoke and interpret this tool correctly 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 the baseline is 3; the description nonetheless adds real meaning by explaining that price_usdc overrides a 402 exact quote and that unlabeled leftover 0.05 / leftover=0 is not a unit price. Method and agent_intent get no extra color in the prose, keeping it short of a 5.

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+resource ('One-shot x402 guard') and then unpacks the exact pipeline: fetch resource_url, extract seller wallet from the 402 accepts array, run TWZRD preflight, return a spending decision. This is far more specific than any sibling and lets an agent place it precisely among low_level_preflight and the verify_* 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?

It gives strong context on how to act on each decision value (allow/warn/block/unknown) and the revenue path for 'warn'. It does not explicitly contrast itself against siblings like low_level_preflight or verify_x402_settled_claim, so the when-not-to-use-this angle 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 the annotations (readOnlyHint, idempotentHint), the description discloses detailed verification behavior: publication signature, artifact digest, schema, evidence binding, and that a failing read is refused. It also notes that unknown claims stay unknown and that claims carry an expiry. This exceeds the annotation coverage significantly.

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 with the core purpose, then adds verification, state behavior, and safety. Each sentence contributes new information; there is no filler or repetition. It is slightly long but appropriate for the complexity of the resource.

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 tool with an output schema, the description fully covers what the tool does, its safety profile, edge cases (unknown, expired), and verification guarantees. Nothing an agent needs to decide whether to call it 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, so the description need not explain any. The schema is trivially covered at 100%. Per calibration, a baseline of 4 applies, and the description adds no parameter-related confusion.

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 specific artifact (Vuori Kore Short listing-claim), states the resource it twins, and enumerates the information it provides (what is claimed, by whom, state, evidence). It also distinguishes its read-only nature from any payment/checkout actions, making its purpose unambiguous among sibling tools.

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

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

It explicitly states the tool is read-only and never starts a payment or checkout, which is a clear usage constraint. It also explains that unknown claims remain unknown and that after expires_at the claim is historical, providing context on when to rely on the result. However, it does not name alternative tools for comparison, so it lacks explicit exclusion 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 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 already mark the tool read-only and idempotent, so the description's job is to add behavioral depth, and it does. It discloses that the evidence digest is an RFC 8785 SHA-256 of the envelope, that every read is verified against the artifact, that mismatches cause refusal, and that raw page bytes are not returned. These are non-obvious behaviors an agent would not know from annotations alone.

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 each subsequent sentence adds a distinct, useful fact: resource twin, digest format, verification behavior, and a content limitation. It is somewhat dense with jargon like 'RFC 8785 SHA-256' and 'canonical_evidence/1', but no sentence is wasted.

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 tool with a rich annotation set and an output schema, the description is remarkably complete. It explains what the tool accesses, how integrity is checked, what happens on mismatch, and what is excluded. An agent has enough information to invoke it correctly and interpret its behavior without further investigation.

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

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

With zero parameters and 100% schema coverage, the baseline is 4. The description adds meaning by identifying the exact resource being read (canonical_evidence/1 envelopes and capture records) even though no input parameters are needed, which helps the agent understand what the fixed invocation actually returns.

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: 'Read the evidence bundle behind the Vuori Kore Short listing claims.' It further distinguishes itself by naming the exact backing resource URI and framing itself as the 'Tool twin' of that evidence resource, which separates it from sibling tools like get_claim that serve the claim itself rather than the evidence bundle.

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 intended use is implied: call this tool when you need the evidence bundle behind the claim, and it does state a limitation ('Raw page bytes are not served'). However, it never explicitly names an alternative or states when not to use it, so the guidance relies on inference rather than a clear 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 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?

Annotations only cover readOnly/idempotent, so the description carries the load and delivers real behavioral contract: tri-state wash_flagged semantics (null is NOT clean), that wash_flagged=true can never soft-allow, that the card is down-only and never returns 'allow', and that `reason` disambiguates a collapsed 3-value decision. This is exactly the kind of non-obvious behavior an agent needs before trusting 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?

Purpose is front-loaded in the first line and the rest is dense, high-value contract detail rather than filler. The density and unexplained internal tokens ('PR-3', 'corpus_complete_day', 'upto_cap') cost it some readability, but no sentence is redundant.

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, return values needn't be explained, yet the description still pre-empts the key output semantics (decision routing, stale/corpus fields). It does omit what happens when both optional inputs are omitted (0 required parameters) and gives no rate-limit/free-tier caveat beyond the word 'Free'.

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 baseline is 3, and the description adds meaning: it establishes that wallet and resource_id are interchangeable paths to the same card ('resolves ... to a pay_to, then the same graph card'), and clarifies that catalog services are gated behind full=true while the compact surface is the default decision view.

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?

'Free merchant card: observed inbound payment-graph quality around a Solana or Base receive wallet' states the resource and the scope precisely. It also carves out what it is not ('Does NOT claim service quality'), which separates it from catalog/listing tools. However, the heavy jargon ('PR-3', 'TWZRD seed', 'payment-graph quality') leaves the core purpose legible only to an agent already steeped in this domain.

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 does specify input combinations ('pass wallet and/or resource_id') and how to consume the result ('Route on next_action.decision'), which implies usage. But it never states when to pick this tool over close siblings such as score_wallet_for_intel, compare_wallets, or check_listing, and the 'HTTP twin' line gives no actionable routing advice.

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?

Goes well beyond the readOnlyHint/idempotentHint annotations by disclosing the fail-open contract (DB gap returns 'unknown' + wash_flagged=null, never clean), the tri-state meaning of wash_flagged, and the downstream consequence that wash_flagged=true triggers a buyer refuse / preflight block. This is exactly the operational semantics an agent needs and cannot get from 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?

Front-loads the core question and keeps to a tight set of sentences, but the signal list is a dense run-on and 'captive-payer % (onboarding-sink proxy)' and 'top_payer_tx_pct (captive concentration)' restate the same captive-payer concept. Minor redundancy, otherwise every sentence carries weight.

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, the description correctly focuses on interpretation rather than return format, and it covers the failure mode, the tri-state null semantics, and the pricing/escalation ladder. Nothing an agent needs to invoke and interpret this tool correctly 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% and the single parameter is already fully documented (base58 Solana or 0x Base address). The description reinforces that this is the seller/merchant side of the graph but adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('corpus-backed SELLER reputation for a merchant/provider wallet') and frames the question it answers ('is this provider organic, narrow, or a wash fleet?'). It explicitly differentiates from the sibling score_wallet_for_intel by naming the seller-side vs payer-side split, so an agent can pick between them without opening schemas.

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 positions itself as the 'free discovery' / 'free seller signal' entry point and names the paid escalation hops with prices (GET /v1/intel/quick/{wallet} at 0.001 USDC, GET /v1/intel/trust/{wallet} at 0.05 USDC). The when-to-use context (seller side, complementing the payer-side tool) is spelled out rather than inferred.

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 disclosure of the return shape (Ed25519 record, verify key, sha256 fingerprint) and, unusually, the trust model: the check only proves record/bytes agreement unless the fingerprint is pinned from a second source, and the signature is explicitly not a merchant attestation. Auth/error behavior is unstated, keeping it below a 5.

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 the purpose, and each sentence carries verification or trust-model information rather than filler. The verification instructions are dense and slightly meandering, but nothing is truly wasted.

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, return values need not be explained, yet the description still frames what comes back and how to use it. For a zero-param read tool, nothing an agent needs in order to call it correctly 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 takes zero parameters, so per the baseline a 4 applies. The description does name fields from sibling tools (artifact_digest, evidence_digest) that contextualize the comparison, but there is nothing parameter-level for this tool to document.

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: reads the signed publication record behind the current Vuori Kore Short claims. Names its relationship to the twzrd://claims/vuori-kore/publication resource and to the get_claim/get_evidence siblings, so an agent can place it precisely among the claim-verification 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?

Explains what to do with the output (verify the signature, then compare sha256 of get_claim/get_evidence text against artifact_digest/evidence_digest), which implicitly positions it as the anchoring step before those comparisons. It stops short of an explicit when-to-use vs when-not statement, but the workflow context is clear.

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

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

Annotations only cover readOnly/idempotent, yet the description discloses the full behavioral surface: hard-stop rules (wash_flagged, unlabeled leftover), the three decision branches and their spend caps, a no-counterparty input-bug path that is explicitly distinguished from a seller verdict, and the caveat that trust_score is 'a free heuristic, NOT the full corpus.' That is far beyond what the annotations provide and it is internally consistent with readOnly/advisory.

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?

It is well front-loaded (purpose, then when/when-not, then hard-stops and decision semantics), but it is also dense and redundant: 'wash_flagged=true never soft-allows' appears twice and the 'unlabeled leftover 0.05 is not a unit price' rule appears three times across the description. The repetition is defensible for a safety gate, but it costs efficiency.

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 return values need not be enumerated, yet the description still documents decision/recommended_action mappings, reason_codes, the null_reason=no_subject path, and the next_action enrollment handoff. For an 8-parameter, optional-arg gate with no required fields, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter interaction guidance the schema cannot express: the OR-requirement between seller_wallet and resource_name, the rule that path templates must never be pasted as a wallet, and the price_kind distinction for price_usdc. Marginal overlap with schema text exists, but the selection logic is genuinely added.

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 states a specific verb+resource and a scope: 'PRIMARY free pre-spend gate (advisory). Pass seller_wallet OR resource_name.' It also names a sibling boundary ('use verify_receipt for signed receipts only'), but does not distinguish itself from other near-neighbors in the cluster (evaluate_x402_resource, low_level_preflight, get_merchant_card), so it falls just short of a 5.

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

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

Explicit 'When to use: before any x402 payment to a seller/resource' paired with 'When not to use: after you already decided to refuse; use verify_receipt for signed receipts only.' The condition that selects the alternative is named outright, leaving no inference required.

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 cover readOnlyHint and idempotentHint, so the bar is lower, yet the description adds real behavioral context: each read is 'Built from the verified signed publication' (provenance/freshness), 'Expired observations are historical' (how stale data is presented), and it performs no payment. That is useful disclosure beyond the structured hints.

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 the verb and target, then the report contents, then provenance and the no-payment guarantee. Mostly efficient; the inline URL repeats what the slash path already conveys and adds a little length without adding 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?

No parameters and an output schema exists, so return structure needn't be described, and the description still enumerates the report sections. The one gap is that it never routes the agent among the many sibling read tools when this check is or isn't the right one.

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?

Zero parameters, so there is no per-parameter semantics to explain; the baseline for a parameterless tool is 4. The description compensates by making clear the report is fixed to one specific product rather than being configurable.

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?

Specific verb ('Read') plus a concrete resource ('Agent Shopping Check for Vuori Kore Short, Ink, US'), with the report's contents enumerated (product context, advertised claims with sources, gaps, editorial fixes). An agent can tell this delivers a curated shopping-gap report rather than raw listings. It does not, however, name a sibling it should be preferred over.

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 implied rather than stated: 'free', 'Read', and 'Never pays or starts checkout' tell the agent this is a safe pre-purchase lookup that can substitute for initiating a checkout. No explicit when-to-use trigger and no alternative sibling (check_listing, get_publication, get_evidence) is offered for cases where this check doesn't apply.

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 is consistent with those. It adds meaningful behavioral context beyond the annotations: the PayAI surface is not_indexed, 'Solana wash overlay is the only wash graph,' Base listings only carry EIP-3009 corpus membership yet 'remain wash_unknown,' and Polygon listings 'carry wash_unknown.' This flags data-coverage limitations an agent must know before trusting wash-flag 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 dense but front-loaded: purpose first, then alternative routing, then data caveats, then params. Every sentence earns its place. The only knock is heavy domain jargon (wash overlay, SOT, not_indexed, EIP-3009 corpus, wash_unknown), which trades readability for compactness.

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 output schema (return shape covered), annotations (safety profile covered), and 100% param coverage, the description fills the remaining gaps well: when to use it, what it is not, and chain-specific wash-coverage caveats. The main residual gap is that 'mirror GET /v1/intel/x402-directory' assumes external knowledge of an HTTP surface the agent may not have, though the output schema mitigates this.

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 three parameters (limit range 1-500, source filter values, flagged_only semantics). The description only adds a cross-reference that the params 'mirror GET /v1/intel/x402-directory,' which is marginal. Per the rubric, baseline 3 is correct since the schema carries the load.

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 resource and scope: a wash overlay on ingested PayAI/CDP/Agentic listings, retrieved 'when you need the ingested listing overlay indexed by payTo.' It explicitly distinguishes itself from GET /v1/intel/resources (resource join SOT), GET /v1/intel/bazaar/offers (TWZRD Bazaar catalog), and 402 extensions.bazaar, so an agent can route correctly without opening schemas.

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 guidance is explicit and contrastive: 'Prefer HTTP GET /v1/intel/resources for the resource join SOT' (with the reason: callable URL + discovery claim + settlement reputation), then 'Use this tool when you need the ingested listing overlay indexed by payTo,' and 'Not GET /v1/intel/bazaar/offers... and not 402 extensions.bazaar.' When-to-use, when-not-to-use, and the preferred alternative are all named.

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

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

Annotations only cover safety (readOnlyHint, idempotentHint); the description goes well beyond them, disclosing fail-open semantics ('a DB gap returns classification "unknown"'), the Base-vs-Solana implementation difference, and the critical ring_evaluated=false pitfall where ring_events=0 means NOT EVALUATED. It also bounds what is returned, noting wash_factor/wash_ratio are withheld.

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?

Purpose is front-loaded in the first line and the remaining sentences are dense with unique operational facts rather than filler. Slightly fragmented across six short paragraphs, but no sentence is wasted.

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

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

Despite an output schema existing, the description supplies the interpretive context the schema cannot: the meaning of the four classifications, the fail-open 'unknown' case, and the ring_evaluated caveat. For a single-param gate tool with annotations covering safety, nothing needed for correct invocation 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% and the schema already documents the wallet string as a Solana pubkey or Base/EVM address. The description's 'Accepts a Solana public key or a Base/EVM address' repeats that without adding format or precedence detail, so baseline 3 applies.

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

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

States a specific verb and resource (circular-flow / wash check for a payer wallet) and scopes it as a 'free discovery' tool, which implicitly separates it from the paid scoring siblings. An agent can tell what it produces (a categorical classification plus counts) 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?

'Use as a fast Sybil/wash gate before trusting a counterparty' gives a concrete when-to-use condition. It implies a paid alternative exists ('the full renormalized model stay paid') but never names the sibling tool an agent should reach for instead, so routing is only partly resolved.

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

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

Annotations already mark the tool readOnly and idempotent, and the description adds meaningful behavioral details: paid endpoint costs, the hard-stop that wash_flagged=true never soft-allows, and the warning that unlabeled leftover 0.05 is not a unit price. The phrasing is somewhat cryptic and repetitive, but it discloses important constraints 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 front-loaded with purpose and the sibling alternative, but it repeats the two hard-stop sentences almost verbatim in both the opening paragraph and the hard-stops section. That duplication costs conciseness without adding clarity.

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

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

With a full output schema, complete parameter descriptions, and readOnly/idempotent annotations, the description supplies the remaining necessary context: when to use it instead of the readiness-card tool, the richer fields it exposes, the embedded readiness_card shape, and the key hard-stop rules.

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 input schema already documents all seven parameters, including price_usdc and its caveats. The description reinforces the price caveat but does not add meaningful semantics for the other parameters beyond what the schema already provides.

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

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

The description clearly states this is a low-level preflight check that returns a richer result object, and it explicitly distinguishes itself from get_readiness_card_tool by naming the additional fields it exposes. An agent can tell exactly what this tool is for 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?

It explicitly says to prefer get_readiness_card_tool for most callers and to use this tool only when max_spend_recommendation_usdc, full_report_hint, or suggest_full_report is needed. That is a clear when-to-use and when-not-to-use alternative.

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

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

Annotations only cover readOnly/idempotent, but the description adds substantial behavior: the transparent heuristic components, wash_flag/wash_factor semantics, Base vs Solana scoring paths and the 'unknown' wash_flag caveat, clean rejection of malformed pubkeys, and the guarantee that the failure path returns the same shape as success. These are exactly the traits annotations cannot convey.

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 the core purpose and the exclusion, then layers in caveats and endpoints. It is dense and long, and the trailing endpoint/pricing details (quick teaser, signed receipt) are more operational than call-relevant, keeping it just short of maximally tight.

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 scoring tool with dual-chain logic, wash signals, and a non-trivial failure path, the description covers inputs, semantics, edge cases, and downstream signals. With an output schema present it need not restate return fields, yet it still names the key ones, so nothing an agent needs to invoke it correctly 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% and already documents that the wallet is a Solana base58 pubkey or Base 0x address, so the baseline is 3. The description adds real meaning beyond the schema by explaining how a Base 0x wallet is scored (relayer-attributed x402_base_daily rollup, 90d) versus the Solana path.

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/resource/scope: a 'PAYER-side 0-100 intel score for a wallet from the x402 payments it SENT', with the exact signals (paid calls, distinct counterparties, volume, recency). It also explicitly names the sibling it is not (seller checks -> get_readiness_card_tool, get_provider_reputation, get_merchant_card), so an agent can disambiguate without opening other schemas.

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?

Gives explicit when-to-use (free payer-side discovery) and when-NOT-to-use ('Not a seller check'), routing to named alternatives for seller vetting. It also flags the seller-scores-zero edge case so an agent won't misread a 0 as an error.

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?

Far exceeds the annotations (readOnlyHint/idempotentHint): it discloses that the block path ABORTS and no wallet/signer is contacted, the allow path proceeds, ok=true, no USDC is spent, and that the call writes an EXTERNAL_RUN *candidate* into an attribution ledger tagged with the caller's IP. It even clarifies that a candidate is not a confirmed EXTERNAL_RUN and points to not_external_run_proof — exactly the side-effect transparency a mutation-adjacent call 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?

Front-loaded with the core purpose and the critical 'not a live run / spends no USDC' caveats, and the ledger caveat is clearly segmented. Slightly verbose in the attribution-ledger paragraph, but every sentence carries real 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?

With an output schema present, the description needn't explain return values, and it covers everything else an agent needs: what runs, what is and isn't touched, the deterministic transcript contents, and the ledger side effect plus its caveat. Nothing material 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 fully documents run_id and integration. The description references 'your run_id' and the integration id only in the context of the ledger entry, adding narrative context but no new syntax, format, or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

States a precise verb+resource: a no-spend, recorded transcript of the TWZRD buyer-side x402 trust gate. It explicitly marks itself as 'a recorded example, not a live run', which cleanly separates it from live siblings like evaluate_x402_resource or low_level_preflight without needing to name them.

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

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

Implies usage ('discoverable at runtime with no install and no human', a no-spend demo), but never states when an agent should pick this over evaluate_x402_resource or a real gate run, nor any exclusions. Context is inferable but not spelled out.

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

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

Annotations only declare openWorldHint=false, idempotentHint=false, destructiveHint=false. The description adds substantial context: control-proof, fail-closed authentication where signature+timestamp prove the caller holds the payer wallet's key, and the asynchronous re-call/webhook behavior. It stops short of 5 by not flagging the idempotentHint=false implication that repeated registrations create distinct watches.

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 the core action, then layers on lifecycle, auth, and return-value context. Sentences are dense but each carries signal; overall slightly longer than strictly necessary but well organized.

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 return structure need not be detailed, yet the description usefully notes the returned watch row and computed recheck_after_unix. Auth model, async lifecycle, and the freshness window (via schema) are covered, leaving little for an agent to guess before invoking.

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 baseline is 3. The description references webhook_url and the auth fields conceptually, but adds no format, constraint, or default detail beyond what the schema already documents for the five 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 opening sentence states a specific verb and resource ('Register a re-call watch on a seller wallet'), and the assembly of the watch/unwatch siblings (twzrd_watch_list, twzrd_watch_remove) makes the additive nature inferable from 'register'. It does not name any sibling explicitly, so it falls short of the top tier.

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

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

The description explains the mechanism (proactive re-check after recheck_after_unix, webhook POST on material change), which implies when this tool is useful. However, it never states when to choose this over twzrd_watch_list/remove or other intel tools, and gives no explicit exclusions or prerequisites beyond it being a registration.

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 cover the safety profile (readOnlyHint, idempotentHint), yet the description adds material context: control-proof authentication via signature + timestamp with fail-closed behavior, and the warning that recheck_after_unix is an untrusted V5/V6 hint. These are genuinely non-obvious behavioral traits beyond the structured fields.

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-loads the purpose, then layers return contents, the consumption caveat, and the auth model in short sentences. Dense but each line earns its place; internal jargon (V5/V6) is the only minor drag.

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 return values need not be fully spelled out, yet the description still names the key fields. Auth requirements and the untrusted-hint caveat close the main gaps; only the explicit alternative-routing guidance is absent.

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 the signature message format and freshness window already documented in the schema. The description only echoes 'signature + timestamp' at a high level, adding no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List active re-call watches') scoped to 'your agent wallet,' which is unambiguous against read-oriented siblings. It does not, however, explicitly name or contrast with twzrd_watch_add/remove, so sibling differentiation is implied rather than stated.

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

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

The description gives important interpretive guidance ('do not treat due / shouldRecheck as a trusted allow' and points to evaluateRecall / shouldRecheckTrusted as the real gate), which steers correct downstream use. But it never states when to call this tool versus alternatives such as twzrd_watch_add or twzrd_watch_remove, leaving the primary when-to-use question 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?

Annotations only cover openWorldHint, idempotentHint and destructiveHint, so the description adds meaningful context: the operation is control-proof authenticated, fails closed, and requires a signature + timestamp proving key possession before the row is touched. It stops short of 5 because it does not state the failure mode concretely (error vs no-op) or that deactivation is state-changing and not reversible.

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, front-loaded with the action and constraint before the authentication detail; nothing is padded. The only minor waste is restating the payer_wallet ownership rule already present in the schema.

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, return values need not be explained, and all four required parameters are documented in the schema. The description completes the picture by covering the auth model, though it omits any note on idempotency or what the caller observes after a successful deactivation.

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%, including the exact signed-message format, the freshness window, and the owner-match requirement for payer_wallet. The description's "payer_wallet must match the owner" largely restates what the schema already documents, so it adds little beyond the baseline.

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

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

States a specific verb ("Deactivate") and resource ("re-call watch") with an ID scoping qualifier, which cleanly separates it from the watch_add and watch_list siblings by action. It does not explicitly name or contrast with any sibling, so it stops short of a 5.

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 supplies a real prerequisite ("payer_wallet must match the owner") but never states when this tool should be chosen over twzrd_watch_add, twzrd_watch_list, or any alternative, nor any exclusions. Usage is implied by the verb rather than guided.

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

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

Annotations only declare readOnlyHint/idempotentHint, but the description adds substantial context: pure and offline (no DB/network/payment), tamper-evidence vs authenticity semantics, the return fields, and the key-anchoring rule (trust comes from the published key, not the receipt's pubkey). Minor omission: it never states the effect of require_signature beyond what the schema says.

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 the core action and mechanism, then layers in guardrails; every sentence carries information. Mild padding in phrases like 'Free utility' and 'the after you pay half of the loop' keeps it from a 5.

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 annotations, 100% schema coverage, and an output schema, the description covers the remaining gaps: offline/pure nature, key-anchoring trust model, version compatibility, and freshness semantics. An agent has everything needed to call it correctly without opening the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: max_age_seconds is tied to the library/CLI equivalents and framed as replay freshness gating, and expected_pubkey is explained as the trust anchor override. It does not add anything for require_signature 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?

States a specific verb (offline-verify) and resource (portable V7 trust receipt), plus the exact mechanisms (Keccak256 leaf recomputation, Ed25519 signature check). It is clearly distinguished from siblings like verify_root_inputs and verify_x402_settled_claim by scoping itself to 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?

Frames itself as the 'after you pay' half of the loop and instructs the caller to pass the entire PaidReceipt object, with a note that V5/V6 receipts still verify. Clear context for when to reach for it, though it stops short of naming when another sibling is the better choice.

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, so the safety profile is covered. The description adds that the verification is independent and recomputes values from public data, which clarifies the trust model, but it does not cover permissions, rate limits, or return behavior beyond what the output schema provides.

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 front-loaded sentence with no wasted words. It is appropriately concise, though its brevity leaves little room for structural aids such as usage context.

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

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

The tool has an output schema and annotations covering safety and idempotence, so return-value and safety details need not be repeated. However, the description omits any usage guidance or prerequisites, which would be valuable for an agent choosing among several verification tools.

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

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

Schema description coverage is 100%, so the input schema already fully documents all three optional parameters. The description adds no parameter-level meaning, which is acceptable given the schema's completeness, but it does not enhance 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 gives a clear verb ('verification') and specific method ('recomputes the leaves, dataset hash and root from the public root data'). It distinguishes the operation as root verification, but does not explicitly differentiate itself from sibling verification tools like verify_receipt or verify_x402_settled_claim.

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?

There is no explicit guidance on when to use this tool versus alternatives. It implies verification is needed, but does not state prerequisites, exclusions, or when a different verify tool is more 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 cover read-only and idempotent behavior; the description adds the useful context that the result is evidentiary rather than an authorization to spend. It does not disclose more about outcome handling, but the parameter schema covers match/mismatch/unknown.

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?

One tight sentence, front-loaded with the action and ending with a meaningful boundary ('not a spend decision'). No filler or repetition of schema fields.

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 verification with a rich schema and output schema, the description is mostly sufficient. The only notable gap is not addressing how it differs from verify_receipt, though this is minor given the clear scope.

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 the single parameter's description is exceptionally detailed, covering accepted input, verification logic, and return values. The tool description adds no parameter-level meaning, so the schema-heavy baseline of 3 applies.

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

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

The description uses a specific verb and resource ('Verify a receipts-ledger settlement') and adds a clarifying role ('evidence, not a spend decision'). It does not explicitly distinguish itself from the sibling verify_receipt, so it falls just short of a 5.

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 'this is evidence, not a spend decision' gives the agent a clear caution about how to treat the result, but does not state when to prefer this tool over verify_receipt or other siblings. The usage context is implied rather than explicit.

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