Authoryze

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

Beyond the readOnlyHint annotation, the description explains the meaning of the retrievable boolean and the status values, and clarifies that it never issues, draws, or reveals a card. This adds significant behavioral context.

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

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

The description is a bit verbose but well-structured, covering all necessary aspects without unnecessary fluff. It is front-loaded with the primary purpose and then details conditions.

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 status-checking tool, the description covers all essential aspects: what it does, what the returned boolean means, how to proceed, and when polling is safe. It is complete for the given 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?

The request_id parameter is described as 'The request_id returned by request_purchase', which links it to a sibling tool and provides context. Since schema coverage is 100%, the description adds value beyond the bare schema.

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

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

The description clearly states the tool checks the current status of a purchase request, which is distinct from sibling tools like retrieve_card (which retrieves the card) and get_spending_summary (which shows spending).

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 explicitly instructs to call retrieve_card once when approved and retrievable is true, and notes it is safe to poll while pending. This gives clear when-to-use guidance and directs to the appropriate sibling.

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

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

Annotations only declare readOnlyHint=true; the description adds valuable behavioral context: only configured limits appear, the optional user_aggregate object covers account-wide caps, and those caps can deny a purchase even when per-agent rules are not exceeded. This goes well beyond the annotation and clarifies how the read-only result should be interpreted.

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, with the main purpose front-loaded and each subsequent sentence adding meaningful detail about response behavior. No filler or repetition of annotation/structured data.

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 carries the responsibility of explaining the response. It names the relevant fields, distinguishes per-agent from account-wide limits, and notes the conditional presence of limits. This is sufficient for an agent to correctly invoke and interpret the result.

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 has zero parameters, so there is no parameter semantics burden for the description to carry. The description instead explains the meaning of the response fields and the optional user_aggregate object, which is appropriate given the empty schema.

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

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

The description uses a specific verb and resource ('Get current spending vs. configured limits') and lists the exact fields returned. It is clearly distinct from siblings like request_purchase (a mutation) and retrieve_card (card data), so an agent can tell what this tool is for 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?

The description provides clear context about what the tool returns and explains the per-agent versus cross-agent distinction, making its purpose obvious. It does not explicitly state when not to use it or name alternatives, but with only zero parameters and clearly distinct siblings, the implied usage is strong.

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

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

Annotations declare destructiveHint=true, so the mutation is known, but the description goes much further. It discloses the exact return states (approved, pending_review, denied with reason, failed), explains the duplicate-detection behavior (escalated to pending_review rather than auto-approved), and details idempotency guarantees for retries (no double card or fee). It also surfaces a specific failure mode (missing Privacy.com key) and its remedy. This is exceptional transparency beyond what annotations provide.

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

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

The description is a single dense paragraph but is well-structured: it opens with the core action, then covers return values, retry safety, duplicate handling, and idempotency guidance in logical order. Every sentence adds necessary information for correct invocation and error recovery. It is longer than minimal but not padded; the complexity of the tool justifies the length. A slight improvement would be breaking into bullets, but it remains highly readable.

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

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

Given the tool's complexity (9 params, 5 required, no output schema), the description is thorough. It explains the return states and error handling, which substitutes for an output schema. It covers retry behavior and duplicate escalation. It does not explicitly detail prerequisites like authentication, but that is likely implicit in the platform context. For a mutation tool with this much nuance, the description is nearly complete, missing only minor operational details like timeout expectations.

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

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

The input schema has 100% coverage with every parameter described, so the baseline is 3. The description adds behavioral context for idempotency_key and merchant_url (whitelist matching), but these are already covered in the schema descriptions with comparable detail. The description does not introduce new parameter semantics beyond the schema; it reinforces but doesn't extend them, so 3 is appropriate.

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

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

The description opens with a precise verb and resource: 'Submit a purchase request.' This clearly states the action and what it acts on. The tool's function is unambiguous and distinct from siblings like check_status, get_spending_summary, and retrieve_card, which are all read-oriented; there is no confusion about which one to invoke for creating a purchase.

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 explicitly instructs when to use this tool versus alternatives: after submitting, 'poll check_status rather than retrying' directly names the sibling used for follow-up. It also provides retry guidance (reuse same idempotency_key) and clarifies when a fresh key is appropriate ('only for a genuinely new, separate purchase'). These are concrete, actionable usage guidelines that leave no ambiguity.

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

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

The annotations only carry destructiveHint: true, but the description adds critical behavioral context: the card is shown only once, a second call returns already_retrieved, and drawing consumes the spending envelope. It also explains AVS implications and the singleton nature of the display. This goes well beyond the annotation and is not contradicted by 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?

The description is long but every sentence carries weight — usage constraints, response fields, billing address handling, and null-value guidance are all essential. It is front-loaded with the most critical constraint ('Call exactly ONCE') and remains focused. Slightly long, but justified by the tool's complexity.

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

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

Given the tool's complexity (single-use, spending envelope, AVS, null handling), the description covers all relevant aspects: when to call, what it returns, how to use billing address vs shipping address, and how to handle missing data. There is no output schema, so the description must convey response behavior, and it does thoroughly.

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

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

Schema coverage is 100% for the single request_id parameter, and its description ('The request_id returned by request_purchase') is adequate. The tool description does not add extra parameter detail beyond that, so a baseline of 3 is appropriate.

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

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

The description clearly states the verb ('Draw and return') and the resource ('single-use virtual card for an APPROVED purchase request'), and explicitly distinguishes it from the sibling check_status by saying 'use check_status for that.' It is unambiguous about what the tool does and what it does not.

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 explicit when-to-use ('only when you are ready to pay'), when-not-to-use ('do NOT call this speculatively, to poll status, or more than once'), names the alternative tool (check_status), and instructs waiting for approval before calling. This is exemplary usage guidance.

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