earnrate

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

Annotations only say it is a non-destructive, non-idempotent write; the description goes further by disclosing the implicit side effect of creating a wallet when none exists, the shape of the reply (what the card still needs), and a data-storage guarantee (product id and settings only, never card numbers). That is real context an agent could not infer from structured fields.

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

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

Three sentences, front-loaded with the action and scope, then the required follow-up behavior, then the safety note. Nothing is repeated from annotations or schema, and every sentence carries a distinct obligation.

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

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

An output schema exists so return values need not be spelled out, yet the description still flags the actionable part of the reply, and the wallet-creation side effect plus the one required parameter cover everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by tying the shortfall categories in the reply to the picks/activated fields and by reinforcing that cardId must come from search_cards. It does not explain the trickier params (bonus, anniversary, checkoutLabel), which the schema already handles.

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 (adds) plus resource (a card the user holds) plus target (their wallet) and the source of the identifier (search_cards). That is enough to separate it from search_cards, update_card, remove_card, list_wallet and import_wallet without opening any 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?

Names the prerequisite path (id comes from search_cards) and tells the agent what to do after the call: prompt the user about category picks, memberships and activations. It stops short of an explicit exclusion naming update_card or import_wallet as the alternative when a card already exists or when adding in bulk.

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 read-only annotations, the description discloses rich behavioral details: it returns `decision.cardId`, `decision.checkoutLabel`, ranked cards with reasons, cards the merchant won't accept, assumptions, warnings, and valuation sensitivity. It also states a privacy constraint ('Never needs or returns card numbers'). This is substantial context an agent could not infer from the annotations alone.

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

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

The description is front-loaded with the core question and then efficiently covers the two modes and return behavior. It is dense but every sentence carries information, though a few long clauses make it slightly harder to scan quickly.

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 presence of an output schema and clear read-only annotations, the description still adds enough context about modes, return values, and privacy behavior to fully support correct invocation. Nothing critical is missing for an agent to use the tool confidently.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description adds meaning specifically for the `cards` parameter, explaining that omitting it falls back to the saved wallet or, with neither, produces an answer covering every known card. This clarifies the parameter's role and fallback logic beyond the schema, though other parameters rely mainly on their schema descriptions.

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

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

The description states a specific verb and resource: 'Which card earns the most rewards for a purchase, and why.' It also clarifies the two operating modes (all cards vs. user's own cards), which helps distinguish its role. However, it does not explicitly name or contrast itself with the sibling tool `best_cards_for` (plural), so an agent could still be unsure when to choose this over that batch variant.

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 usage context: when no cards are provided and no wallet exists, it ranks every known card; when cards are named or a wallet is saved, it picks from the user's set. This tells the agent how to invoke it in different scenarios, but it does not explicitly state when to use an alternative sibling or when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds the substantive assumption behind the ranking — every card is modeled at its best (correct category pick, activated, cap unused) — which materially affects how results should be read. It also tells the agent to surface annual fee and conditions, though it does not discuss result limits or ordering depth.

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

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

Dense but front-loaded: what it ranks, the modeling assumption, the examples, the sibling exclusion. The closing sentence "Mention the annual fee and any conditions" partly repeats the earlier "with its annual fee", so one clause is mildly 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?

A 10-parameter, zero-required tool with an output schema and full schema descriptions — the description supplies the missing behavioral context (assumption of optimal setup, no wallet needed, sibling routing) that structured fields cannot. Only the shape of the ranked result set (count, tie handling) is left implicit.

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

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

Schema coverage is 100% with rich enum descriptions, so the schema carries parameter meaning. The description adds only indirectly ("one purchase or category", "needs no wallet" implying all params optional) and gives no extra guidance on how merchant vs category or valuation interact in practice.

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

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

States a specific verb and resource ("Ranks every card earnrate knows ... for one purchase or category") and immediately scopes it as not only the user's cards. That phrase alone separates it cleanly from best_card_for_purchase and list_wallet without opening any schema.

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

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

Gives concrete trigger examples ("what's the best card for groceries?", "which card should I get for Amazon?") and an explicit exclusion routing the agent to best_card_for_purchase when the question is about the user's own wallet. It also notes no wallet is required, removing a precondition an agent might otherwise assume.

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 openWorldHint=false, and the description adds useful behavioral context about scope selection, fee/condition notes, and how saved caps/picks/activations are treated. It does not cover every operational detail, but with annotations this is strong supplementary 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?

The description is front-loaded with the core purpose and then covers scope cases efficiently. It is slightly dense and includes an odd closing instruction ('Pass on the notes'), but overall every sentence contributes.

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

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

With an output schema, read-only annotations, and fully described parameters, the description supplies enough behavioral context for correct invocation. It could say a bit more about date and memberships, but those are handled by the schema.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description adds some meaning for the cards/no-cards/wallet distinction, but does not explain date or memberships beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb-like outcome—the card to use for each everyday purchase category—and names the resource scope. It explicitly distinguishes itself from best_card_for_purchase for single-store queries, so an agent can tell when this tool is the right one.

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

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

Gives explicit branching conditions: no cards and no saved wallet means all known cards; cards named or saved wallet means the user's own cards; one specific store means use best_card_for_purchase instead. These are clear when-to-use and alternative-tool instructions.

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

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

Annotations already cover safety (readOnlyHint, openWorldHint=false), and the description adds real behavioral context beyond them: coverage limits ('only the cards earnrate knows'), per-user variance, the presence of issuer eligibility rules in each offer's note with an instruction to pass those caveats on, and the exclusion of spending-based value. That's substantive disclosure for a read-only ranking tool.

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

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

Four tight sentences, front-loaded with the ranking definition, then when to use it, then the caveats. Every clause carries information; nothing repeats the name or schema.

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

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

Given an output schema exists and annotations cover the safety profile, the description fills the remaining gaps an agent needs: coverage scope, per-user variability, note semantics for eligibility rules, and the value-model limitation. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema itself (kind enum, cards/picks/activated, includeHeld, noAnnualFee). The description reinforces the 'user's point values' and 'cards the user doesn't have' concepts but adds no parameter-level detail like how includeHeld interacts with the default wallet behavior. Baseline 3 is appropriate.

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

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

States the specific verb (ranks), the resource (public welcome/sign-up offers), the population (cards the user doesn't have), and the exact ranking formula (bonus at user's point values minus first-year fee). This is far more precise than siblings like best_cards_for or simulate_spending, so an agent can route correctly without opening the schema.

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

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

Explicitly names the triggering user questions ('which new card to get' or 'which has the best sign-up bonus'). It also sets boundaries by stating what it doesn't do (card earning on the user's spending), which implicitly points to siblings like simulate_spending or best_card_for_purchase.

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 idempotentHint=true, but the description adds non-obvious behavior: the deletion is permanent, it signs out every app using the wallet, and user confirmation is required beforehand. Those side effects are not derivable from the annotations and materially change how an agent should invoke it.

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

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

Two sentences, front-loaded with what happens, followed by the gating condition and fallback. No sentence is filler and the destructive consequence is stated before the procedural rules.

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

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

For a zero-param, irreversible tool with an output schema and full annotation coverage, the description supplies the remaining needed context: irreversibility, cross-app sign-out, confirmation, and the export alternative. Nothing an agent needs to call it safely is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The empty schema is consistent with a whole-wallet deletion that targets the saved wallet implicitly.

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 (deletes the saved wallet) plus its two consequences: permanence and signing out every app using it. That scope wording implicitly separates it from remove_card (single card) and export_wallet, though it never names those siblings explicitly.

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

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

Gives an explicit precondition ('Only when the user asks to delete it'), a procedural requirement ('confirm first'), and a named alternative ('offer export_wallet to keep a copy'). An agent knows exactly when to call it and what to do instead.

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 openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: the exact serialization format (wallet.yaml), the specific data classes included, and a privacy guarantee ('Never card numbers') that an agent could not infer from structured fields.

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

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

A single compact sentence with the artifact front-loaded before the contents list, and the security caveat placed last for emphasis. It is a sentence fragment, but nothing is wasted and no sentence is filler.

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

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

For a zero-parameter, read-only tool with an output schema, the description covers what an agent needs to select it. Minor gaps remain — where the file is written and whether it overwrites an existing wallet.yaml — but these are secondary given the output schema and annotations.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly adds nothing extraneous about inputs and instead spends its words on output content.

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 action and artifact: exports the saved wallet as a wallet.yaml file. It also enumerates the exported contents (card ids, picks, activations, memberships, cap usage, bonus progress), which makes the resource concrete. It doesn't explicitly distinguish itself from list_wallet or import_wallet, so sibling differentiation relies on the name.

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

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

Usage is only implied: naming 'the earnrate command line and earnrate.dev' as consumers hints at when you'd export (to move data into those tools). There is no explicit when-to-use/when-not, and no mention of list_wallet as the read-only alternative or import_wallet as the inverse operation.

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

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

The description adds meaningful context beyond annotations by saying the saved wallet is replaced, that only wallet files are accepted, and that user confirmation is needed if cards already exist. The destructive and idempotent traits are already covered by annotations, and the description is consistent with them.

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

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

The description is three tightly written sentences with the core action front-loaded, followed by input constraints and the confirmation rule. Every sentence adds useful operational guidance without 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 single-parameter import tool with an output schema and rich annotations, the description supplies the necessary purpose, usage conditions, destructive confirmation behavior, and input restrictions. Nothing important for correct invocation appears missing.

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

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

Schema coverage is 100%, so the yaml parameter is already documented structurally. The description adds semantic constraints by specifying that the YAML comes from the earnrate command line or earnrate.dev and must be wallet files only, not statements or card numbers.

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 action and resource: replacing the saved wallet with a wallet.yaml file. It also constrains the input to wallet files, which distinguishes it from tools that handle individual cards or statements, though it does not explicitly name sibling 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?

It gives clear usage conditions: when the user pastes or attaches a wallet.yaml, and warns never to use it for statements or card numbers. It also instructs confirmation when cards are already saved. Alternatives such as add_card or list_wallet are not explicitly named, keeping it below a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The one piece of added behavioral value is the mention that each card reports when its data was last verified, signalling staleness; there is no ordering, pagination, or 'what happens if the wallet is empty' 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?

One front-loaded sentence with the verb first and the field list after, no filler. The list of eight included data points is long but each item conveys distinct content the caller would otherwise have to infer from the output schema.

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

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

No parameters, safety annotations present, and an output schema exists, so the description need not explain return values. It nevertheless confirms scope and freshness metadata, making it sufficient; only the lack of sibling routing keeps it from the top.

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. Baseline 4 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?

A specific verb and resource ('Lists the user's cards') with an enumeration of the wallet fields returned, so the agent knows this is a full wallet snapshot. It never distinguishes itself from siblings like search_cards or cheat_sheet, but the scope (all cards, all fields) 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?

No explicit when-to-use or when-not statement and no named alternative. The field enumeration implies the intended use (when the agent needs caps, rewards value, welcome-bonus progress, or data freshness for all cards at once), but that inference is left to the reader.

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

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

Adds real behavioral context beyond the annotations: it writes to the user's saved wallet, double-invocation double-counts spend (consistent with idempotentHint=false), and it explicitly discloses the no-op case where nothing is written. That no-op disclosure is exactly the kind of information annotations cannot convey.

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

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

Four short sentences, front-loaded with purpose and effect, then constraints, then the edge case. Every sentence earns its place, though the no-op sentence could arguably be folded into the constraint sentence.

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

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

With an output schema present and full schema coverage, the description only needs to cover behavior — and it does: mutation target, idempotency risk, and the write-free acknowledgment path are all stated.

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

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

Schema description coverage is 100%, including detailed enum documentation for category and the channel default behavior, so the schema does the heavy lifting. The description adds no parameter-level detail of its own, making the baseline 3 the correct score.

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 ('Records a purchase the user has already made') plus the downstream effect on spending caps and welcome-bonus progress. The 'already made' framing separates it cleanly from simulate_spending-style tools without needing to name them.

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

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

Gives explicit timing ('only after the purchase has happened') and an explicit anti-pattern ('only once per purchase: calling it twice counts the spend twice'). It stops short of naming a sibling alternative such as simulate_spending or best_card_for_purchase for the pre-purchase case, so it is strong but not fully routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description earns credit by naming the collateral damage beyond the card record itself: tracked cap usage and bonus progress are removed too, which an agent could not infer from the 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?

Two sentences, zero filler. The action and its data consequences come first, and the invocation condition follows, which is the right front-loading for a destructive tool.

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

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

With one fully documented parameter, an output schema, and annotations covering destructiveness and idempotency, the description supplies what is missing. It could say whether removal is reversible or requires confirmation, but nothing essential to correct invocation is absent.

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

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

Schema coverage is 100% and the single cardId parameter is fully documented in the schema, including where to source it (search_cards). The description adds no parameter-level meaning, 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 ('Removes a card from the wallet') plus the collateral scope ('with its tracked cap usage and bonus progress'), so the agent knows exactly what is deleted. It does not explicitly differentiate itself from siblings like delete_wallet or update_card, leaving the agent to infer the boundary.

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?

'Only when the user says they no longer have it or don't want it considered' gives a clear gating condition for invocation and implicitly excludes speculative removal. It stops short of naming an alternative tool (e.g., update_card) for the case where the card should be kept but corrected.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: it discloses that results carry a confidence value and a provenance field (curated data, Claude, or nowhere), telling the agent the tool can legitimately return an unresolved answer rather than failing. It does not discuss error handling or cost/latency.

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

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

Two sentences, zero filler, and the high-value content (what comes back) is front-loaded before the usage hint. Nothing is repeated from the title or schema.

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

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

With an output schema present and read-only annotations, the description needn't enumerate return fields in depth, and the provenance/confidence mention covers the one behavior an agent must anticipate. A brief note on unknown-merchant behavior beyond provenance would make it 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 the enum parameters are richly documented in the schema itself (including when to omit `channel` and when `category` is ignored). The description adds no parameter-level information, so baseline 3 applies.

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

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

States a specific verb (identify/resolve) and resource (merchant) and enumerates exactly what the result contains: spend category, likely MCC, accepted card networks, confidence, and provenance. It's clearly a lookup/explanation tool, distinguishable from wallet-mutation and card-search siblings, though it never names a sibling 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?

"Use it to explain or double-check a recommendation" gives one concrete usage context, implicitly pointing at best_card_for_purchase/best_cards_for. But there are no exclusions (e.g. when to just call best_card_for_purchase instead) and no guidance on when resolution is unnecessary.

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 openWorldHint=false, so safety is covered; the description nevertheless adds real context beyond them: the result payload (id, network, annual fee, wallet membership, required setup like category picks, memberships, activations) and the hard constraint that the catalog is US-only. It does not discuss result volume or pagination, which matters for an unfiltered "list every card" call.

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

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

Three sentences, front-loaded with the verb and catalog scope, then examples, then the return shape, then the empty-query rule. No hedging or filler; every clause carries either routing or payload 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?

Complete for a one-parameter read tool: an output schema exists so return values need not be spelled out (the brief summary is a bonus), annotations carry the safety profile, and the description still contributes catalog scope, example queries, and the list-all behavior. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the format of the single query parameter is already documented, and the description's examples plus "as the user said it" overlap with that. The one genuine addition is that omitting the query returns the full catalog, which the schema cannot express; otherwise the schema does the heavy lifting.

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

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

States a specific verb and resource ("Finds credit cards in earnrate's catalog") and scopes the matching keys (name or issuer) with three concrete example queries. It also implicitly separates itself from list_wallet by noting results carry "whether it's already in the wallet," and marks the boundary of the catalog with "US cards only."

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

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

Explicitly covers the no-argument case: "Leave the query out to list every card," which is the main branching decision for a single optional parameter. It also routes forward by tagging the returned id as "for add_card." It stops short of naming when to prefer a sibling like list_wallet or best_cards_for over this, so no explicit exclusion is 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 destructiveHint=true and idempotentHint=true; the description adds the specific destructive mechanism (full-list replacement, not append/merge), which annotations alone don't convey. It stops short of saying what happens to cards whose required membership is dropped, or how unknown values are handled, but the main risk is disclosed.

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

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

Two sentences, zero filler. The purpose comes first and the replacement warning follows immediately, so the most consequential instruction is front-loaded rather than buried.

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

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

With an output schema present and a single fully-described enum parameter, the description needn't explain return values. It covers purpose and replacement semantics well; only edge behavior (invalid values, effect on dependent card rate calculations) is left unstated, which is a modest gap for this complexity.

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

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

Schema coverage is 100% and the enum plus its description already enumerate the allowed values, so baseline is 3. The description adds genuine meaning beyond the schema by explaining what a membership does (unlocks elevated card rates) and tying an example value to a concrete card benefit, which helps the agent populate the array correctly.

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 ('sets') and resource ('memberships') and immediately grounds it in effect: memberships that unlock some cards' rates, with two concrete examples (amazon-prime for Prime Visa's 5%, BofA Preferred Rewards tier). No sibling tool touches memberships, so the scope 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?

Explicitly warns that the call replaces the whole list and instructs the agent to include the ones to keep — a critical precondition that prevents accidental data loss. It does not name alternatives, but no sibling overlaps with this resource, so the omission costs little.

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

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

Adds real behavioral context beyond the readOnlyHint/openWorldHint annotations: default household spending with the answer self-reporting that default, ranking based on rewards minus annual fees, and the exclusion of welcome bonuses. It does not explicitly state that nothing is persisted, though the schema's "without saving anything" phrasing partially covers that; the annotations already establish the non-mutating 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?

Front-loaded with the core action and only five sentences, none wasted. The third sentence is dense, packing the two ranking modes and the wallet fallback into one clause, which costs a little readability.

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

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

For a 9-parameter tool with no required params, an output schema, and full annotation coverage, the description covers the decision-critical parts: mode selection, spending defaults, and scoring basis. Filter parameters (kind, issuer, business, memberships, noAnnualFee, valuation) are left entirely to the schema, which documents them fully, so nothing essential 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?

With 100% schema description coverage the baseline is 3, but the description adds precedence semantics the schema does not: `cards` takes priority, compareToWallet is the saved-wallet alternative, and neither means the full catalog. `spending` optionality and the default-spending fallback are also explained here rather than in the schema.

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

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

Opens with a specific verb and resource: spends a year of monthly amounts across every card in the database and ranks single cards and two-card pairs by rewards minus annual fees. That scope (whole-catalog, pair-aware, fee-adjusted) is distinguishable at a glance from siblings like best_cards_for or best_card_for_purchase, which answer narrower queries.

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

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

Explicitly names the user questions this answers ("which card fits my spending?" / "is it worth adding a card?") and spells out the two mode switches: `cards` for cards named in conversation versus compareToWallet for the saved wallet, falling back to all known cards. It also tells the agent that `spending` is optional and that typical household amounts are used (and disclosed) when omitted.

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 disclose that this is a non-read-only, destructive, idempotent, non-open-world operation, so the description does not need to restate those safety traits. It adds useful behavior beyond annotations and schema by explaining that current-period picks are merged with saved picks. It does not explain replacement semantics for activated categories or bonus-tracking behavior, but those are documented in the 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?

The description is three compact sentences with the main action front-loaded. Each sentence contributes useful information: editable settings, merge behavior, and a concrete use case.

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 complex six-parameter tool with nested objects, annotations, and an output schema, the description covers the central update behavior and the important merge semantics for picks. It is not fully complete because it omits the bonus parameter from its field list and does not mention replacement behavior for activated categories, but the rich schema and annotations compensate for much of that.

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

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

Schema description coverage is 100%, so the baseline is 3 even without extra parameter guidance in the description. The description adds merge semantics for picks and mentions checkout label, anniversary, and activated categories, but it omits the bonus parameter entirely. The schema carries most of the 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?

The description states a specific verb and resource: it changes settings on a card already in the wallet. It names multiple editable settings and distinguishes itself from add_card by specifying that the card is already in the wallet. The omission of the bonus parameter from the field list is a minor completeness issue, not a purpose-clarity failure.

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 an explicit use case: use it when the user picks new categories, such as quarterly category selection. It does not name when not to use it or route to sibling alternatives such as remove_card or add_card, but the usage context is clear.

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