Loyal Spark

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

The description adds useful behavioral detail beyond the annotations by disclosing the B20 no-op case and the legacy calldata return shape. With readOnlyHint=false and destructiveHint=false already covering the safety profile, this is helpful but still omits what the caller should do with the returned calldata or any auth requirements.

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 compact clauses are front-loaded and each carries distinct, decision-relevant information. There is no filler or repetition.

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

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

For a one-parameter tool with no output schema, the description covers the key conditional outcomes and return payload for legacy programs plus the B20 no-op. It stops short of explaining how the returned calldata should be used, but it is complete enough for correct tool selection and invocation.

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

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

The schema already fully documents the single token_address parameter at 100% coverage. The description does not add any parameter-level meaning, 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 specific conditional behavior: legacy ERC-20 programs return unpauseUtility and enableMinting calldata, while B20 programs are a no-op. This makes the activation purpose clear, though it does not explicitly distinguish the tool from siblings such as update_program_status or register_loyalty_program.

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

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

It gives clear context by program type: use it for legacy ERC-20 activation and recognize that B20 programs are already active, making the call a no-op. It does not name alternative tools or explicitly state when to prefer them, so it falls short of full selection 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=true, but the description adds genuinely new behavioral facts: the lookup is free (no x402 payment required) and it does not execute the discovered tools — execution belongs to proxy_tool_call. It stops short of describing the shape of the returned rows or pagination limits, which it could since there is no 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?

Three tight sentences with zero waste, front-loaded with what is searched and immediately followed by the cost and execution caveat. Every sentence carries information an agent needs.

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 four-parameter, no-required-arg discovery tool with annotations covering safety, the description is nearly complete: it covers scope, cost, and where execution happens. The remaining gap is the return shape (what a 'row' contains) and the 20-row cap context, neither of which is in an 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%, with each of q, limit, cursor, and network documented in the schema itself (including that cursor is ignored). The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Search Coinbase CDP's Bazaar MCP catalog') plus the result class ('third-party x402-payable tools'). It names the underlying method (search_resources) but never distinguishes itself from the near-identically named sibling bazaar_discover_resources, leaving an ambiguity an agent could easily trip on.

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?

'Read-only, free' and 'Rows are run via the Bazaar MCP server's proxy_tool_call, not here' give a clear next-step route after discovery. However, there is no explicit guidance on when to pick this over bazaar_discover_resources, bazaar_probe_x402, or bazaar_pay_and_call, so the choice among the bazaar_* siblings 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 readOnlyHint=true and destructiveHint=false, and the description's "Read-only" merely restates that. It adds no auth requirements, rate limits, result-set behavior, or pagination semantics beyond what the schema's cursor field already conveys. The parenthetical content-type list is modest added context.

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

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

Three short sentences, front-loaded with the core purpose before the filter guidance. Slight waste in restating "Read-only" already covered by annotations, but nothing verbose or 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 no output schema, the description should say something about the return shape (resource records with name/url/price/network) and that results are cursor-paginated. It covers inputs adequately but leaves the agent guessing about what a result row looks like and how large result sets behave.

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 q, limit, cursor, and network are already fully documented, including the default/max on limit and the cursor provenance. The description names q and network but adds no syntax, matching rules, or interaction details (e.g., whether q and network are ANDed). 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 (Discover) and a well-defined resource (third-party x402-paid resources in Coinbase CDP's Bazaar), with examples of content types that sharpen the scope. It implicitly excludes what bazaar_discover_mcp_servers covers, but never names that sibling, so the 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?

"Filter by free-text q and/or network" gives a workable usage pattern, and "Read-only" signals a safe exploratory call. However, there is no guidance on when to pick this over bazaar_discover_mcp_servers, bazaar_probe_x402, or bazaar_pay_and_call, nor any mention of what to do with results (probe then pay).

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 say readOnlyHint=false and destructiveHint=false; the description adds the important context an agent needs before a money-moving call: host allowlist enforced before any signature, required scope, wallet requirement, and a per-call spend cap with a hard ceiling of 10 USDC. It doesn't state that the payment is final/non-refundable or what happens on a failed settlement, which is the one behavioral gap.

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 that front-load the core action and follow with the refusal rule and prerequisites. The final sentence duplicates schema content on max_usdc, which is the only wasted material.

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 7-parameter payment tool with no output schema, the description covers what an agent most needs: spend limits, auth scope, host restriction and accepted scheme/network. It could still say what is returned after a successful call and how failures surface.

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 url, body, method, headers, max_usdc, allowed_schemes and allowed_networks. The description restates the max_usdc default and hard limit already present in the schema and adds no meaning for the other six parameters — baseline 3 applies.

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

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

States a specific verb and resource: paying an x402 URL through the merchant agent's CDP MPC wallet, with the payment rail (EIP-3009 exact scheme, Base USDC) named. An agent can immediately tell this apart from probe/discover siblings because this one actually spends funds.

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 concrete preconditions: host must be api.loyalspark.online, requires scope 'mint' and an active CDP wallet. What's missing is explicit routing advice versus bazaar_probe_x402 or bazaar_discover_resources (e.g. probe first to learn the price before paying).

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 far beyond the readOnly/destructive annotations: https-only, 5 s timeout, 64 KB cap, no redirects, body never returned on non-402, exact error code not_x402_resource, and rate limits (20/min per IP keyless, key limits otherwise). These are precisely the operational constraints an agent needs before calling.

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 dense paragraph, front-loaded with the core action, then limits, then return/error behavior, then auth and rate limits. Every clause carries a distinct constraint; nothing is repeated from the annotations.

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

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

No output schema exists, and the description compensates fully by specifying what a 402 returns (parsed payment requirements from PAYMENT-REQUIRED header or accepts[]) and what every other status yields. Nothing needed to call or interpret the result is missing.

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

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

Schema coverage is 100% and the single parameter is already documented as a full https:// URL. The description reinforces the https-only constraint and that the target must be an x402-paid endpoint, adding modest but real meaning over the schema.

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

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

States a specific verb and resource ('Probe one x402 resource URL without paying') plus the exact mechanics (single GET). The 'without paying' qualifier implicitly separates it from bazaar_pay_and_call and it reads as a follow-up to bazaar_discover_resources, so an agent can place it in the workflow 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?

Clearly frames the use case (inspect an endpoint's payment requirements before committing to a paid call) and rules out prerequisites ('No signing. No API key needed'). It never names bazaar_pay_and_call explicitly as the escalation path, so the alternative is inferable 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, so safety is covered. The description adds real behavioral detail beyond that: the missing_identifier error_code, that an example and next_action are returned, and that the underlying lookup is an anonymous public GET endpoint — useful auth and failure-mode context.

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

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

Three short sentences, no repetition or filler, and the identity/identifier constraint is front-loaded ahead of the failure mode and endpoint detail.

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 no output schema, the description should hint at what a successful status response contains (valid/expired/redeemed, balance, expiry). It only documents the error path, leaving the success payload shape undefined.

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 each parameter already documents the 'one of code, voucher_code, or voucher_id' rule, so the description's restatement adds little. The error-on-omission note is behavioral rather than parameter semantics, so this lands at the schema-backed baseline.

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

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

States a specific verb+resource ('Check voucher status for this merchant'), which is enough for an agent to separate it from mutation siblings like use_voucher or create_gift_certificate. It stops short of explicitly naming the alternative sibling to use when the goal is redemption rather than status inspection.

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 verb 'check' and the identifier requirement, but there is no explicit when-to-use/when-not-to-use guidance, e.g. status check versus use_voucher. The anyOf identifier rule is stated, which is the only concrete invocation guidance 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?

Goes meaningfully beyond the annotations: it discloses the write to customer_tier_status, the effect on get_token_balance returning 0, and idempotent crediting on a second call, plus EIP-5792 batching where both hashes match. It omits failure/verification-error behavior and permission requirements, keeping it below top marks.

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 dense sentences, front-loaded with the purpose before the conditional behavior; no filler, though the parenthetical clauses make it slightly hard to parse on first read.

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?

A mutation tool with annotations but no output schema; the description covers the state change but says nothing about what a successful confirmation returns or how a failed verification surfaces, which an agent may need to react 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% so the baseline is 3, but the description adds real semantics: recipient_tx_hash becomes relevant only when set or when the fee receipt already carries the recipient mint, and that the same hash is used for batched calls.

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 ('a prepared mint on Base'), plus what is verified (the protocol-fee mint). An agent can distinguish it from mint_loyalty_tokens (prepares) and get_token_balance (consumer of its side effect), though no sibling is named 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?

Implies the call follows a prepared mint and explains the conditional recipient_tx_hash path and the repeated-call case, but never states when to use this versus list_fee_obligations or mark_gift_certificate_minted, nor any when-not 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 only declare readOnlyHint=false and destructiveHint=false, so the description genuinely adds value: it discloses the two-phase lifecycle (create cert now, merchant mints tokens on-chain later) and the customer redemption path via QR or code entry. It does not cover error cases such as an invalid or foreign token_address, nor whether certificates can expire, beyond the expires_in_days schema hint.

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, each carrying distinct information: what is created, how it is redeemed and fulfilled, and when to use it. The core identity and the unique-code detail are front-loaded with no filler.

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

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

With 9 parameters (2 required) fully documented in the schema and no output schema, the description covers the concept and lifecycle well. The remaining gap is that it never says what the caller receives back — presumably the generated codes/QR payloads — which matters for a batch creation tool with no 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 every parameter including quantity ranges (1–100), points_per_dollar override, and max_redemption_percent is already documented. The description adds no parameter-level meaning beyond the code format, so the baseline 3 applies.

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

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

States a specific verb and resource — "Create a gift / welcome certificate (UDS-style) with a unique random redemption code" — and even pins down the code format (LOYAL-XXXX-XXXX-XXXX). The scope is unmistakable versus list_gift_certificates, revoke_gift_certificate, or mint_loyalty_tokens, though no sibling is named 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?

"Use for welcome bonuses, promo campaigns, partnership gifts" gives concrete trigger scenarios, and the redemption flow sentence clarifies when this tool belongs in the workflow (pre-mint). It stops short of stating when NOT to use it or which sibling to pick instead (e.g. create_reward or create_personalized_offer for non-certificate incentives).

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?

While annotations provide basic status, the description adds critical behavioral context regarding the atomic granting of MINT_ROLE to the CDP wallet and explicit extra_minters. This is vital knowledge for an agent performing autonomous deployment.

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 extremely dense with relevant information, front-loading the core purpose and immediately detailing the critical behavioral defaults.

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

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

Given the complexity of deploying standards (B20 vs ERC20) and managing multi-party permissions, the description is very comprehensive in detailing the core technical constraints of the operation.

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?

Although schema coverage is 73%, the description clarifies the operational meaning of key fields like token_standard and the role of extra_minters (atomic minting), providing semantic value beyond what the structure alone offers.

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 is highly specific, clearly stating the tool deploys a new loyalty token on Base via factory calldata. It differentiates its behavior from standard protocols by highlighting the B20 asset standard and atomic role granting.

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 provides clear workflow instructions by distinguishing between the B20 default (single TX, active immediately) and the ERC-20 option, which explicitly requires a 'follow-up transaction' (implying the use of other tools in the workflow).

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

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

Annotations already establish that this is a non-read-only, non-destructive operation. The description adds no behavioral context beyond that: it does not say whether the offer is immediately sent, whether it is idempotent, how bonus tokens or discounts are funded, or what side effects occur.

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, front-loaded with the action and followed by the triggering condition. There is no filler or repetition.

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

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

This is a mutation tool with seven parameters and no output schema. The description does not explain what is returned, whether the offer is delivered to the customer, or how the optional incentive fields interact, leaving meaningful gaps for correct invocation.

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

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

Schema description coverage is 100%, so all seven parameters are documented in the schema itself. The description adds only that the offer targets a specific customer, without clarifying relationships such as whether bonus_tokens and discount_percentage are mutually exclusive or both optional.

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 ('Create a personalized offer') and scopes it to 'a specific customer'. It is clear but does not explicitly distinguish this tool from nearby siblings like create_reward or create_gift_certificate.

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 a clear usage context: 'Use when analytics reveal engagement patterns (e.g., inactive customers, high-value segments).' That is helpful guidance, but it does not name when not to use it or point to alternative tools for adjacent cases.

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 and destructiveHint=false, so the safety profile is known, but the description adds nothing about behavior: no mention of required permissions, whether the reward is immediately active or needs update_reward_status, whether duplicate names are allowed, or whether the operation is idempotent. For a creation mutation with only safety annotations, this is thin.

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 with no wasted words. It is appropriately sized, though its brevity is part of the completeness gap rather than a virtue on its own.

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

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

No output schema exists, and the description says nothing about what is returned (reward ID, status) or which loyalty program/token context the reward attaches to. For a mutation tool with four parameters, the definition leaves the agent under-informed about prerequisites and results.

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 four parameters (cost, name, description, token_address) are already documented in the schema. The description adds no extra semantics such as token address format, valid cost ranges, or whether description is optional. Baseline 3 applies.

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

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

The description states a specific verb and resource ("Create a new reward") and adds the redeemability constraint ("redeemable with loyalty tokens"), which separates it from redeem_reward, list_rewards and update_reward_status. It stops short of naming a sibling explicitly, so it is clear but not strongly differentiated.

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 statement about when to call this versus redeem_reward or create_gift_certificate, nor any prerequisite such as needing an active loyalty program or registered token. Usage is only implied by the verb.

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 and readOnlyHint=false, so the safety profile is carried by structured data. The description adds nothing beyond that: it does not say whether deletion is permanent, whether it requires specific permissions, or what happens if the report is already processed. The opaque 'Internal.' tag conveys no actionable information.

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 with the verb and ownership constraint up front; no padding. The unexplained 'Internal.' prefix is a small waste of the limited space available.

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 destructive tool with annotations covering the safety signal, the definition is minimally adequate. It omits consequences of deletion, permission requirements, and any hint of what 'Internal' restricts, leaving real gaps for a destructive operation.

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

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

With a single parameter at 100% schema description coverage, the schema already documents report_id as the UUID of the report to delete. The description adds no format, ownership, or validation detail beyond that baseline.

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

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

States a specific verb and resource: 'Delete a report'. However, it does not distinguish this from adjacent siblings such as update_report_status, send_report, or list_my_reports, and the leading 'Internal.' is unexplained rather than clarifying.

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

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

The phrase 'a report you submitted' implies an ownership precondition, which is the only usage guidance given. There is no statement on when to delete versus update status or use other report tools, and no mention of confirmation or prerequisites.

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, it discloses important non-obvious behavior: the return is a fee-first calls[] bundle with protocol fee mint before customer mint, calls must be submitted in order, atomic submission is possible via EIP-5792, and unconfirmed fee obligations block future mints. This gives the agent critical workflow and failure-mode context.

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

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

The description is dense but front-loaded, starting with the core purpose and redemption behavior, then moving to return shape, submission order, confirmation, and blocking consequences. Every sentence carries operational information with no filler.

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

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

For a complex minting workflow with no output schema, the description explains the important return structure and next steps: calls[] ordering, atomic submission, and confirm_mint_fee parameters. It could be slightly clearer about where obligation_id comes from in the returned bundle, but it is largely complete 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 meaningful interaction semantics: redemption reduces the payable receipt amount before new cashback is calculated. It does not add much beyond the schema for token_address, customer_address, or cashback_rate, but the redemption interaction is valuable.

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: calculate and mint loyalty tokens from purchase amount and cashback rate, with optional redemption of existing points. It also distinguishes the operation by tying it to purchase checkout/cashback calculation rather than generic token minting.

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

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

It gives clear operational context: use points_to_redeem or redeem_all to reduce the payable receipt amount before calculating new cashback, then submit the returned calls in order and confirm via confirm_mint_fee. It does not explicitly compare this tool against siblings such as mint_loyalty_tokens, so it lacks full alternative-selection 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=true and destructiveHint=false, so the safety profile is covered. The description adds value by listing what comes back (wallet addresses, voucher stats, balances, tier info), but says nothing about export volume, pagination, rate limits, or any auth/sensitivity requirements for bulk customer address data — the kind of context that matters for an export.

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

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

Three short sentences, front-loaded with the action and scope, then the return contents, then the use case. No filler, though the trailing 'analytics, segmentation, personalized offers' list is somewhat generic boilerplate rather than actionable guidance.

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 read-only export with a fully-covered schema and no output schema, the description covers action, scope, and the shape of returned data. The only meaningful gap is behavior at scale (pagination/limits) and the absence of any sibling disambiguation, which keeps it from being fully complete.

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 there is a single required parameter, so the schema already does the work. The description only implies that 'token_address' identifies the loyalty program ('for a specific loyalty program') and adds no format, validation, or lookup-hint detail beyond that. Baseline 3 is correct.

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 with scope: 'Export customer data for a specific loyalty program', and enumerates the payload (wallet addresses, voucher stats, balances, tier info). Clear on its own, but it never contrasts itself with a close sibling like get_program_analytics, so the agent must infer the boundary between customer-level export and program-level analytics.

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

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

'Use for analytics, segmentation, and personalized offers' gives implied usage context, but does not say when NOT to use it or name an alternative (e.g. get_program_analytics for aggregate metrics, create_personalized_offer for the follow-up action). The agent gets a use case, not a routing rule.

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

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

Annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description does contribute one genuinely useful trait: the output is 'non-binding examples' and a planner, i.e. nothing is applied server-side and agents must supply name/symbol/economics themselves. It stops short of explaining what 'field catalog' or 'next_actions' actually contain.

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 with no padding, which is good, but the first is a noun-list fragment ('field catalog, required parameters, next_actions, and non-binding examples') that front-loads jargon rather than the tool's action. Brevity here costs clarity rather than earning 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 six undocumented optional parameters, no output schema, and no annotations beyond the read-only hints, the description should explain what the inputs influence and roughly what comes back. It gives neither, leaving an agent unable to predict whether passing category or business_name changes the returned defaults.

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 six parameters (locale, category, description, business_name, preferred_style, target_audience) have 0% schema description coverage, so the description carries the full burden and explains none of them. The only parameter-adjacent signal is that name, symbol, and economics are *not* accepted here, which is marginal and slightly at odds with the presence of business_name.

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 label 'Workflow planner' plus a list of return contents ('field catalog, required parameters, next_actions, examples') implies it returns scaffolding for setting up a program, but there is no verb+resource statement of what the tool actually does. An agent must infer from the name alone that it 'generates defaults'; the description never says it produces or returns anything.

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

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

No when-to-use, no prerequisites, and no reference to the obvious siblings such as create_loyalty_program, get_program_workflow_status, or register_loyalty_program. The clause 'External agents must choose their own name, symbol, and economics' is a constraint on what the tool will not supply, not guidance on when to call 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral fact — that the target is resolved from the caller's authentication rather than a parameter — but says nothing about auth requirements, failure modes, or the shape of the returned profile.

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 clause with zero filler, sized appropriately for a zero-argument read tool. Nothing is buried or redundant.

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

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

For a trivial zero-param read with annotations covering safety, this is close to sufficient, but with no output schema the description could have indicated what the profile includes (identity, wallet, program membership) so the agent knows whether calling it will answer its question.

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 no parameter semantics to explain; the baseline of 4 applies. The description correctly implies no input is needed because identity comes from the session.

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... profile', with the qualifier 'authenticated agent's' narrowing scope to the caller. No sibling tool in the list deals with profiles, so no additional differentiation is needed, but it stops short of describing what the profile contains.

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 context, prerequisites, or mention of alternatives. An agent must infer from the name alone that this is the way to retrieve its own identity/account details rather than another agent's.

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 destructiveHint=false, so the safety profile is covered. The description contributes one behaviorally relevant fact — that the data pertains to the protocol on Base L2 — which helps the agent interpret results, but says nothing about response shape, caching, or freshness. With annotations carrying safety, this modest added context merits a 3.

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 short sentence with the resource front-loaded after the verb; nothing extraneous. It is under-specified rather than padded, so it is efficient if not maximally informative.

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?

There is no output schema and no parameter list to lean on, so the description is the only place an agent could learn what this returns — yet it never says. For a zero-argument read tool with no return documentation, the description leaves the most important question (what will I get back?) unanswered.

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 and no schema gap to compensate for. Baseline for a parameterless tool is 4.

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

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

States a verb (get) and a resource (Loyal Spark protocol on Base L2), so the agent knows the general subject. But 'info' is unspecified — it does not say whether this is configuration, contract addresses, chain metadata, or version data. No sibling is named or implicitly excluded, though the scope is distinct enough from siblings like get_my_profile.

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

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

No guidance on when to call this versus other read tools such as get_my_profile, get_program_analytics, or get_token_balance. The agent must infer usage from the name alone; there are no prerequisites, no exclusion conditions, and no alternative tools mentioned.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that the description adds nothing: no indication of the metric set, time window, aggregation level, or response shape for an analytics call with no 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?

One short sentence with no redundancy, so nothing is wasted, but the terseness comes at the cost of substance rather than being efficient. It is under-specified rather than lean.

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 an analytics tool with no output schema, the description should say what the agent will receive (metrics, totals, time series). Instead it leaves the return value entirely unknown, which is a significant completeness gap for a query whose value is the data returned.

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 fully documented as a token contract address. The phrase 'one of your loyalty programs' lightly implies token_address selects the program, but adds no format or selection guidance beyond the schema. 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?

It names a verb and resource ('Get analytics for ... loyalty programs'), which is better than a tautology, but 'analytics' is undefined and the description does nothing to separate it from siblings like get_program_workflow_status or list_loyalty_programs. An agent cannot tell what data this actually retrieves.

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 statement of when to use this tool, no prerequisites, and no named alternative. 'One of your loyalty programs' hints that a program must exist, but nothing routes the agent between this and adjacent status/list 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 declare this is read-only and non-destructive. The description adds useful context by naming the returned fields and clarifying that the caller must supply parameter values for next_actions, which helps set execution expectations.

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 with no wasted words. The parenthetical is compact and clarifies an important behavioral detail without bloating the description.

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

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

For a read-only tool with no output schema and one optional parameter, the description is adequate but thin. It names the returned fields but does not explain their structure, conditions, or how next_actions should be interpreted.

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 only parameter is already documented as an optional token to inspect. The description does not add meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific purpose: explaining the next merchant action and returning current_step, required fields, and ordered next_actions. It is clearer than a generic status tool, though it does not explicitly contrast itself with siblings like update_program_status.

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 'next merchant action,' suggesting it should be called when the merchant needs workflow guidance. However, there is no explicit when-to-use or when-not-to-use guidance relative to siblings such as update_program_status or generate_program_defaults.

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 destructiveHint=false, so the safety profile is covered. The description adds that it returns balance and tier info and that either a wallet address or email identifies the customer, which is useful, but says nothing about behavior for unknown customers, error cases, or whether results are live versus cached.

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 with the resource and return content before the parenthetical detail. The parenthetical is slightly clunky but nothing is wasted.

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

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

For a read-only, two-parameter tool with no output schema, the description adequately covers input shape and hints at the return content ('balance and tier info'). Only marginal gaps remain around error behavior and result freshness.

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 both parameters are documented in the schema, so the schema does the heavy lifting. The description restates the dual identifier option for customer_address but adds no semantics for token_address beyond what the schema already states.

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 loyalty token balance and tier info for a customer'), which is clearly distinct from siblings like mint_loyalty_tokens or transfer_loyalty_tokens. It stops short of naming a sibling alternative, but the purpose is unambiguous.

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

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

Usage is implied by the domain (a read lookup of a customer's balance), but there is no explicit when-to-use, no prerequisites, and no guidance on choosing between this and related tools such as list_loyalty_programs or get_my_profile.

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 destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: unpaid rows include a next_action field describing the follow-up POST /mint/confirm call. It doesn't cover pagination or row fields beyond next_action, preventing 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 front-loaded sentences with no filler: purpose first, then the status alias, then the row-level next_action detail. Every sentence 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?

No output schema exists, so the description must convey return behavior; it usefully notes that rows can carry next_action, but says nothing about pagination, ordering, or what other fields a row contains. Adequate for a simple read-only list tool but not complete.

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

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

Schema coverage is 100%, so the schema already documents the status parameter. The description goes further by explaining that 'unpaid' is an alias for 'pending', which the schema does not, and this prevents an agent from treating them as distinct states.

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 with scope: 'List protocol-fee obligations for this API key'. An agent can tell it apart from list_mints or confirm_mint_fee. It does not explicitly name a sibling, so it stops short of a 5.

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

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

Usage is implied by the status values and the hint that unpaid rows carry next_action pointing at POST /mint/confirm. However there is no explicit when-to-use/when-not or a named alternative such as confirm_mint_fee for acting on those obligations.

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 readOnlyHint=true and destructiveHint=false annotations already establish the safety profile. The description adds that results include status and redemption info, a small amount of context, but says nothing about pagination, ordering, or default result size.

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 efficient sentence, front-loaded with the verb and resource and with no wasted words.

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

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

Read-only tool with all three parameters documented and an annotation covering safety; the description usefully notes that output contains status and redemption info, partly compensating for the absent output schema. Only minor gaps around pagination and ordering remain.

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 limit, status, and token_address are fully documented in the schema. The description's 'with status' refers to returned data rather than the filter parameter, so it adds no meaning beyond the schema; 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 ('List') and resource ('gift certificates') with an ownership scope ('issued by the agent's merchant'), and it hints at included fields (status, redemption info). It is clearly distinct from create_gift_certificate and revoke_gift_certificate, though it does not explicitly contrast with list-style siblings.

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

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

Usage is implied by the filters and the ownership scope, but the description gives no explicit when-to-use or when-not guidance and names no alternatives (e.g., check_voucher_status for single-certificate lookup).

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 destructiveHint=false, so the safety profile is covered. The description adds useful scoping context ('owned by the agent's merchant'), but does not describe pagination, ordering, or return shape.

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

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

The description is a single front-loaded sentence with no wasted words. It communicates the core operation and scope immediately.

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

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

For a simple read-only list tool with one optional, fully documented parameter and safety annotations, the description is largely sufficient. It could mention default inclusion behavior for expired programs or pagination, but those are minor gaps.

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 sole optional parameter is already documented in the schema. The description does not add syntax, defaults, or behavioral detail for include_expired, so the schema carries the parameter 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 and resource ('List loyalty programs') and adds ownership scope ('owned by the agent's merchant'), making it clear what is returned. It does not explicitly distinguish itself from siblings such as create_loyalty_program or list_rewards, but the purpose is unambiguous.

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

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

Gives no explicit guidance on when to use this tool versus related siblings, nor any when-not conditions. The listing intent is implied by the verb, but alternatives like list_rewards or get_program_analytics are not addressed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that – no pagination behavior, default limit, ordering, or result shape – and its 'active' qualifier slightly tensions with the schema's status filter. Adequate but thin given annotations carry the load.

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 short sentence with the resource and scope front-loaded; nothing is padded. It is arguably too terse rather than too long, and 'active' is the one word that could mislead.

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

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

For a read-only, zero-required-parameter list tool with full schema coverage and no output schema, the essentials are present. Missing are default limit, whether results are paginated or sorted, and how 'active' relates to the status filter – gaps an agent would need to fill by trial.

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 each of the three parameters is documented inline (limit range, status values, token_address semantics), so the schema does the heavy lifting. The description contributes no additional parameter meaning beyond the domain context, which matches the 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 ('List ... offers on the marketplace') so an agent can tell it enumerates marketplace offers rather than anything else. It does not differentiate itself from the many other list_* siblings (list_rewards, list_mints, list_gift_certificates), though the domain noun 'marketplace offers' is distinctive enough.

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 guidance on when to call this versus alternatives, no prerequisites, and no exclusions. The word 'active' implies scoping, but the schema's status parameter allows completed/cancelled, leaving the caller to guess whether this tool really returns only active offers.

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 this is a non-destructive read operation, and the description adds useful behavioral context: pending means transaction_hash is null and the recipient has not been credited, completed means the mint was recorded, and /balance remains 0 until confirm. This is meaningful state semantics beyond the annotations, though it does not cover auth or return-shape 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?

The purpose is front-loaded in the first sentence, followed by compact status definitions and one balance note. The description is short, structured, and every sentence contributes useful interpretation.

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

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

For a read-only list tool with 100% schema coverage and annotations covering safety, the description gives enough context to understand pending versus completed mints. It does not describe the return shape or pagination, which is a minor gap given there is no 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 coverage is 100%, so the baseline would be 3, but the description adds real meaning to the status filter by defining pending and completed in transactional terms. The optional token_address parameter is left to the schema, so this is not a 5.

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

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

The description states a specific verb and resource: it lists mint intents scoped to the merchant. It is clearly distinguishable from action-oriented siblings like mint_loyalty_tokens and balance-oriented siblings like get_token_balance, though it does not explicitly name alternatives.

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 usage by explaining what pending and completed mean and that GET /balance stays 0 until confirm, which helps an agent interpret results. However, it does not explicitly say when to choose this tool over siblings or mention any when-not conditions.

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 destructiveHint=false, so the safety profile is covered. The description adds useful scope (agent-submitted only) and enumerates the status values, but says nothing about pagination, ordering, or what an empty result means.

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 terse sentences with the scope qualifier front-loaded and no redundant prose. The 'Internal.' fragment is unclear rather than wasteful, a minor blemish on an otherwise efficient definition.

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

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

For a simple, parameterless-required read tool with a fully documented schema and explicit read-only annotations, the description covers ownership scope and status filtering adequately. Return shape details are not strictly needed absent an output schema, though result ordering remains 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 coverage is 100%, so both the limit range (1-50, default 20) and the allowed status values are already documented in structured fields. The description repeats the status values but adds no format or usage detail beyond the schema, 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?

The description uses a specific verb (List) and resource (reports) and adds a scoping qualifier — only reports this agent submitted — which separates it from delete_report, send_report, and update_report_status. The leading 'Internal.' is cryptic but the core purpose is unambiguous.

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

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

Usage is only implied: an agent can infer this is for viewing its own submitted reports, and the sibling names suggest delete/send/update are the mutating counterparts. No explicit when-to-use or when-not-to-use statement is given.

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 destructiveHint=false, so the safety profile is covered. The description adds that each reward carries redemption counters including a last-30-day window, which is useful behavioral context, but says nothing about pagination, caps, or ordering on what could be a long list.

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: the action and its scope come first, the payload description second. Nothing is redundant or 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?

For a single-parameter read with annotations present and no output schema, the description covers both the input scope and the shape of the returned metrics, which is what an agent needs to decide and call. Missing only list-size/pagination expectations.

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 the single parameter, so the schema already explains that token_address is an 0x... contract address. The description adds only the framing that the address selects a loyalty program's rewards, which is marginal beyond structured data.

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 rewards'), the scoping key ('by token_address'), and what the response contains (redemption metrics per reward). This clearly separates it from sibling mutations such as create_reward, redeem_reward, and update_reward_status.

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

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

The phrase 'by token_address' implies the tool is scoped to one loyalty program, but the description never says when to reach for this versus list_loyalty_programs or get_program_analytics, and gives no exclusions or prerequisites. Usage is inferable 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 and destructiveHint=false, so the safety profile is covered. The description adds the scope that the result includes point-spend configuration alongside discount codes, which is useful context beyond the annotations. It does not disclose pagination, auth requirements, or return shape, so it adds value but not rich behavioral detail.

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 with zero waste, front-loading the main resource and appending the secondary point-spend dimension. Every phrase 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?

Given a simple read-only list tool with one fully documented optional parameter and no output schema, the description is nearly complete. The only gaps are return format and pagination behavior, which are minor for a list operation whose safety is covered by 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%; the token_address parameter is fully documented in the schema, including the 'omit to list every linked store' semantics. The description adds no parameter-level 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?

The description states a specific verb (list) and resource (discount codes) and adds the secondary resource of point-spend methods (online code, register voucher, both). It is clear what the tool returns, but it doesn't differentiate itself from siblings like update_store_discount_code or list_rewards, 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 no explicit guidance on when to use this tool versus alternatives. The sibling update_store_discount_code is the mutation counterpart, and list_rewards covers a different resource; the agent must infer the boundary. The only condition implied is 'for this merchant's Shopify store,' which is context, not usage direction.

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 and destructiveHint=false, so the write nature is already flagged. The description adds useful behavior beyond that: it updates status from pending_mint to redeemed and persists the mint transaction hash. It does not mention permissions, idempotency, or edge cases.

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 efficient sentence, front-loading the prerequisite ('After the merchant submits...') before the action and state transition. No wasted words.

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

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

For a simple two-parameter state-transition mutation with full schema coverage and safety annotations, the description is sufficient to invoke correctly. Minor omissions like idempotency behavior or failure modes keep it from being fully complete.

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 are already documented in the schema. The description reinforces that the certificate is claimed and the transaction hash is the mint tx hash, but it adds little syntax or meaning beyond the schema.

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

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

The description gives a specific verb and resource: 'mark it as minted' for a claimed gift certificate. It also states the exact state transition (pending_mint -> redeemed), which clearly distinguishes this from siblings like confirm_mint_fee or list_mints.

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 trigger is explicit: call this 'after the merchant submits the on-chain mint transaction for a claimed gift certificate.' That gives clear usage context, though it does not name alternatives or state when not to use the 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?

The description discloses behavior well beyond the annotations: the protocol fee is charged in the merchant's own loyalty tokens rather than USDC, the fee mint must be first, both calls must be submitted in order, and unconfirmed fee obligations have downstream consequences. It also explains automatic wallet resolution from customer email, which is critical operational context.

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

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

The description is dense but front-loaded: it states the action and returned bundle first, then ordering, submission strategy, confirmation step, and recipient handling. Every sentence contributes operational information needed to invoke the tool correctly.

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 multi-step blockchain mint with no output schema, the description explains the returned calls[] structure, required ordering, atomic submission option, follow-up confirmation tool, and the consequence of leaving a fee obligation unconfirmed. That is sufficient context for an agent to complete the intended workflow 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 schema already documents recipient_address, recipient_email, recipient, token_address, and amount. The description reinforces that recipient_address accepts a 0x Base address or customer email and resolves automatically, but that meaning is already present in the schema, so this is a baseline case rather than meaningful added parameter guidance.

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 ('Record mint intent') and immediately clarifies that this tool returns a fee-first calls[] bundle rather than executing the mint directly. It also explicitly names the follow-up sibling confirm_mint_fee, so an agent can distinguish this preparation step from the confirmation step without inspecting other tools.

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

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

It gives clear when-to-use guidance: submit both calls in order, atomically via EIP-5792 send_calls when supported, then call confirm_mint_fee with specific fields. It also names the alternative confirmation path (POST /agent-api/mint/confirm) and warns that unconfirmed fee obligations block future mints, which is actionable exclusion/ordering 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=false and destructiveHint=false, so the write/no-destroy profile is covered; the description adds that a voucher is created and that the transaction must be verified. It does not disclose what happens if the transaction hash is invalid or already used, whether the call is idempotent, or what permissions are required. Useful but incomplete behavioral context for a mutation.

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, no filler, with the required input front-loaded ahead of the side effect. Every clause carries information the agent needs.

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?

There is no output schema, so the agent must infer the return value (presumably a voucher identifier) from 'Creates a voucher for the customer'. Failure modes, idempotency, and post-redemption state are unaddressed. Adequate for a 3-parameter mutation but not complete.

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 parameters are already documented in the schema. The description reinforces the meaning of transaction_hash as a verified onchain transfer from customer to merchant, but adds no syntax, format, or validation detail beyond the schema. Baseline 3 applies.

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

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

The description gives a specific verb ('Redeem') and resource ('a reward'), and adds the distinguishing mechanism: a verified token transfer transaction hash. This separates it from sibling tools such as use_voucher or update_reward_status, though it does not explicitly name those alternatives. The second sentence clarifies the outcome (voucher creation), making the action unambiguous.

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

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

The description implies the prerequisite of a verified token transfer and indicates the result is a voucher, which hints at when to use it. However, it never states when not to use it, nor does it distinguish this redemption path from related sibling flows like check_voucher_status, use_voucher, or update_reward_status. Usage must be inferred.

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

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

Annotations only state readOnlyHint=false and destructiveHint=false, so the description usefully adds the real side effect: B20 tokens land in 'active' while legacy ERC-20 land 'inactive' pending activation. It does not cover prerequisites such as ownership of the token or duplicate-registration behavior, but the status-outcome disclosure is genuine value 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?

Two dense sentences with no filler: the action is stated first, the conditional status behavior second. Nothing could be removed without losing 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 7-parameter mutation with no output schema, the description covers the core action and the status outcome, but omits error/duplicate handling and required authorization over the token address. Adequate for a well-documented schema but incomplete for an agent that needs to know failure modes.

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; every parameter including defaults for cashback_rate, points_per_dollar, expiration_days and token_standard is already documented in the schema. The description contributes only the conditional consequence of token_standard ('b20' active vs 'erc20' inactive), adding marginal meaning beyond that baseline.

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

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

The description names a specific verb and resource ('Register a deployed token as a loyalty program in the database') and the second sentence clarifies the active/inactive outcome by token standard. It never names create_loyalty_program or activate_loyalty_program, so an agent must infer the boundary between 'register an existing deployed token' and 'create a program'.

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 'deployed token' (use this when a contract already exists) and 'activate next' hints that activate_loyalty_program is the follow-up step for legacy ERC-20s. No explicit when-to-use/when-not guidance or named alternatives are given, leaving selection against create_loyalty_program 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 destructiveHint=true and readOnlyHint=false; the description adds the concrete state machine (active -> revoked), the authorization requirement, and eligibility exclusions. It does not say whether revocation is reversible or what happens to an already-revoked certificate, but it adds real context 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?

Two tight sentences: the state transition is front-loaded, followed by the authorization and eligibility constraints. Nothing is redundant or 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?

For a single-parameter mutation with no output schema, the description covers the state change, who may invoke it, and which certificates are ineligible. It omits idempotency/error behavior for non-active certificates and whether the action is reversible, which is a modest 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% and the single parameter already documents that certificate_id is a UUID from create_gift_certificate / list_gift_certificates. The description adds no format, sourcing, or edge-case detail beyond the schema, 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?

The description states a specific verb ('Revoke'), resource ('gift certificate'), and the exact state transition (active -> revoked). Combined with the precondition about minted/redeemed certificates, an agent can distinguish this from mark_gift_certificate_minted or list_gift_certificates without opening another schema.

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

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

It gives explicit when-not conditions ('Already-redeemed/minted certificates cannot be revoked') and a permission constraint ('Only the issuing merchant can revoke'). It stops short of naming the alternative sibling to use when revocation isn't permitted, but the usage envelope is clear.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds useful context about where the report lands (the Agent Reports dashboard) but does not say what the call returns, whether duplicate reports are created, or any auth/ownership requirements. Some added value beyond annotations, but not 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?

Two short sentences with the destination and content scope front-loaded; 'Not a loyalty action' efficiently rules out a whole category of misuse. Slightly terse phrasing ('Internal.') sacrifices a little clarity for compactness but no sentence is wasted.

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

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

With 4 required parameters, no output schema, and only generic annotations, the description covers the purpose but leaves the agent without a return-value expectation (e.g., a report ID) or mention of what the created report looks like in list_my_reports. Adequate for invocation, incomplete for a write tool whose result the agent may need to reference later.

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 required fields like agent_role and report_type are already fully documented and the description adds nothing new about them. The parenthetical content examples loosely map to the report_type values but duplicate rather than extend the schema. Baseline 3 is appropriate when the schema carries parameter meaning.

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?

Names a specific verb ('send') and a specific destination ('the merchant's Agent Reports dashboard'), plus examples of content types (SEO audits, growth ideas, anomalies, weekly summaries). This clearly separates it from siblings like list_my_reports, delete_report, and update_report_status, though it never names those siblings directly.

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?

'Internal.' and 'Not a loyalty action.' set a general boundary, implying the tool is for the agent's own reporting rather than customer-facing loyalty flows. However, there is no explicit when-to-use versus list_my_reports/update_report_status, and no stated prerequisites or conditions that would select this tool over a sibling.

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

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

Annotations indicate a non-read-only, non-destructive mutation, so the safety profile is partly covered. The description adds useful context about what the channel controls (checkout code, register voucher, or shopper choice), but it omits auth requirements, idempotency, and whether changing the setting affects existing vouchers or checkout codes.

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 with no wasted text. The parenthetical clarifications for each mode are compact and directly useful.

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 setter with annotations covering the mutation safety profile and no output schema, the description supplies the key channel semantics needed to call it correctly. It does leave minor operational gaps around prerequisites and effects on existing settings, but the low complexity keeps it broadly complete.

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

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

There is only one parameter and schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that online means a checkout code, offline means a voucher at the register, and both means the shopper chooses.

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: 'Set how this store's customers spend loyalty points', and names the available channel modes. It is clear what setting the tool controls, though it does not explicitly contrast with nearby program-configuration siblings.

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

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

Usage is implied by the setting's scope, but the description gives no explicit when-to-use guidance, prerequisites, or alternatives such as update_program_config. An agent can infer that this is the store-level channel setter, but the routing is not spelled out.

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

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

With annotations present, the description adds useful context by clarifying that the tool returns calldata rather than executing the transfer. However, it does not state whether the caller must sign and send the transaction, what chain is involved, or other operational requirements.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core action and output.

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

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

Given the tool has no output schema, the description should do more to explain the calldata return format and execution flow. It is sufficient to identify the tool's basic purpose but leaves gaps around how the calldata should be used and whether the caller's wallet is the source.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds only the phrase 'between wallets', which does not clarify the missing sender parameter or token units beyond what the schema provides.

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

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

The description states a specific verb ('Get') and resource ('calldata') for transferring loyalty tokens between wallets. It is clear what the tool produces, though it does not explicitly distinguish itself from siblings like mint_loyalty_tokens or get_token_balance.

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

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

There is no explicit guidance on when to use this tool versus alternatives. It implies transferring tokens, but does not mention when not to use it, prerequisites, or related 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 declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive mutation and the description's 'update default' phrasing is consistent. However, it doesn't disclose whether changes affect already-issued earn events, permission/auth requirements, or reversibility—context an agent would want for a config mutation.

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 mutation target and its effect with zero filler. Nothing extraneous.

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 mutation tool with no output schema, the description covers what changes but omits what the response returns, whether other settings remain untouched (schema implies via omission), and any activation/permission prerequisites. Adequate but with clear gaps given no 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 coverage is 100%, so both parameters (cashback_rate, points_per_dollar) and their ranges are already fully documented in the schema. The description only echoes the parameter names and adds the slider analogy, which conveys intent but not new semantics beyond the schema.

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

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

The description names a specific verb and resource ('Update default cashback_rate and/or points_per_dollar for a program') and clarifies the effect with the merchant-dashboard-slider analogy. It's clear what changes, though it doesn't differentiate itself from siblings like create_loyalty_program or generate_program_defaults.

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

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

No guidance on when to use this versus alternatives such as generate_program_defaults or create_loyalty_program, nor preconditions like program ownership or activation state. The agent must infer usage context entirely.

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 this is a non-read-only, non-destructive mutation. The description adds that it is a database persistence step following an onchain activation or pause, which is useful context, but it does not describe side effects, authorization needs, or status transition rules.

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

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

The description is a single front-loaded sentence with zero waste. It conveys the action and timing context immediately.

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

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

For a simple two-parameter mutation with full schema coverage and annotations, the description is largely complete. It identifies the operation and its onchain-event context, though it could clarify the relationship to sibling activation tools and any status transition constraints.

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 required parameters are already documented in the schema. The description adds no additional parameter details such as token address format or status transition constraints, making 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?

The description states a specific verb and resource: it updates a program's status in the database. That is clear enough to distinguish it from update_program_config, which handles configuration rather than status, though it does not explicitly name sibling tools.

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

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

The phrase 'after onchain activation/pause' gives a timing context for when to use the tool, but the description does not explicitly say when not to use it or which sibling to choose instead, such as activate_loyalty_program.

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=false and destructiveHint=false, so the safety profile is covered. The description adds a real ownership/authorization constraint ("a report you submitted") but does not say whether transitions are reversible, whether 'done' is terminal, or what happens if the report is already in the target state.

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 with the scope flag ("Internal.") front-loaded and zero filler. Sizing is appropriate for a trivial two-parameter mutation.

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

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

For a simple two-required-parameter tool with full schema coverage and no output schema, the description is minimally sufficient. However, it omits transition rules (idempotency, terminality of 'done', failure modes) that an agent needs to call this mutation reliably.

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 the allowed status values are already documented in the schema, making the description's restatement of 'reviewed or done' redundant. The only added semantic value is the ownership constraint on report_id.

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 (set), resource (report status), and the exact target states (reviewed or done), which clearly separates it from siblings like update_reward_status, update_program_status, or send_report. It lacks explicit sibling naming, 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?

"Internal." plus "a report you submitted" implies the usage context and ownership precondition, but there is no explicit when-to-use guidance relative to send_report, delete_report, or list_my_reports. The agent must infer the workflow position.

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 this is a non-destructive mutation, and the toggle described is consistent with that. The description adds no further behavior: nothing about idempotency, permissions, or what happens to already-redeemed or in-flight redemptions when a reward is deactivated.

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 with the action front-loaded. 'Based on analytics' is a slightly vague justification clause, but overall there is no wasted text.

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

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

For a two-parameter status toggle with full schema documentation and annotation-covered safety, the description is nearly sufficient. Only the side effects of deactivating a reward are 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 coverage is 100% and both parameters are documented in the schema (is_active semantics, reward_id as UUID). The description adds no format, constraint, or edge-case detail beyond that, so the baseline 3 applies.

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

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

States a specific verb pair (activate/deactivate) plus the resource (a reward in the catalog), which separates it cleanly from create_reward, list_rewards and redeem_reward. It does not explicitly name those siblings, but the action is unambiguous.

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

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

'Use to manage reward availability based on analytics' implies the intent but gives no concrete when/when-not conditions and never contrasts the tool with redeem_reward or create_reward. The agent must infer that this only toggles status rather than performing redemption.

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`, so the agent knows this mutates state. The description adds genuinely useful side-effect context that annotations cannot convey: cancelling returns loyalty points. However, it doesn't state that 'use' is irreversible, whether both actions are idempotent, or what happens if the code has already been redeemed — gaps that matter for a destructive two-mode operation.

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, front-loaded with the two actions the tool performs. The trailing sentence ('Same actions as the merchant discount-code journal') is the weakest part — it references an external concept without explaining it, spending words that could have carried real behavioral detail.

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 two required parameters, 100% schema coverage, and destructive annotations present, the definition is largely serviceable. But for a destructive, two-mode operation with no output schema, the description should say what happens on success or failure for each action and confirm that the same `redemption_id` applies to both 'use' and 'cancel'.

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 `action` documented as 'use or cancel' and `redemption_id` pointing to `list_store_discount_codes`, so the baseline is 3. The description adds no parameter detail beyond what the schema already supplies.

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

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

The description names a specific verb-plus-resource pair ('mark a Shopify discount code used, or cancel it') and enumerates the two supported actions, which map directly onto the `action` parameter. It is clear what state changes are possible, though it doesn't distinguish itself from siblings like `use_voucher` or `redeem_reward`, which could plausibly be confused with it.

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

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

There is no explicit statement of when to pick this tool over alternatives. The only routing information is one sentence naming another tool as the source of IDs ('Id from list_store_discount_codes' in the schema), plus a vague reference to 'the merchant discount-code journal' that assumes knowledge the agent may not have. No when-not-to-use conditions are given.

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, so irreversibility is signaled structurally. The description adds concrete behavioral detail the annotations do not: the tool returns error_code missing_identifier plus an example when neither identifier is supplied. It does not explain post-use consequences (e.g., whether status can be reversed), 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 action and followed by the identifier constraint. Minimal waste, though the trailing 'and an example' is a slightly vague phrase.

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

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

For a simple two-parameter mutation with full schema coverage and annotations covering safety, the description gives the action, the identifier rule, and the failure behavior — enough to call it correctly. Only post-redemption semantics are absent.

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

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

Schema coverage is 100% — both properties document their format and the OR relationship — so the schema already does the heavy lifting. The description's restatement of the anyOf constraint adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Mark a voucher as used at the merchant'), which precisely identifies the operation. It does not differentiate itself from sibling tools such as check_voucher_status or redeem_reward, but the action itself is unambiguous.

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

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

The phrase 'at the merchant' implies the redemption context, but there is no explicit when-to-use guidance and no mention of alternatives like check_voucher_status (to verify before using) or redeem_reward. The 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.