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

Annotations already declare destructiveHint=true, so destructiveness is known; the description reinforces it with 'Cannot be undone,' which is useful confirmation. It does not disclose the notable dry-run behavior of the confirm parameter (live-environment preview), although that is documented in the schema, nor what happens to balances or pending transactions on the card.

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 zero waste; the core action and its irreversible nature are front-loaded before the usage example.

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?

Adequate for a two-parameter destructive tool: schema fully documents parameters and annotations cover the safety profile. However, for an irreversible workflow-ending operation, the description never states the close/suspend distinction or the consequences for the card's remaining funds and transactions.

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 paymentCardId and the confirm dry-run semantics are already documented in structured data. The description adds no parameter meaning of its own, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Permanently close a card') plus the irreversibility qualifier, which implicitly separates it from the sibling suspend_payment_card. It does not name that sibling outright, so the differentiation requires the agent to infer it from 'permanently'.

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

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

Provides one usage cue ('when the agent's workflow is finished') but no explicit when-not condition and no named alternative. The most likely confusion, close vs. suspend, is left for the agent to resolve from sibling names alone.

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 annotation already declares this is a safe read, so the bar is lower. The description adds genuine value by disclosing the response shape (ledger balances plus payment cards), but it says nothing about behavior on an unknown ID, whether the card list is truncated or paginated, 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?

One sentence, zero filler, and the most important information (the resource being looked up) is front-loaded. Nothing could be removed without losing meaning.

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 one-parameter read with no output schema, the description covers purpose and the notable return contents, which compensates for the absent output schema. Minor gaps remain around not-found behavior and whether the embedded card collection is bounded, but nothing essential to invoking 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?

There is a single required parameter with 100% schema description coverage, so the schema already documents financialAccountId as a Highnote financial account ID. The description adds no format, prefix, or sourcing guidance beyond that, which is the expected baseline-3 case when the schema carries the 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 ("look up") and resource ("a financial account") and even enumerates what the result contains: ledger balances and issued payment cards. It is clearly a read operation, distinguishing it from mutation siblings like issue_virtual_card or close_payment_card, but it never differentiates itself from the retrieval sibling get_payment_card.

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

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

Usage is only implied: the description tells you it looks up an account, so an agent can infer it should be called when account-level balances or attached cards are needed. There is no explicit when-not guidance, no mention of get_payment_card or list_account_activity as alternatives, and no stated 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description adds genuinely useful context with the field enumeration and the explicit guarantee that the card number is never returned, which is the kind of security-relevant detail an agent cannot get from annotations. It does not mention error behavior for an unknown or expired card ID.

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 filler; the returned-field list comes first and the non-disclosure guarantee follows. Every clause carries information an agent would act on.

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

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

For a single-parameter read-only lookup with full schema coverage, the description covers purpose, scope of returned data, and the key data-protection boundary. The only meaningful omission is what happens on a missing or invalid card ID.

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 is documented in-schema as a Highnote payment card ID, so the baseline is 3. The description adds no further meaning about the ID's format, source, or behavior when invalid.

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?

"Look up a payment card" gives a specific verb and resource, and the field list (status, last 4, network, form factor, expiration) makes clear what the call returns. It implicitly separates itself from mutating siblings like suspend_payment_card or close_payment_card, but never names or contrasts them explicitly.

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

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

There is no when-to-use or when-not-to-use guidance, no mention of prerequisites (e.g., needing a valid card ID from another call), and no reference to alternatives among the many sibling card tools. Usage must be inferred entirely from the word "look up".

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 idempotentHint and destructiveHint=false, and the description adds real context beyond them: the card is created 'active' (immediately usable), and guardrails should be applied first, implying real spend risk. It does not mention the confirm/dry-run gate or the 365-day default, both of which live only 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?

Two sentences, zero waste, with the core action front-loaded and the workflow recommendation following. Every clause earns its place.

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

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

For a state-changing financial tool with no output schema, the description never says what an agent gets back (e.g., a card ID needed for the follow-up set_transaction_limit call) nor references the live-environment confirm gate. Annotations cover idempotency and non-destructiveness, so this is adequate but with clear gaps for chaining calls.

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 including confirm, idempotencyKey, and expiresInDays. The description only adds a loose mapping for externalId ('one card per agent, workflow or vendor') and adds no new semantics for required financialAccountId; 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 ('Issue a new active virtual card on a financial account') plus the intended granularity ('one card per agent, workflow or vendor'). An agent can distinguish this from sibling tools like get_payment_card, suspend_payment_card, or simulate_authorization without inspecting schemas.

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

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

Gives explicit sequencing guidance: pair with set_transaction_limit and restrict_merchant_categories 'before using it', which names siblings and orders the workflow. It lacks a when-not-to-use clause (e.g., reuse an existing card vs. issuing a new one, or test vs. live mode) but the positive guidance is concrete.

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 genuinely new behavioral context beyond that: results are ordered newest first and each entry carries merchant, amount and card. It does not discuss result windowing, how far back 'recent' reaches, or error behavior when the account ID is unknown, which keeps it off 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?

A single sentence, front-loaded with the verb and resource, that also packs in ordering and payload contents. Every clause earns its place and nothing is repeated from the schema or 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?

For a simple two-parameter read tool with no output schema, the description carries the important return-value information (newest first, merchant/amount/card fields) that would otherwise be missing. The remaining gap is minor: no statement of how far back activity extends or what an empty result means.

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 both financialAccountId and limit (including its 1-100 bounds and default of 20) fully documented in the schema. The description references the account implicitly but adds no meaning beyond that. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description pairs a specific verb ('List') with a specific resource ('recent activity on a financial account') and adds scope detail: 'newest first', and the activity types 'authorizations and clearings with merchant, amount and card'. That is far more informative than the title alone. It stops short of naming a sibling to distinguish itself from, so a 4 rather than 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 only implied: the tool is evidently for inspecting recent transactions on a known account, and the required financialAccountId makes that context obvious. There is no explicit when-to-use, when-not-to-use, or pointer to a sibling such as get_financial_account for account metadata. Minimum viable rather than instructive.

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?

No annotations are supplied, so the description carries the full burden. It does disclose the useful behavioral fact that the call both creates a rule and attaches it to a card, but it omits whether an existing rule is replaced or appended, whether allowed and blocked may be combined, permission requirements, and idempotency behavior.

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

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

A single front-loaded sentence with the action, the two list modes, the identifier formats, and the attachment target. There is no redundant restatement of the tool name or the 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?

For a 7-parameter mutation tool with no annotations and no output schema, one sentence leaves meaningful gaps: replacement-vs-additive semantics, mutual exclusivity of allow/block lists, and any confirmation of what the call returns. The dry-run behavior is only covered by the schema's confirm description, so the definition is workable but thin overall.

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 86%, so the baseline is 3; the description pushes it higher by framing the two parallel parameter families ('by Highnote MerchantCategory name or MCC'), which tells the agent that allowed/blocked and allowedMcc/blockedMcc are alternate encodings of the same concept. It still says nothing about whether allowed and blocked are mutually exclusive or how conflicting entries are resolved.

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+resource ('Create a merchant category spend rule') plus the compound effect ('attach it to a card'), and it pins the domain to merchant categories by name or MCC. That is clearly distinguishable from sibling spend-control tools such as set_transaction_limit (amount limits) or simulate_authorization (a test, not a rule).

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 it is used when a card needs category-level allow/block rules, but the description never states when to choose this over set_transaction_limit, nor that it should be paired with simulate_authorization to validate the outcome. There are no explicit exclusions or prerequisites (e.g., live-environment confirmation is only discoverable in the schema).

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?

No annotations exist, so the description carries the full burden; it does disclose that this is a mutation that creates a rule and attaches it to a card, that subsequent authorizations over the limit are declined, and that a server-side cap rejects oversized limits. It omits whether an existing limit rule is replaced or duplicated, what permissions are needed, whether the rule can be later removed, and it never mentions the confirm-gated dry-run behavior that the schema flags as important in the live environment.

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 functional outcome is front-loaded before the server-side constraint. Nothing repeats the title or the 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?

For a four-parameter mutation with no annotations and no output schema, the description covers the core effect and one server constraint but leaves the mutation's blast radius vague: no statement about replacement vs. additive behavior, no mention of the confirm dry-run mode, and no hint of what is returned. Adequate to invoke correctly, thin for invoking safely.

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 are already documented and the baseline is 3. The description adds the 500.00 USD ceiling, which is genuinely useful, but it phrases it in major currency units while maximumAmount is declared in minor units, so it creates a conversion ambiguity rather than resolving one.

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 ('Create an amount-limit spend rule') and states the observable effect ('attach it to a card, so any single authorization above the limit is declined'), which is far more than a restatement of the name. It does not explicitly distinguish itself from the closest sibling, restrict_merchant_categories, which is another spend-rule creation path, so it falls one step 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 effect statement: an agent can infer this is the tool for capping per-authorization spend. It gives no guidance on when to prefer it over restrict_merchant_categories or how it relates to simulate_authorization for testing, and the 500.00 USD ceiling is stated as a hard fact rather than as a precondition the caller should check before invoking.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that this runs in the test environment and is a simulation, but it does not say what side effects occur, whether an authorization record is created, what permissions are required, or how approval versus decline is returned.

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 well-formed sentence with the core action and environment front-loaded. The example use case is compact and every clause earns its place.

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

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

For a four-parameter simulation tool with no annotations and no output schema, the description explains purpose and a test scenario but omits what the simulation returns and what side effects it has. It is adequate to start an invocation but not complete for predicting the outcome of approval or decline.

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 75%, with meaningful field descriptions for amount, paymentCardId, and merchantCategory. The description adds no parameter-level meaning beyond the schema and does not document merchantName, so the schema does most of the work.

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: 'Simulate a card authorization in the Highnote test environment.' It also adds a concrete example use case, checking spend rules, so an agent can identify the tool's function quickly. It does not explicitly differentiate itself from sibling card-management tools, which keeps it from a 5.

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

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

The description gives clear usage context by naming the test environment and explaining the example scenario: testing whether spend rules decline as expected. It does not specify when not to use the tool or name alternatives among the siblings, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the safety burden alone; it does disclose the two most important traits — new authorizations are declined and the action is reversible. It says nothing about authentication requirements, rate limits, what happens to already-authorized or pending transactions, or the dry-run gating that the schema implies via 'confirm'.

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

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

Two short sentences, zero filler, and the effect statement is front-loaded ahead of the reversibility note. Every clause 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 two-parameter mutation tool with no annotations and no output schema, the description covers the essential facts: what changes, what the user-visible consequence is, and that it can be undone. Remaining gaps (permissions, treatment of in-flight authorizations) are secondary but real.

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 paymentCardId and the confirm/live-environment behavior are already documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the work.

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 ('Temporarily suspend a card') plus the concrete effect ('new authorizations are declined'), which implicitly separates it from the permanent-close sibling. It stops short of naming close_payment_card explicitly, so the distinction must be inferred from the word 'Temporarily' and 'Reversible'.

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 adverb 'Temporarily' and the note that the action is reversible imply when to pick this over an irreversible close, but no alternative tool is named and no precondition is stated. An agent gets the general context but must infer the when-not case on its own.

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