TWZRD Agent Intelligence

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

Far exceeds the annotations: it enumerates every verdict (unknown_seller, expired, check_failed, advertised), states that authorizes_spend is always false, and spells out exactly when needs_approval is true, including edge cases like an unverified discount including zero. It also bounds side effects explicitly.

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 core purpose is front-loaded in one sentence and the verdict enumeration is information-dense rather than padded. The needs_approval sentence is long and clause-heavy, costing a little readability, but every clause carries distinct behavior.

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

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

For a read-only, idempotent verification tool with a full input schema and an output schema, the description supplies the decision logic (verdict meanings, approval rules, no-spend guarantee) an agent needs to interpret results, with nothing material 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 documents all six parameters in detail, including matching rules and price semantics. The description reinforces price behavior via the needs_approval logic but adds no syntax 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?

The opening line states a specific verb and resource ('Pre-spend check of one product against the published listing cards') plus the cost/safety profile ('Free, read-only'). An agent can immediately distinguish this verification-before-buying tool from retrieval siblings like get_merchant_card or get_publication.

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 context is clear ('pre-spend check', the URL the agent is 'about to buy from'), and it plants exclusions ('It does not fetch the store page, open a checkout or move money'). However, it never names a sibling alternative such as get_shopping_check or low_level_preflight, so routing among the 27 siblings still requires 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 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?

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?

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?

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?

Far exceeds the annotations (readOnlyHint, idempotentHint): it documents the block/warn/allow decision mapping, hard-stop rules, the no-counterparty input-bug path, that trust_score is a free heuristic not the full corpus, and that the aop_bind registry is additive and never mutates decision/can_spend. This is rich behavioral context an agent needs before paying.

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 primary role and uses labeled sections, but it is long and prone to repetition – the 'wash_flagged=true never soft-allows' and template-rejection rules each appear more than once. The density of edge-case bullets makes it harder to scan than necessary for a free advisory check.

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 covers decision semantics, next_action handoff, null_reason=no_subject behavior, and the additive aop_bind block. Nothing critical for correct invocation or interpretation of the result appears 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 already 100%, so the baseline is 3. The description adds genuine value beyond the schema: 'Pass seller_wallet OR resource_name' as the routing rule, the price_kind distinction that unlabeled 0.05 is not a unit price, and the explicit ban on passing path templates as seller_wallet. Still, most per-parameter detail lives in the schema.

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

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

States a specific role: 'PRIMARY free pre-spend gate (advisory)' that returns a decision card before x402 payments. It also names a sibling it is not ('use verify_receipt for signed receipts only'), which helps disambiguate. However the core noun ('readiness card') is never plainly defined, so an agent must infer the primary deliverable from the decision-semantics block rather than a clean one-line purpose.

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' and 'When not to use: after you already decided to refuse; use verify_receipt for signed receipts only.' It names the alternative tool and the condition selecting it, plus follow-up routing (verify_receipt on the signed receipt, twzrd_watch_add for re-checks).

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 real context beyond them: the report is free, is built from a verified signed publication on every read, expired observations are treated as historical, and it never starts checkout. These extras usefully set expectations about freshness and provenance.

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 then a compact enumeration of contents and behavioral constraints. It is somewhat dense and prose-heavy but every sentence carries information; nothing is redundant padding.

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 spelled out, yet the description still summarizes them. Combined with the provenance, freshness, and no-checkout details, the definition is complete enough for an agent to call it correctly; only an explicit sibling-routing rule 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 there are no argument semantics to explain; per the rubric a 0-param tool gets a baseline of 4. The description does not need to compensate for any schema gap here.

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 (Read) and a precise resource (Agent Shopping Check) scoped to a named product (Vuori Kore Short, Ink, US). The description enumerates the report's contents (product context, advertised claims, gaps, merchant fixes), so an agent knows exactly what artifact this returns. It is clearly distinguishable from siblings like get_publication or get_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?

Usage is only implied: the agent can infer this is a read-only report fetch and that 'Never pays or starts checkout' marks a boundary, but there is no explicit when-to-use, when-not, or named alternative among the many sibling tools (get_publication, get_claim, evaluate_x402_resource). No routing guidance is offered.

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 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?

Annotations already declare readOnlyHint and idempotentHint, yet the description adds real behavioral context beyond them: hard-stop rules where wash_flagged=true forces decision=block with no warn/allow/quick path, and the pricing interpretation rule that an unlabeled leftover 0.05 / leftover=0 is not a unit price. Some of this is output-interpretation guidance rather than tool behavior, but the hard-stop semantics are genuinely additive.

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 opening leads with edge-case pricing jargon rather than a plain statement of purpose, which hurts front-loading. Content is also duplicated: 'wash_flagged=true never soft-allows' appears twice, and the 'Unlabeled leftover 0.05 / leftover=0' rule is restated in the body and again in the schema. The material earns its place but the redundancy and ordering cost it.

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 and the description correctly points to it ('see the outputSchema') rather than re-documenting return values, and it flags that the embedded readiness_card has the SAME shape as the sibling tool. For a 7-parameter, zero-required evaluation tool this covers routing, hard-stops, and return structure adequately. It stops short of stating any required auth or wallet prerequisites.

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 7 parameters at 100% schema description coverage, the schema already documents each field's meaning, so the baseline is 3. The description echoes one schema rule for price_usdc ('Unlabeled leftover 0.05 / leftover=0 is not a unit price') but adds no new per-parameter syntax or constraints beyond that. Credit is limited because the schema is doing 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 names the tool as a 'Low-level preflight check' and immediately clarifies what it returns (a richer result object with paid_quick_endpoint / paid_trust_endpoint), so an agent can see this is a deeper evaluation pass. It distinguishes itself from the closest sibling by naming get_readiness_card_tool and the extra fields only this tool exposes. The core entity being preflighted (an x402 resource/seller before payment) is only inferable from the parameter names, not stated outright.

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 routes callers: 'Prefer get_readiness_card_tool for most callers. Use this when you need max_spend_recommendation_usdc, full_report_hint, or the suggest_full_report flag.' That names the alternative and the exact conditions that select this tool over it. Nothing about when to reach for this versus the readiness card 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?

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?

Annotations only declare readOnlyHint and idempotentHint, yet the description adds substantial behavioral context beyond them: the block path ABORTS without contacting a wallet/signer, no USDC is spent, and the call records an EXTERNAL_RUN candidate with the caller's run_id and real inbound IP in an attribution ledger. It also discloses a non-obvious side effect (ledger surfacing) and that proof is not implied.

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 purpose is front-loaded in the first sentence, but the description runs long and repeats the no-spend/no-wallet message ('Spends no USDC, contacts no wallet' restates 'a wallet/signer is never contacted'). The attribution-ledger paragraph earns its place, but there is avoidable redundancy.

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

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

An output schema exists, so return-value detail is not required and the description correctly focuses on behavior and the caveat that a candidate is NOT transitive proof. It covers side effects and constraints well; only explicit when-to-use routing to sibling tools 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 both parameters (run_id, integration) are already fully documented in the schema, including defaults and nullability. The description mentions run_id correlation but adds no syntax or format detail beyond the schema, so the 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 names a specific resource (the TWZRD buyer-side x402 trust gate) and explicitly frames this as a recorded no-spend demo transcript rather than a live run, which separates it from live siblings like evaluate_x402_resource. It is clear, but the actual action (returning a deterministic fixture transcript) is embedded in prose rather than stated as a crisp verb+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?

It conveys the usage context ('discoverable at runtime with no install and no human') and the not-a-live-run framing, but never states when to choose this tool over live siblings such as evaluate_x402_resource or low_level_preflight. The agent must infer the demo/smoke-test use case.

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 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=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.

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.