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 description goes well beyond the destructiveHint annotation by explaining the one-time nature, spending-envelope consumption, lack of re-draw, and the already_retrieved error response on second call. This tells the agent the real-world consequences before invoking the 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?

The description front-loads the primary action, then layers critical usage rules and consequences with very little waste. It is dense but every sentence serves a different purpose—precondition, timing, side-effect, fallback behavior, and alternative tool routing.

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

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

For a one-parameter, no-output-schema tool, the description covers the relevant facets an agent needs: exactly what it does, when to call it, what consuming side effect exists, what to do if called again, and what to do if the purchase is not approved. No important invocation context 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%: request_id is already described as 'The request_id returned by request_purchase'. The description adds contextual significance by tying the parameter to an approved purchase, but does not need to repeat schema information. 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?

The description states a specific action ('Draw and return'), the exact resource ('single-use virtual card'), and a strict precondition ('for an APPROVED purchase request'). It also distinguishes itself from sibling tools, especially check_status, so an agent can tell when to select this tool.

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 very explicit when-to-use rules: call exactly once, only when ready to pay, and not speculatively. It names check_status as the correct alternative for polling or when the request is not yet approved, leaving no ambiguity about usage boundaries.

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