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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent, open-world). The description adds genuinely useful context beyond them: the one-merchant-credit cost, which is a real constraint an agent must budget for. It does not cover wallet-format requirements or error behavior, keeping it short of 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?

Three short sentences, front-loaded with the purpose and followed by return shape and cost. Mild redundancy: the return-value sentence partially duplicates what the output schema already declares, but nothing is padded.

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

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

With an output schema present, the description needn't explain return values (though it does), and it adds the credit-consumption cost plus the relationship to the non-ACP check. For an 8-parameter, 1-required tool this is adequately complete; only explicit sibling routing is missing.

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

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

Schema description coverage is 100% and every parameter carries its own regex pattern and description, so the schema does the heavy lifting. The description adds nothing about the multi-chain wallet alternatives or the items array, so baseline 3 applies.

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

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

States a specific verb+resource ('Check token-holder discount eligibility') and qualifies the output format (ACP). The sentence 'The on-chain check is the same one behind INSR discount codes, wrapped in ACP format' explicitly distinguishes it from the sibling insumer_check_discount and the format twin insumer_ucp_discount.

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 implied by the ACP-format framing and the credit-cost note, so an agent can infer this is for ACP checkout flows rather than direct discount-code checks. However, it never states when to pick this over insumer_check_discount or insumer_ucp_discount, nor any prerequisites for the wallet/merchant setup.

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: discloses ECDSA signing plus a post-quantum companion signature, cost (1 credit, 2 with proof), shorter 5-minute expiry for delegation conditions, failReason on failure, and that declaredLimits are reported rather than simulated. It also honestly frames erc8004_agent registration as permissionless with no vetting or reputation — substantial behavioral context the 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?

Purpose is front-loaded and every sentence carries information (condition types, chains, signing, cost, expiry). It is a dense single paragraph, though, and the long inline enumeration of condition types is harder to scan than a structured list would 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?

Given a 9-type condition tool with 11 parameters and an output schema present, the description covers capabilities, chain coverage, cost, signing, and expiry behavior. Nothing an agent needs to call it correctly is missing, and return-value detail is properly delegated to the output schema.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters including condition sub-fields. The description largely restates condition types and semantics already present in the schema (ratio_to_amount, erc7710_delegation, proof, etc.), so it adds little beyond the structured fields — baseline 3.

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 — 'Verify 1-10 on-chain conditions for a wallet and return a signed yes or no for each, never the balance' — which is precise about what is and isn't returned. It does not, however, name or differentiate itself from sibling tools like insumer_wallet_trust or insumer_batch_wallet_trust, leaving the agent to infer the distinction from 'signed'.

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 enumerates condition types and chain support, which implies when each variant applies (e.g. 'Bitcoin, Tron, Stellar and Sui support token_balance only'), but never states when to choose this tool over the unsigned wallet_trust or batch variants. Usage is implied rather than directed.

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 declare readOnlyHint=false, idempotentHint=false and openWorldHint=true but say nothing about cost or failure behavior. The description fills exactly that gap: credit pricing (3/wallet, 6 with merkle), the fact credits are charged only for successful profiles, and partial-success semantics with per-wallet error entries. This is behavioral context the structured fields cannot supply.

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 and batch size are front-loaded, then speed rationale, then signing/partial success, then cost. Five sentences with no filler and no repetition of schema field names.

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 no explanation. Everything an agent needs to invoke this correctly is covered: input limit, cost model, the merkle upgrade, and what happens on partial failure.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by tying the 'merkle' enum value to a concrete price change and by framing the wallets array as a 1-10 size constraint with per-entry independence, which adds economic meaning 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?

States a specific verb and resource ("Generate wallet trust fact profiles") with an explicit batch scope ("up to 10 wallets in a single request"). The batch framing plus the signing/ID detail makes it distinguishable from the single-wallet sibling insumer_wallet_trust.

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 a clear rationale for choosing this over the sequential path ("Shared block fetches make this faster than sequential calls"), which tells the agent when a multi-wallet call is warranted. It never names the single-wallet sibling for the 1-wallet case, so the routing guidance is incomplete but present.

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 cover safety (destructiveHint, idempotentHint=false, openWorldHint), but the description adds substantial context beyond them: it does not move funds, unsupported chains are unrecoverable, purchases are non-refundable, the first purchase registers the sender wallet, later purchases must use the same sender, and updateWallet replaces it. These are material behaviors an agent cannot derive 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?

Dense but front-loaded, and every clause carries non-obvious information (chain support, conversion, wallet rules, irreversibility). It is on the longer side for a description, but no sentence is 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 no explanation, and the description covers the mechanics, supported chains, irreversibility, wallet registration, and a pricing pointer. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is already 100%, so the schema documents amount, txHash, chainId, and updateWallet. The description still adds useful meaning beyond it: EVM/Solana auto-detect USDC vs USDT, BTC is converted at market rate with 1 confirmation, and the wallet-registration/updateWallet semantics.

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

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

States a specific verb+resource ('Add verification credits to the current API key') and immediately narrows the input to a tx hash for a payment already sent. This clearly distinguishes it from siblings like insumer_buy_key, insumer_buy_merchant_credits, and insumer_confirm_payment.

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

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

The description establishes the precondition clearly ('a payment the caller has already sent', 'it submits the transaction hash'), which tells the agent this is a post-payment submission step. It does not, however, explicitly name the related sibling tool (e.g. insumer_confirm_payment or insumer_buy_key) as an alternative, so routing is inferred rather than stated.

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

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

Adds substantial behavior beyond the annotations: receiving addresses per chain, the 1-confirmation requirement for Bitcoin, automatic USDC/USDT detection, BTC-to-USD market conversion, one-key-per-wallet rule, and a non-refundable policy. These are exactly the operational constraints an agent needs and none are in the annotations, which only carry openWorldHint/idempotentHint/destructiveHint flags.

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, then layers prerequisites, addresses, and policies in a readable sequence. It is dense — the address list with confirmation note is packed into one mid-paragraph sentence — but nearly every clause carries actionable 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?

For a payment-registration tool with an output schema already covering return values, the description supplies everything else an agent needs: prerequisites, per-chain payment addresses, confirmation rules, conversion behavior, and the non-refundable/one-key constraints. Nothing required 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%, so the baseline is 3, but the description adds real semantics: it maps chainId values to accepted assets, explains that amount is not required for BTC, and lists the exact addresses funds must be sent to. This meaningfully extends the parameter documentation rather than restating it.

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 — registering an API key against an already-sent payment — and disambiguates from the credit path by noting top-ups go through a credit purchase instead. The clarification that the tool 'does not move funds: it submits the transaction hash' pins down exactly what the operation does versus what an agent might assume.

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 pre-conditions (payment already sent, no auth, no email) and an explicit when-not case (existing keys are topped up via credit purchase instead), which routes the agent away from re-using this tool. It stops short of naming the sibling tool (insumer_buy_credits) explicitly, so it is clear context rather than full alternative routing.

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

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

The annotations already declare this is a non-read-only, destructive, non-idempotent, open-world operation. The description adds substantial behavioral context beyond that: it explicitly says funds are not moved, that it submits a txHash, that payment is non-refundable, that it is owner-only, that the first purchase registers the sender wallet, that updateWallet replaces it, and that BTC requires one confirmation. This is a rich and helpful disclosure for a state-changing 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 a single dense paragraph that front-loads the core action and packs multiple operational caveats into minimal space. It is well-sized for a complex tool, though the long compound sentence structure and appended pricing URL slightly reduce readability.

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 complexity, full schema coverage, and the presence of an output schema, the description covers everything an agent needs: what it does, which chains and assets are accepted, the non-refundable and owner-only constraints, wallet registration semantics, and the fact that it does not move funds. No critical gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by noting that EVM/Solana stablecoins are auto-detected and that BTC is converted at market rate with one confirmation required. These operational details are not fully captured in the schema and clarify how chainId and amount behave in practice.

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 and resource ('Add merchant verification credits') and the input condition ('against a ... payment the caller has already sent'), which distinguishes it from a generic credit purchase. It does not explicitly name or contrast with the sibling insumer_buy_credits, so the differentiation is implicit rather than spelled out.

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 usage context (after a payment has been sent, owner only, first purchase registers the wallet) but never names the alternative tools or states when-not to use this one versus insumer_buy_credits or insumer_confirm_payment. Adequate context is present, but routing guidance 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real value beyond them: it discloses the privacy-relevant return behavior ('never raw balance amounts') and the billing behavior ('does not consume credits').

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

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

Three short sentences, front-loaded with the core action followed by return behavior and cost. No filler, though the title's 'Free' repeats the final sentence's cost statement.

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

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

An output schema exists, so return values need not be described, and the schema fully documents all 7 parameters. The description covers purpose, output privacy and cost, leaving only usage-alternative guidance unaddressed.

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

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

Schema description coverage is 100%, with each wallet parameter carrying its own pattern and format note, so the baseline is 3. The description adds no per-parameter meaning beyond the schema; only 'per token' hints at the result shape.

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: 'Calculate discount for a wallet at a merchant.' It also names the scope (per-token discount percentage) so an agent can distinguish it from siblings like insumer_wallet_trust or insumer_validate_code.

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 when to use it (to compute a discount for a wallet/merchant pair) and flags the cost model ('Free: does not consume credits'), which is a genuine selection signal. However, it names no alternative tool and gives no explicit when-not-to-use or prerequisite 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?

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so replacement semantics are partially covered. The description nonetheless adds two things annotations cannot express: the 4-collection ceiling and the owner-only authorization requirement, which materially affect how the agent invokes it.

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

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

Three short sentences, front-loaded with the core purpose, then constraints. No filler and nothing buried.

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, full parameter coverage, and annotations covering safety, the description needs only to add the replacement behavior, cap, and auth requirement — all of which it does.

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 and every nested field (name, taxon, chainId, discount, contractAddress) are already documented in the schema. The description adds only the max-4 limit, which is also in the schema via maxItems, 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?

States a specific verb (configure) and resource (NFT collections granting discounts), plus the key operational fact that it replaces the existing configuration. It is distinguishable from siblings like insumer_configure_tokens, though it never names that sibling explicitly.

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 usage context: it is a full replacement operation, capped at 4 collections, and requires owner privileges. It lacks an explicit 'use X instead when...' pointer to the tokens/settings siblings, but the prerequisites are 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them by stating that supplied fields replace current values (partial-update semantics) and that the operation is owner-only, which the annotations do not 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?

Two dense sentences: scope first, then the update/auth semantics. Every clause earns its place with no redundancy or filler.

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

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

With an output schema present and full parameter documentation in the schema, the description only needs to supply what structured fields omit: partial-update behavior and the owner-only restriction, both of which it provides. Nothing critical is missing, though guidance on related configure_* siblings would round it out.

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

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

Schema description coverage is 100%, with each parameter fully documented including the discountMode enum semantics and usdcPayment nesting. The description names the configurable areas but adds no syntax or format detail beyond the schema, so the baseline 3 for high coverage 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 (Update) and resource (merchant settings) and enumerates the exact scope: discount stacking mode, cap, and stablecoin payment configuration. This implicitly distinguishes it from sibling configure tools like insumer_configure_tokens and insumer_configure_nfts, though it never names them explicitly.

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

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

Provides useful invocation constraints (all fields optional, partial-replace semantics, owner-only access), but offers no explicit when-to-use guidance or routing to alternatives such as configure_tokens/configure_nfts for other setting categories. Usage is implied rather than directed.

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 destructiveHint=true, idempotentHint=true and openWorldHint, so the safety profile is present. The description still adds non-redundant context: the replace (not merge) semantics of the write, the 8-token cap, and the owner-only authorization requirement. Return/error behavior is left to the output schema.

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 compact sentences, front-loaded with the purpose, then the replace semantics, the limit, and the permission. Nothing is wasted and no sentence is redundant with another.

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 destructive, owner-scoped write with a rich schema, annotations and an output schema, the description covers purpose, replace semantics, cap and authorization. It omits how invalid chain/token combinations fail and how ownToken interacts with the partner cap, but those are secondary given the structured data.

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 id, ownToken, partnerTokens and all nested fields in detail. The description adds only the 'max 8 tokens total' cap, which loosely maps to the partnerTokens maxItems=8; it does not explain the ownToken vs partnerTokens distinction or null-to-remove. 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 and resource: 'Configure merchant token discount tiers. Set own token and/or partner tokens.' This clearly distinguishes it from sibling reads like insumer_list_tokens or insumer_check_discount. It stops short of naming any sibling explicitly, so it does not reach the 5 bar.

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 real usage context: this replaces the existing configuration rather than appending, is capped at 8 total tokens, and is owner-only. That tells the agent when the call is appropriate and who can make it, though no alternative tool is offered for the non-owner or non-replacing 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?

Annotations already declare the mutation profile (readOnlyHint=false), idempotency, and open-world behavior, so the safety bar is lower. The description usefully adds that the server verifies the on-chain transaction receipt, but says nothing about what happens on verification failure, required payment timing, or confirmation latency.

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 short sentences, zero waste, with the action front-loaded and the server-side verification detail following. Nothing is repeated from the schema or title.

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 explained, and the annotations plus 100%-covered schema leave little else required. The description covers purpose and the receipt-verification behavior; only edge-case behavior (failure handling, whether a prior validation is required) 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% with all four parameters documented (code format, txHash patterns, chainId options, amount), so the burden is already met by structured data. The description adds no additional parameter meaning beyond what the schema provides, 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 (confirm) and resource (stablecoin payment for an INSR discount code), so the agent knows this finalizes a payment against a discount code. It is distinct from validate_code/check_discount by focusing on payment confirmation, but it never names those siblings explicitly.

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 word 'confirm' suggests this is called after a stablecoin transfer has been sent, ideally following a code validation step. There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as insumer_validate_code or insumer_check_discount.

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 (which only declare non-read-only, non-idempotent, non-destructive, open-world), the description discloses ownership semantics, the free-credit grant on creation, and a per-API-key quota. That quota detail is valuable for avoiding failed calls. It does not clarify what happens on duplicate companyId or what the response contains.

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 tightly written sentences with zero filler; the core action and constraints are front-loaded. Every clause carries information an agent can act 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 an output schema present, return values need not be described, and annotations cover the safety profile. The description covers ownership, credits, and quota, leaving only edge cases (duplicate ID handling, quota exhaustion behavior) unaddressed.

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 three parameters are fully documented in the schema, including patterns, lengths, and meanings, so the baseline is 3. The description adds no parameter-level syntax or format guidance beyond what the schema already provides.

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

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

Specific verb ('Create') plus resource ('merchant'), with extra scope detail: ownership by the creating API key and an initial allowance of free verification credits. It implicitly distinguishes itself from siblings like insumer_list_merchants and insumer_get_merchant, though it does not name them.

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

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

The quota note ('Limited number of merchants per API key') hints at a precondition an agent should weigh, but there is no explicit when-to-use guidance and no routing to alternatives for inspecting or managing existing merchants. Usage is implied rather than stated.

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, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by enumerating what is returned (balance, tier, daily rate limit) and that it is key-scoped, but it says nothing about rate limiting on the check itself or how the daily limit is reset.

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 front-loaded sentence that identifies the action, the subject, and the key scoping with no filler or redundancy.

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

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

For a zero-parameter read tool with an output schema and full annotation coverage, the description supplies everything needed to invoke it correctly. The only shortfall is the missing tie-in to the credit-purchasing siblings, which is a usage rather than completeness gap.

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 is nothing for the description to disambiguate; the baseline of 4 applies. Schema description coverage is also 100%.

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

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

The description gives a specific verb ('Check') plus the exact resource ('verification credit balance, tier, and daily rate limit') and scopes it to the current API key. It is clearly distinguishable from siblings like insumer_buy_credits or insumer_buy_key, though it never names 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?

There is no when-to-use or when-not-to-use guidance, and the natural alternatives (insumer_buy_credits, insumer_buy_merchant_credits) are never referenced. The agent must infer that this is a pre-purchase check rather than being told so.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds only that the profile is 'public' and which field groups are returned, which is useful scoping context but not deep 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?

One front-loaded sentence with no filler; the verb and resource come first and the enumerated contents follow. It is tight, though the trailing field list is somewhat inventory-like rather than decision-relevant.

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 the description's burden, and annotations fully cover the safety profile. For a single-parameter, non-destructive read, the definition is essentially complete; only usage routing to siblings 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?

There is a single parameter with 100% schema description coverage ('Merchant ID'), so the schema already carries the semantics. The description adds no format, lookup, or fallback detail about the id, 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 (Get) and resource (merchant profile) and enumerates the payload contents (token tiers, NFT collections, discount mode, verification status). It does not explicitly distinguish itself from the sibling insumer_list_merchants, but the singular 'a merchant profile' plus the required id makes the single-record scope inferable.

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 no when-to-use guidance, no prerequisites, and never names an alternative such as insumer_list_merchants for discovery or insumer_check_discount for discount evaluation. The only usage signal is the implied 'you have a merchant id'.

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, idempotentHint, openWorldHint and non-destructive, so safety is covered. The description adds that the directory is public (no auth implied) and enumerates return fields, but the field list largely duplicates the output schema and no pagination or rate-limit behavior is disclosed.

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

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

Three short, front-loaded sentences with no filler. The final sentence enumerating return fields is mildly redundant given the output schema, but the structure remains tight and easy to scan.

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

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

With a full output schema, rich annotations, and 100% parameter coverage, the description only needs to frame purpose and filters, which it does. It is nearly complete; the only gap is any guidance on result-set size or when to prefer the singular get_merchant tool.

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

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

Schema description coverage is 100%, so the schema fully documents limit, offset, token, and verified. The description restates the token and verification filters without adding format or syntax beyond the schema, which is the baseline when the schema does the heavy lifting.

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

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

States a specific verb (browse/list) and resource (merchants in the public directory), which cleanly separates it from the singular insumer_get_merchant. However, it never explicitly names the sibling or the listing-vs-single distinction, so differentiation is left to inference.

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: 'Browse merchants in the public directory' suggests a directory-scan use case, and the filters hint at narrowing results. There is no explicit statement of when to choose this over insumer_get_merchant or insumer_list_tokens, and no 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=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the registry scope (tokens + NFT collections) but says nothing about pagination, result limits, or ordering for a potentially large registry listing.

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, zero filler, with the core purpose front-loaded and the filtering capability trailing. Every clause 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?

An output schema exists, so the description needn't explain return values, and annotations cover the safety profile. For a simple zero-required-parameter list tool the description is nearly sufficient, with only pagination/result-size behavior left unstated.

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 all three filters (type, chain, symbol) are already documented in the schema including the enum values and chain IDs. The description's mention of the same three filters adds no syntax, defaults, or combination semantics beyond the structured fields.

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 all registered tokens and NFT collections in the Insumer registry' — which is unambiguous and matches the title. It doesn't need to differentiate against siblings since none of the other Insumer tools list tokens, but it also makes no explicit contrast, so it stops short of a 5.

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

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

The only usage-shaped text is 'Filter by chain, symbol, or asset type,' which describes the parameters rather than when to reach for this tool. There is no statement of prerequisites, when-not-to-use, or alternatives among the nine sibling tools.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds two things annotations cannot convey: that the returned data is the private/full view and that an owner-level authorization check applies. No error or rate-limit behavior is described, but the auth disclosure is genuinely useful.

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

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

A single front-loaded sentence; the verb and access constraint are positioned clearly. The enumerated field list is a bit dense, but it earns its place by telling the agent what the private payload exposes.

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 documentation is not needed, and annotations cover the safety profile. The description supplies the missing scope and ownership context; only failure/unauthorized behavior is left unstated, which is a minor gap.

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?

Only one parameter (id), and the schema describes it at 100% coverage with pattern and length constraints. The description adds no syntax or format detail beyond the schema, so the baseline of 3 for high schema coverage 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 (Get) and resource (private merchant details) and enumerates exactly what the payload contains: credits, token configs, NFT collections, directory/verification status, payment settings. The 'private' qualifier plus 'Owner only' implicitly separates it from the public-facing merchant reads in the sibling 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?

'Owner only' is a real access precondition, but the description never says when to prefer this over insumer_get_merchant or insumer_list_merchants, nor what to do when the caller is not the owner. Usage is only implied by the ownership constraint.

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 write (readOnlyHint=false), idempotent, non-destructive, and open-world. The description adds the meaningful extra context that the caller must be the owner and that publication is public-facing and republished from existing state rather than ad-hoc input. It stops short of noting failure modes (e.g., what blocks publication).

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, zero filler; the action and scope come first and the authorization constraint is appended compactly at the end.

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 only one parameter, full schema coverage, an existing output schema, and annotations covering the safety/idempotency profile, the description covers what an agent needs. Minor gaps remain around prerequisites and what a failed publish looks like.

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 single `id` parameter is fully documented as the merchant ID with a pattern and length bound. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb pair (publish/refresh), the exact resource (merchant's listing in the public directory), and the data source (current tokens and settings). No sibling tool touches directory publication, so the agent can immediately distinguish it from configure_tokens, configure_settings, or verify_domain.

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

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

"Owner only" gives a clear permission gate, and "refresh ... from its current tokens and settings" implies the tool should follow configuration steps. However, it never explicitly says when to call it versus alternatives such as re-running configure_tokens, nor states prerequisites (e.g., verified domain) as an exclusion condition.

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 readOnly=false, idempotent=false, destructive=false, and openWorld=true, so the safety profile is covered. The description adds useful context beyond that: what the call returns (token + three placement mechanisms), the auth constraint ('Owner only'), and the downstream benefit (trust badge in the public directory). It does not mention rate limits or token expiry.

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 tight sentences: what is requested, what comes back, and the permission gate. Front-loaded with the core action and no redundant 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?

An output schema exists, so return values need not be restated (though the description helpfully summarizes them). With annotations covering the mutation/safety profile and the description adding the owner-only constraint and outcome, an agent has everything needed to call 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% for both parameters (id and domain), so the schema carries the semantics. The description adds no syntax, format, or constraint detail beyond what the schema already provides, which is the baseline 3 case.

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 ('Request a domain verification token for a merchant') with concrete output detail (token plus DNS TXT, HTML meta tag, or file upload). It does not explicitly contrast with the closely related sibling insumer_verify_domain, so sibling differentiation rests largely on the tool name.

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 'Owner only' note gives a prerequisite/permission gate, and the description implies the tool is a first step before verification. However, it never states when to call this versus insumer_verify_domain or what to do after placing the token, leaving workflow routing 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 covering only the safety profile (readOnlyHint false, idempotentHint false, openWorldHint true), the description supplies the substantive behavior: it is a non-idempotent one-per-email issuance, subject to a per-IP daily quota, requires no payment, and requires a config edit plus restart. Rate limits and quota constraints are disclosed, which is exactly what the 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?

Five short sentences, front-loaded with what is generated and the cost, then the post-call action, constraints, and a reference link. Every sentence carries distinct information with no repetition of the title.

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 no explanation in prose. The description covers the remaining gaps an agent needs: cost, key format, quota limits, and the required follow-up (inject as INSUMER_API_KEY and restart). Nothing material is missing for a two-parameter setup tool.

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

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

Schema description coverage is 100%, so email and appName are already documented in the schema. The description reinforces that email drives the one-key-per-email rule but says nothing about appName or its default, so it adds only marginal meaning. Baseline 3 applies when the schema carries the parameter 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?

States a specific verb and resource ('Generate a free-tier InsumerAPI key') plus the artifact format (insr_live_...), so the agent knows exactly what is produced. It implicitly separates itself from the paid sibling insumer_buy_key via 'free-tier' and 'No credit card required', but never names an alternative, so sibling differentiation is inferential rather than explicit.

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 when this is used (agent needs a key for MCP config, then restarts) and states real constraints: one free key per email and a per-IP daily limit. It stops short of naming alternatives such as insumer_buy_key for higher allowances, so there is no explicit when-not 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?

Annotations declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, and the description adds the crucial billing fact that it 'consumes 1 merchant credit,' explaining why the call is non-read-only. It also sketches the return shape (title, extension field, applied array). It stops short of stating auth requirements or whether the credit is spent on failure.

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 tight sentences, front-loaded with the action and format before the return shape and billing note. Every sentence adds distinct information; no repetition of the name or title.

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

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

With an output schema present, the return-value detail is bonus rather than required, and the billing note covers the main non-obvious cost of calling a non-read-only tool. A brief mention of when UCP applies vs ACP would close the remaining gap.

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% across all 8 parameters (wallet variants, items, merchantId), so the schema carries the parameter burden. The description adds nothing param-specific, 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+resource ('check token-holder discount eligibility') and pins the format ('Google Universal Commerce Protocol (UCP) format'), which is the key axis distinguishing it from the sibling insumer_acp_discount. It never names that sibling directly, so an agent must infer the ACP/UCP split rather than being routed.

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

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

Usage is implied by the UCP format framing, and 'the on-chain check is the same one behind INSR discount codes' hints at its relationship to the discount family. But there is no explicit when-to-use vs insumer_acp_discount, insumer_check_discount, or insumer_validate_code, and no statement of prerequisites for the checkout flow.

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 readOnly, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds genuinely non-annotated context: no authentication required, no credits consumed, and an explicit data-scope guarantee ('Does not expose wallet or token data'), plus the return shape (valid/invalid with reason). This is solid added value beyond the structured fields.

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

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

Three short sentences, front-loaded with the verb+resource and the format, followed by audience, return shape, and constraints. Slight redundancy between 'Validate an INSR-XXXXX discount code' and 'confirm code validity', but no padding overall.

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 one-parameter tool with full schema coverage, complete annotations, and an output schema, the description covers audience, cost, auth, data scope, and return shape — everything needed to call it correctly. The one unresolved item is sibling differentiation against insumer_check_discount, which is a routing concern rather than a completeness gap.

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 pattern '^INSR-[A-Z0-9]{5}$' fully documents the single parameter, so the baseline is 3. The description restates the INSR-XXXXX format but adds no semantics beyond what the schema already encodes (no case handling, no normalization notes).

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 ('Validate an INSR-XXXXX discount code') and specifies the format constraint up front. However, it never distinguishes itself from the sibling tool insumer_check_discount, which sounds functionally identical, so an agent cannot disambiguate the pair from the description alone.

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

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

Provides a usage context ('For merchant backends during ACP/UCP checkout'), which implies when the tool applies. But it gives no explicit when-not guidance and, critically, no routing between this tool and the near-identical sibling insumer_check_discount, leaving the primary selection decision 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 declare the generic profile (not read-only, open-world, non-idempotent, non-destructive). The description adds genuinely non-obvious traits: the returned code is signed and expires in 30 minutes, the result exposes tier and discount percentage but never raw balance amounts, the call consumes one merchant credit, and a Stripe Connect merchant triggers an auto-created coupon.

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 dense sentences, front-loaded with what is created and its format, then cost and side effect. No filler, no restating of the title, and every clause carries information an agent would otherwise have to discover empirically.

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 described, and the description still covers cost, expiry, privacy of the payload and the Stripe side effect. The remaining gap is that it never clarifies the multi-chain wallet parameter choice or whether additional credits/merchant setup are prerequisites for a mutation with no idempotency guarantee.

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 each of the seven wallet parameters and merchantId is already documented in the schema, making 3 the baseline. The description adds no per-parameter meaning: it does not say that only one chain wallet is expected, nor how the wallet family is chosen, so it does not compensate for anything the schema lacks.

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 ('Create a signed discount code') plus the shape and lifetime of the artifact (INSR-XXXXX, 30-minute expiry), which is far more than the title alone. It does not, however, distinguish itself from closely related siblings such as insumer_check_discount, insumer_validate_code, insumer_acp_discount or insumer_ucp_discount, so the agent must infer the boundaries.

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 the operating context ('for a wallet at a merchant') and a cost signal ('consumes 1 merchant credit'), which implies usage. But there is no explicit when-to-use vs. when-not, no mention of the ACP/UCP discount alternatives, and no stated prerequisites such as having merchant credits or a configured merchant.

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

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

The description adds substantial behavioral context beyond annotations: it explains the three verification mechanisms (DNS TXT, HTML meta tag, uploaded file), the state change of marking the domain verified when found, the rate limit of 5 attempts per hour, and the owner-only access requirement.

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 tightly packed sentences with no wasted words. It front-loads the core action before moving to mechanism, rate limit, and access constraints.

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 that an output schema exists, return values need not be described. The description covers the action, mechanism, side effect, rate limit, and access control, leaving no significant gaps for an agent to call 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%, and the single parameter is already documented as 'Merchant ID' in the schema. The description adds little parameter-level detail beyond implying the merchant token belongs to that ID, so 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 states a specific verb (check/verify) and resource (merchant's previously requested domain verification token), clearly distinguishing it from the sibling insumer_request_domain_verification. An agent can immediately tell this is the verification step, not the request step.

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 implies usage context by referring to a 'previously requested domain verification token' and specifies 'Owner only' and a rate limit. It does not explicitly name alternatives or state when not to use it, but the workflow relationship to the request tool 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?

Adds substantial behavior beyond the annotations: credit cost (3/6), that rows for absent chains persist with evaluated=false, that every check is held/not-held and never a balance, that conditionSetVersion must be logged and never used to reject, and that the response carries no score or opinion. This is exactly the kind of operational context annotations cannot express.

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?

Dense but front-loaded: the core purpose leads, optional-wallet semantics follow, then cost and versioning caveats. Nearly every sentence carries unique information, though the block is long enough that a reader must parse carefully.

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, the description covers signing, cost, proof degradation/refund behavior, row evaluation states, and version-logging discipline. For a multi-chain, credit-metered, signed-artifact tool there is no obvious gap an agent would need filled before calling.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining the semantic effect of each optional wallet class (adds a dimension vs. merely lets rows evaluate) and the evaluated=false fallback for unsupplied chains, giving the agent meaning beyond the per-field schema text.

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 ('Generate a signed wallet trust fact profile for an EVM wallet') with a precise scope: curated presence checks organized into named dimensions. It is clearly distinguishable from siblings like insumer_batch_wallet_trust (singular vs batch) and insumer_attest without opening a 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 strong context on when optional wallets matter (Solana/XRPL/Bitcoin/Tron add dimensions; Stellar/Sui only let existing rows evaluate) and notes the audience ('AI agent-to-agent trust decisions'). It does not explicitly name sibling alternatives or state when NOT to use this tool, so it stops short of a 5.

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