Authoryze

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

Annotations only cover readOnlyHint, and the description goes well beyond it: it discloses the tool never issues/draws/reveals a card, describes the retrievable-flag lifecycle (single-use card drawn or not), and states polling safety. This is exactly the kind of behavioral context annotations cannot carry.

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

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

Front-loaded with the core purpose, then layered with operational detail; every sentence carries information about the card lifecycle or polling. Slightly long, but each clause earns its place rather than padding.

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

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

With no output schema, the description compensates fully by enumerating return fields (status, denial reason, retrievable boolean, review_url) and their interpretation. Nothing an agent needs to call and interpret this tool 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 request_id parameter is already documented as 'returned by request_purchase'. The description adds no syntax, format, or provenance beyond what the schema provides, 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+resource ('Check the current status of a purchase request') and immediately distinguishes itself from sibling retrieve_card by explaining the retrievable/drawn relationship. An agent can tell exactly what this tool returns and what it does not do.

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 instructs when to call retrieve_card ('ONCE when you are ready to pay'), when to start a new purchase, how to handle the pending_review review_url, and notes it is safe to poll. It names the sibling and the condition that selects 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 only declare readOnlyHint=true, so the description carries most of the burden. It goes well beyond that: it explains the semantics of per-agent fields, the cross-agent user_aggregate caps, team-level ceilings, and threshold overrides. It also notes 'Only configured limits appear in the response,' clarifying absence behavior. This is rich behavioral context not derivable from 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?

Front-loaded with the core purpose, then systematically explains the response structure. It's information-dense without obvious filler, though the list of per-agent fields is slightly repetitive. Overall efficient and well-organized.

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 input parameters and no output schema, the description must explain what the response contains and what it means. It does so thoroughly: it covers per-agent fields, cross-agent aggregates, team-level limits, threshold overrides, and the condition for their appearance. This is complete for an agent to interpret the output 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?

Zero parameters, so baseline is 4 per the rules. The description details the meaning of response fields and nested objects (user_aggregate, team), which compensates for the lack of an output schema and adds value beyond what the empty input schema provides. No penalty since there are no parameters to document.

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: 'Get current spending vs. configured limits.' This clearly distinguishes it from siblings like request_purchase and retrieve_card, though it doesn't explicitly name those alternatives. 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?

Implied usage as a read-only informational tool, but no explicit when-to-use guidance or alternatives. An agent can infer it's for checking spending, but the description doesn't say e.g. 'use before request_purchase to verify capacity' or when not to use it.

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

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

Annotations only declare destructiveHint=true, so the description carries the rest and does so thoroughly: the four outcome states including which failures are recoverable vs. require account-owner action, the near-duplicate escalation behavior, and the atomic idempotency guarantee against double-charging. This is exactly the extra behavioral context the annotation can't express.

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

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

Front-loaded with purpose and return states, then retry semantics — a sensible order with no filler sentences. It is on the long side and the idempotency guidance partially restates the schema's own idempotency_key description, which costs a point.

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?

Nine parameters with no output schema, so the description must explain return values — and it does, enumerating approved/pending_review/denied/failed and the retry-safety contract. Nothing an agent needs to invoke this tool 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 description coverage is 100%, so the baseline is 3, but the description adds operative meaning about idempotency_key that goes beyond its schema text: reuse the same key across retries, fresh key only for a distinct purchase, and that the key is the only fully atomic protection against concurrent double-submits. No added detail on merchant_country_code or amount limits, keeping it below 5.

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

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

States a specific verb+resource ('Submit a purchase request') and immediately enumerates the possible outcomes. It also implicitly routes the agent by naming check_status as the polling target after a pending_review escalation, which separates it from the read-only siblings (check_status, get_spending_summary, retrieve_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?

Explicitly says when to retry (same idempotency_key on timeout/error), when NOT to retry (duplicate escalation to pending_review — poll check_status instead), and when to use a fresh key (genuinely new purchase). Alternatives and exclusions are both covered.

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 give destructiveHint=true, so the description carries the behavioral load and does so richly: irreversibility, single-display of card details, no re-draw (second call returns already_retrieved), null-field handling, and AVS billing-address semantics. This is well beyond what the annotation provides and consistent with 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?

Dense but front-loaded: the exactly-once rule and immediacy of storing details come first, followed by return fields and billing/AVS guidance. Length is justified by genuinely non-obvious constraints, though a few clauses (e.g., the shipping-address aside) run long.

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, yet the description enumerates the returned fields (card number, expiry, CVC, cardholder_name, billing_address components) and how to use them. Combined with the usage and irreversibility rules, an agent has everything needed to call and consume the result 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% and there is a single required parameter, so the schema already documents request_id fully. The description references the approved request but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (draw/return) and resource (single-use virtual card) scoped to an APPROVED purchase request. It clearly separates itself from check_status by naming it for status polling, so an agent can distinguish it from siblings without opening 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?

Explicit when-to-use ('only when you are ready to pay'), when-not ('do NOT call this speculatively, to poll status (use check_status for that), or more than once'), and the alternative for the pre-approval case. The exactly-once constraint and the not-yet-approved path are both spelled out.

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