insumer

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

Annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true) only signal that this is a non-idempotent, outbound operation; the description goes well beyond that by disclosing dual signing (ES256 + ML-DSA-65), the 30-minute expiry and the 5-minute expiry when a delegation condition is present, the credit cost and x402 pricing, and that no balance is ever returned. This is exactly the behavioral context an agent cannot get from 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-loaded with the core action, and most sentences earn their place (signing, expiry, cost, error semantics). It is a single dense block with mild redundancy — 'One call reads the chain for every condition... single attestation covering all of them' restates the opening claim, and the met/not-met rule is repeated later — but no sentence is filler.

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

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

With an output schema present, annotations set, and full schema coverage, the description need not re-explain return values; it still covers everything else an agent needs: cost model, expiry, failure handling, signature scheme and JWKS verification path. Nothing material is missing for a correct invocation.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description adds cross-parameter meaning not derivable from individual field docs — notably that Bitcoin, Tron, Stellar and Sui support token_balance only, and that different condition kinds and chains are combined into a single attestation, which shapes how the conditions array is composed.

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 gives a precise verb and resource: evaluate 1-10 conditions against a wallet's on-chain state and return one signed attestation, with an explicit output shape (yes/no per condition, never the balance). The chain coverage and condition-type list make it distinguishable from the sibling trust/merchant tools 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?

Usage context is concrete: which condition types exist, which chains support which, the credit price, and operational guidance for rpc_failure (503) — retry, never treat as a no. It never explicitly contrasts itself with the sibling insumer_wallet_trust / insumer_batch_wallet_trust, so the when-to-prefer-this-over-that decision is left partly 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?

With annotations present the bar is lower, yet the description still discloses cost (3 credits per successful wallet, 6 with merkle, x402 covers all wallets), partial-success semantics, the fact that failed wallets yield no signed profile and must not be read as 'no', that profiles cannot be re-fetched (consistent with idempotentHint=false), the response size, and the summary-vs-structuredContent split. This is unusually rich behavioral disclosure.

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 correctly with purpose and speed benefit, but the body is a dense block that restates the detail parameter and the credit/x402 pricing twice, and mixes pricing, dimension ordering, retry policy, and response format without structure. Every fact is useful, but a scanner cannot easily locate a specific concern.

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 3-parameter tool with full schema coverage, an output schema, and annotations, the description covers everything an agent needs to call it correctly: cost model, partial-failure handling, dimension ordering, response size, and the non-repeatability of signed profiles.

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 goes beyond the schema by explaining that Solana/XRPL/Bitcoin/Tron wallets each switch on an extra dimension and that dimensions arrive in a fixed, identical order for every wallet in the batch. The credit implication of proof='merkle' (6 vs 3) is also stated, which the schema does not convey.

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 gives a precise verb, resource, and scope: 'Generate wallet trust fact profiles for up to 10 wallets in a single request.' The batch framing ('Faster than sequential calls') cleanly separates it from the single-wallet sibling insumer_wallet_trust without the agent needing to open either 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?

Gives clear conditional guidance: set detail='full' only on the call that needs it, add proof='merkle' when Merkle storage proofs are required, and retry only the wallets that came back as error entries. It does not explicitly name insumer_wallet_trust as the single-wallet alternative, so the 'when not to use this' side 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 already cover read-only/idempotent/non-destructive, and the description adds substantial context beyond them: it never returns raw balances, consumes no credits, exposes totalDiscount vs discountIfProven, and clarifies that no proof of wallet control is carried. The 503 retry semantics are a genuinely useful behavioral disclosure.

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 cost, then error semantics, then the discount-field caveats. Dense but each sentence carries information; the discountIfProven/walletTerms sentence is somewhat packed but still earns its place.

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

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

With an output schema present and full annotation coverage, the description supplies the remaining interpretive context an agent needs — cost model, error retry rule, unproven-wallet caveat — so nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by stating the wallet input may be EVM, Solana, or XRPL — clarifying that the three wallet-typed properties are mutually exclusive chain alternatives rather than additive inputs.

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+resource+scope: 'Calculate discount for a wallet at a merchant,' with the chain coverage and the free/no-credit trait stated. It is clearly distinguishable from siblings like insumer_wallet_trust or insumer_attest, which do not compute merchant discounts.

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 operating context: it is free, accepts EVM/Solana/XRPL wallets, and that a 503 rpc_failure means retry rather than treat as ineligible. It does not, however, state when to prefer this over a sibling such as insumer_wallet_trust or insumer_attest.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description still adds real value beyond them by stating "No authentication or credits required," which affects whether the agent can call this freely as a discovery step.

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

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

Two sentences, front-loaded with the action and then the payload contents; all clauses carry information (field list, provider examples, cost model). The second sentence is somewhat dense with parentheticals, which is a minor readability cost rather than waste.

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 explained, and the description still names the meaningful fields and concrete provider examples (Coinbase Verifications on Base, Gitcoin Passport on Optimism). Combined with the zero-parameter schema, this is complete enough for an agent to call correctly, with only the number/ordering of results left unspecified.

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 rubric the baseline is 4. The description correctly adds nothing about parameters because there are none to describe, keeping it consistent with the empty input 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 uses a specific verb+resource ("List the compliance templates") and immediately scopes it to EAS attestation conditions, making it clearly distinct from siblings like insumer_attest or insumer_wallet_trust. It also enumerates what a template contains (schema IDs, attester addresses, decoder contracts), so the agent knows exactly what kind of object it gets back.

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 states the purpose of the tool: fetching templates so a condition can "name the template instead of raw EAS parameters," which tells the agent when this lookup is warranted. It does not name an alternative tool or an explicit when-not condition, but the usage context is unambiguous for a zero-argument listing tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety and idempotency are fully covered structurally. The description adds context about what the profile contains (walletTerms, verification status) but does not disclose behavioral traits beyond the field enumeration — no auth requirements, rate limits, or caching behavior.

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

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

A single sentence that front-loads the verb+resource and then enumerates the payload and the decision context. It is information-dense without waste, though the clause after 'so you can decide' is slightly run-on.

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 required parameter, full schema coverage, annotations covering safety/idempotency, and an output schema that presumably documents the return shape, the description does not need to explain return values. It covers purpose, payload contents, and the decision context. Slight gaps remain around alternatives and when-not-to-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?

There is only one parameter (id) with 100% schema description coverage and a pattern constraint. The description adds no parameter-level detail, but with a single well-documented parameter and full schema coverage, this is adequate — baseline 3 is appropriate.

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

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

The description states a specific verb+resource ('Get full public merchant profile') and enumerates the payload fields (token tiers, NFT collections, discount mode, verification status, walletTerms). It does not name any sibling tool for differentiation, so it falls 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?

There is an implied usage context — 'so you can decide whether to sign before creating a code' — which tells the agent when this data is relevant (pre-signing decisions). But there is no explicit when-to-use statement, no mention of alternatives like insumer_list_merchants for browsing, and no exclusion criteria.

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 readOnly, idempotent, openWorld, and non-destructive, so the bar is lower; the description still adds real behavioral context beyond them — 'No authentication required' and the rule that matching must be by kid/pqKid, with an unknown kid being 'unverifiable, not refuted.' It does not describe caching or rotation behavior.

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

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

Front-loaded with the core action and appropriately short for a zero-parameter tool. The single dense sentence packs several distinct facts (key types, verification use, matching rule, no auth), which is efficient though slightly overloaded.

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 structure needn't be explained, yet the description still adds the key-identity semantics that the schema alone wouldn't convey. Nothing needed to invoke the tool correctly is missing; only optional context like key rotation cadence 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?

Zero parameters, so baseline is 4. The description's mention of kid/pqKid is about the response payload, not inputs, and the empty schema needs no compensation.

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 ('Get InsumerAPI's public signing keys as a JWKS') and enumerates the key types returned (ECDSA P-256, ML-DSA-65 AKP). It is unmistakably distinct from the attest/trust/compliance siblings, which all consume these keys rather than fetch 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?

Gives clear context for use: 'Signatures on attestation and trust responses verify against these keys,' implying this is the verification prerequisite. However, it never explicitly names alternatives or states when-not to call it, so it stops short of the explicit routing a 5 requires.

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 safety profile is covered. Description adds useful return-field context (walletTerms explanation) beyond annotations, but doesn't mention pagination behavior or default result size, which are relevant for a list 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?

Two sentences, front-loaded with purpose, then filters, then return values. No waste.

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-field details needn't be repeated, but the description does a good job summarizing key fields anyway. Missing pagination behavior for a list tool is a minor gap given params cover limit/offset.

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 fully documents all four parameters including defaults, ranges, and enum. The description adds no syntax or format details beyond what the schema provides. 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?

Specific verb+resource: 'Browse merchants in the public directory.' Clearly distinguishes from sibling insumer_get_merchant (singular fetch) by scoping to listing/browsing.

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?

Mentions filtering by token and verification status but gives no when-to-use guidance or alternatives. An agent would need to infer that insumer_get_merchant should be used for a single merchant rather than listing.

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, idempotentHint, destructiveHint and openWorldHint, so the safety bar is lower. The description adds real value beyond them by disclosing empty-result semantics and the non-exhaustive nature of the registry, which prevents a common misinterpretation.

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

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

Four sentences, front-loaded with the core action before the interpretive caveats. Each sentence earns its place, though the 'not the list of what can be checked' point is restated in slightly different phrasing in the following sentence.

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 and rich annotations, the description needn't cover return values. Combined with the safety annotations and full schema coverage, the definition gives the agent everything needed to call and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the three filter parameters (type, chain, symbol) are already documented in the schema. The description restates the filter axes without adding format or edge-case detail, 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 (List) and resource (tokens and NFT collections in the Insumer registry) with clear scope. It distinguishes itself from the check/attest siblings by framing the registry as a directory rather than the set of checkable assets.

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?

Strong guidance on interpretation: 'The registry is a directory, not the list of what can be checked' and 'An empty result means nothing is listed under that filter, not that the token is unsupported.' This tells the agent when not to conclude lack of support, but it does not explicitly name sibling tools as alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds significant context beyond them: no authentication required, no credits consumed, return shape (valid/invalid with reason, walletProven), and a data privacy guarantee ('Does not expose wallet or token data'). This is a rich behavioral disclosure that 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?

Three sentences, front-loaded with the core action and followed by context, return info, and constraints. Every sentence adds value with no waste.

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 having an output schema, the description still summarizes the return values (valid/invalid status, reason, walletProven), which helps the agent understand the outcome. It covers authentication, cost, side effects, and privacy. Complete for a validation tool with one parameter and annotations.

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

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

Schema coverage is 100% and the schema documents the single parameter with a pattern and description. The description mentions the INSR-XXXXX format, which is redundant with the schema, and adds no extra semantic detail about the parameter beyond what is already provided. 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 specific verb (Validate) and resource (INSR-XXXXX discount code), and explicitly scopes it to merchant backends during ACP/UCP checkout. This distinguishes it from siblings like insumer_check_discount or insumer_attest by naming the exact format and use context.

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

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

Clearly states the context ('For merchant backends during ACP/UCP checkout') and the purpose ('confirm code validity, discount percent, and expiry'). This tells when to use it, though it does not explicitly name an alternative tool (e.g., insumer_check_discount) or state when NOT to use it.

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

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false): it discloses signing semantics (conditionSetVersion must be logged, never rejected on), error semantics (503 rpc_failure means nothing was signed), refund behavior for undelivered Merkle proofs, credit pricing (3, or 6 with proof), and that the hosted endpoint draws from a shared allowance rather than charging the caller.

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, but the body is a single dense run-on of nested parentheticals (dimension list, counts, ordering, account-row behavior, pricing, x402, llms.txt URL) that would benefit from structure. Every fact is relevant, yet the packing reduces scannability.

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 still appropriately summarizes per-dimension pass/fail counts and the overall summary. Combined with error/retry semantics, cost model, and a live URL for current chain/check counts, an agent has everything needed to call and interpret this correctly.

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

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

Schema coverage is 100% with rich per-parameter descriptions, so the baseline is 3. The description adds real semantic detail: each optional wallet's effect (Solana/XRPL/Bitcoin/Tron add dimensions; Stellar/Sui only let existing rows evaluate) and the fixed dimension ordering, plus the two-row structure of the account dimension. It largely reinforces what the schema already says, which caps it below 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?

Opens with a precise verb+resource: 'Generate a signed wallet trust fact profile for an EVM wallet', then enumerates what a profile contains (presence checks across named dimensions, 155 base checks / 27 chains). This distinguishes it cleanly from the sibling insumer_batch_wallet_trust (singular vs. batch) and from insumer_attest (which is referenced for account_code proofs).

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?

States the intended use case explicitly ('Designed for AI agent-to-agent trust decisions') and gives the alternative for account proofs (the attest tool's account_code condition). It also gives operational guidance (retry on rpc_failure 503, never treat as a 'no'). It does not, however, say when to prefer this over insumer_batch_wallet_trust or the non-trust attest path for a single wallet.

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