agentcard

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

Beyond annotations, the description reveals the tool's non-obvious two-phase behavior, the need for user to open a secure link, and the fact that repeated calls are used for status checks. It also clarifies that created cards will automatically use this added card, providing valuable operational context not available in annotations.

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 efficiently packed with necessary details without redundancy. It front-loads the primary purpose and flows logically through behavior, eligibility, and fallback instructions. Every sentence adds value, making it concise for the complexity involved.

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 interactive nature of this tool, the description explains the complete flow, fallback conditions, and the relationship with create_card. With an output schema present, the description correctly focuses on behavioral and contextual guidance, providing a complete picture 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?

The schema already provides 100% coverage with detailed descriptions for both optional parameters (restart and additional). The tool description adds no new parameter-specific information beyond what the schema defines, so the baseline score 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 tool adds the user's own Visa card to Agentcard, distinguishes from siblings by noting no KYC/balance funding needed, and explicitly contrasts with fallback to create_card. It concisely conveys both the action and the outcome.

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 explicit guidance on when to use this tool (adding a personal Visa card) and when to fall back to create_card (ineligible cards). It also explains the two-phase conversational flow and how to use the second call to check status, making usage boundaries clear.

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 annotations (readOnlyHint=false, destructiveHint=false), the description discloses that no money moves, the user completes payment in their browser, payment credentials are never seen/handled, and automatic phone verification may occur. No contradiction with annotations.

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-structured paragraph that front-loads the main action, then clearly explains boundaries, user role, and a conditional workflow. Every sentence adds value; no wasted words.

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, the description need not cover return values. It sufficiently explains purpose, parameter semantics, usage flow, and behavioral traits, including the phone verification contingency. Comprehensive for a checkout-link generation tool.

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%, baseline 3. The description adds meaning: amount is in cents with a typical range ($20–$10,000) and notes that exact range depends on funding provider. It also clarifies the default for payment_method (apple_pay).

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 ('Generate a secure checkout link') and resource ('add cash to user balance'), and distinguishes itself from siblings by clarifying it does not move money or initiate transfers, only prepares a hosted payment page.

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 provides context for when to use (to add funds via Apple/Google Pay) and a conditional workflow (phone verification needed → call verify_phone then add_funds). However, it does not explicitly state when not to use this tool, though the contingency covers a common alternative step.

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?

Describes the two different outcomes: for card_details/transaction, approval completes the action and returns result; for cross_app, it records consent and the requesting app retries. This goes beyond annotations (readOnlyHint=false, destructiveHint=false) and fully discloses the 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?

The description is concise yet comprehensive, using a few well-structured sentences. Front-loaded with purpose, followed by usage contexts, and ends with specific behavior details. Every sentence adds value without redundancy.

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 (multiple action types with different outcomes), the description covers all necessary aspects: when to use, how each action type behaves, and parameter hints. The existence of an output schema means return details are covered elsewhere, so the description is 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?

Adds meaning beyond the 100% schema coverage: explains that resource_id is card ID for most actions but approval ID for transaction, and that list_pending_approvals rows carry the action field. This enhances understanding of parameter usage.

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 resolves pending approval requests (approve or deny) and specifies the contexts (202 responses, list_pending_approvals). It distinguishes between card_details/transaction and cross_app actions, which differentiates it from sibling tools like close_card or pause_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 tells when to use this tool: after get_card_details or create_card returns a 202, or for rows from list_pending_approvals. It also contrasts the behavior for card_details/transaction (auto-complete) vs cross_app (record consent), providing clear usage 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?

Discloses critical behavioral traits beyond annotations: the tool returns a conversation_id that must be reused, checkout 'charges a one-time card' only after explicit user confirmation, replies must be relayed verbatim, and using new_order/timeout 'discards the cart and any pending confirmation.' This is exactly the kind of context an agent needs to avoid dangerous mistakes.

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 paragraph addresses a distinct critical aspect: conversational flow, checkout confirmation, error recovery, login links, and prerequisite guidance. It is front-loaded with purpose and uses capitalization/emphasis effectively. Dense but justified for a complex, potentially 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?

Given the tool's high complexity and the presence of an output schema, the description fully covers the flow, prerequisites, alternative tools, safety rules, and error handling. An agent has everything needed to select and invoke this tool 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%, but the description adds significant semantics: request can be a follow-up or full ask with concrete examples, conversation_id must be 'the SAME conversation_id' for continuity, and new_order 'ignores any conversation_id' and is only for unrelated orders. The prose meaningfully clarifies all three parameters beyond 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?

The description explicitly states the tool 'Shops and checks out, in natural language, across the merchants the user has linked' and 'runs the shopping flow for you.' This clearly distinguishes it from siblings like buy_connect or buy_list_merchants, which handle narrower aspects of the shopping lifecycle.

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 guidance is explicit and actionable: 'Call get_instructions FIRST for the current usage guide before your first buy.' It also explains when buy_connect/buy_connect_status do not apply ('Logins started here have no pending_id') and details when new_order is appropriate versus when it must never be used for error recovery.

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?

Describes that it opens a hosted browser session for some merchants, returns a URL, and requires calling buy_connect_status for confirmation. Mentions that non-login merchants are ready immediately. Also notes that it only tracks logins it started itself. Adds significant context beyond annotations (readOnlyHint=false, destructiveHint=false). No contradictions.

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, each adding value. Could be slightly more concise but still effectively communicates key points without redundancy.

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 one parameter, existing annotations, and presence of output schema (implied), the description covers purpose, usage flow, alternatives, pairing, and specific behavioral notes. Complete for the tool's 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?

Single parameter 'merchant' has schema description 'merchant slug (e.g. doordash)'. Description adds behavioral context: behavior varies by merchant type. Since schema coverage is 100%, description adds meaning beyond 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?

Description clearly states it connects a merchant for shopping, distinguishes between merchants needing login and those that don't, and explicitly contrasts with buy_link_merchant. This provides a specific verb+resource with sibling differentiation.

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 'Use this instead of buy_link_merchant for hosted-login merchants.' Explains pairing with buy_connect_status and contrasts with conversational `buy` tool. Clear when to use and when not.

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 indicate safe, idempotent read. Description adds polling behavior and return states, no contradictions.

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 purpose, efficient and clear.

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 output schema exists and tool is simple, description covers all necessary context for correct usage.

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 covers parameters fully (100%). Description restates that pending_id comes from buy_connect, providing marginal extra context beyond 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?

Clearly states the tool checks the status of a hosted merchant login started with buy_connect, lists return values, and distinguishes from sibling tool 'buy'.

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 use (after buy_connect) and when not to use (for logins from 'buy' tool), and provides alternative action.

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 readOnlyHint=true and destructiveHint=false, which matches the listing nature. The description adds that the tool shows whether each merchant is linked, and that linking is required before shopping, providing useful behavioral context beyond annotations.

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 efficiently convey purpose and usage. No wasted words, front-loaded with core functionality.

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 simplicity (no parameters), the description covers the main points: listing merchants and linking status. The presence of an output schema means return values are handled separately. Slight deduction for not specifying the output structure, but schema compensates.

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 no parameters, so schema coverage is 100%. The description does not need to add parameter meaning, and baseline of 4 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 tool lists merchants available for agent commerce and indicates linking status, with specific examples (Rappi, Good Eggs, DoorDash). This distinguishes it from sibling tools that perform purchases or other actions.

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 advises to link a merchant before shopping, providing context for when to use the tool. While it doesn't explicitly exclude alternatives, the context of listing vs. other actions is sufficient.

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?

Description adds behavioral context beyond annotations: explains that the session and link are dropped and that re-linking is required. Aligns with destructiveHint=true without contradiction.

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?

Extremely concise—one sentence that conveys purpose, effect, and required follow-up. No wasted words.

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 disconnect tool with one parameter and an output schema, the description fully covers purpose, behavior, and post-conditions. No gaps.

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?

Single parameter 'merchant' has schema description. Description adds a concrete example ('e.g. doordash'), providing clarity beyond 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?

Clearly states the action (disconnect a merchant) and the resource (merchant). Explains what happens: drops saved session and link, distinguishing it from other merchant-related tools.

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 states the consequence and the need to re-link, guiding the agent on when to use. Lacks explicit when-not-to-use or comparative alternatives, but the context is clear.

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 and idempotentHint, indicating safe read operation. The description adds value by stating it returns the current step and missing fields, and confirms the tool is non-destructive. No contradictions.

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 concise sentences with no filler. The first sentence states the action and usage context, the second describes the return value. Every sentence 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?

Given the tool's simplicity (zero parameters, clear annotations, and an output schema that presumably defines the return format), the description sufficiently covers purpose, usage, and behavioral context without missing critical details.

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 zero parameters and 100% schema coverage, the tool's schema already conveys all parameter info. The description does not need to add parameter details, meeting the baseline for no-param tools.

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 conversational verification state, specifies when to use it (after ID upload or for re-orientation), and distinguishes from siblings like 'get_kyc_status' and 'submit_kyc_document' by focusing on the verification state and missing fields.

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 advises use after ID upload and for re-orientation, providing clear context. It does not mention exclusions or alternatives, but the guidance is sufficient for a simple read-only check 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?

The description claims the tool is idempotent ('Safe to call on an already-closed card (idempotent)'), but annotations explicitly set idempotentHint to false. This is a direct contradiction, warranting a score of 1 per guidelines.

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 that front-loads the core action. Every sentence adds value, but it could be slightly more concise. Structure is logical: purpose, irreversibility, idempotence, special case for rewards card.

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 complexity (rewards card protection, idempotence, approval flow), the description covers key scenarios. It explains the special case for rewards card and the need for user confirmation. It does not detail what happens to card balances or refunds, but the output schema likely covers return values.

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% (both parameters have descriptions). The description adds significant context for confirm_rewards_card ('only set after user confirms, never preemptively') and clarifies the rewards card protection. It also mentions approval_id, which is documented in schema but the description provides usage context.

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 'Permanently close a virtual card', specifying the verb (close) and resource (virtual card). It distinguishes from sibling tools like pause_card and resume_card by emphasizing permanence and irreversibility.

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 usage context: safe to call on already-closed cards (idempotent), and for rewards cards requires explicit user confirmation via confirm_rewards_card. It also mentions the approval flow for cards from another app. However, it does not explicitly compare to alternatives like pause_card or when not to use.

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 annotations by disclosing that cards are immediately active and incur real charges, the default funding hierarchy, the effect of connected_card_id and source overrides, and the difference between company and personal account limits. This adds critical behavioral context not present in the annotations.

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 dense but well-structured, with each sentence providing necessary information: definition, funding resolution, overrides, fallback, and limit context. No filler or redundant phrasing; 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?

Despite the complexity of 7 parameters, the description covers all key contextual aspects: immediate activation, funding source decision logic, overrides, top-up path, and limit variations. An output schema exists, so return-value details are not needed. This is complete for the tool's 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 description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some cross-parameter context (e.g., how source and connected_card_id interact with funding choices), but this information is largely redundant with the schema descriptions. 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 opens with a specific verb+resource ('Create a new virtual debit card'), immediately distinguishing it from siblings like add_card, close_card, and pause_card. It also clarifies that the card is live and charged for real, reinforcing its unique purpose.

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 clearly explains the context for using create_card, including how funding sources are selected, when to use per-call overrides, and when to top up with add_funds. It does not explicitly contrast with sibling tools like 'add_card' (which might be for adding an external card), but the virtual debit card focus provides enough context for selection.

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 indicate this is a creation (write) operation. The description adds context about supported bank types and required fields. No contradictions. Moderate additional behavioral disclosure beyond annotations.

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 purpose, clearly separating US and international cases. No wasted words. Efficient and well-structured.

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 the richness of sibling tools, the description is complete. It explains the tool's role in the withdrawal flow and covers all necessary behavioral aspects.

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 baseline is 3. The description adds value by explaining the relationship between parameters (e.g., US vs international fields) and giving examples for country_specific. This extra context warrants a 4.

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 saves a bank account as a withdrawal destination. It explicitly mentions support for US ACH and international SWIFT, and distinguishing from sibling tools like 'withdraw' and 'list_withdrawal_recipients'.

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 workflow guidance: ask the user for bank details conversationally, call this once, then use 'withdraw' for payout. It lacks explicit when-not-to-use or alternatives but the context is sufficient.

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?

Discloses that the tool provisions the balance account on first use, a behavioral trait beyond annotations. Explains fund flow (Apple Pay/Google Pay to USDC). Annotations are consistent.

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 primary purpose, efficient and waste-free.

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 description for a simple read tool with no params and an output schema. Explains balance nature, provisioning, and sibling differentiation.

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?

No parameters, so baseline 4. Description adds value by explaining what the returned balance represents and its source, compensating for lack of params.

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?

Clearly states the tool returns the user's cash balance for funding cards. Differentiates from list_cards by specifying that cards themselves are listed elsewhere, providing clear sibling distinction.

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 context that balance account is provisioned on first use and describes funding sources. However, lacks explicit when-to-use vs alternatives like get_card_balance, though differentiation is implied.

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?

Aligns with annotations (readOnlyHint, idempotentHint, destructiveHint) and adds useful behavioral context: live balance, faster, no credential exposure. No contradictions.

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, each purposeful: first states purpose with resource specificity, second provides usage guidance. No wasted words, front-loaded.

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 its purpose: explains what it does, when to use, and key benefits. Output schema exists but not shown; description covers all needed context for an agent.

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?

Single parameter card_id with basic schema description 'The card ID'. Description adds 'of ONE virtual card' but doesn't elaborate on format or constraints. Schema coverage is 100%, 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?

The description clearly states the tool returns the live balance of a single virtual card, distinguishing it from get_balance (overall cash balance) and get_card_details (which exposes sensitive credentials).

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 advises preferring this tool over get_card_details when only verifying available funds, citing speed and credential safety. Also contrasts with get_balance.

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?

Discloses that the tool requires human approval before returning credentials and that card details are encrypted at rest with AES-256-GCM. Annotations already declare read-only and non-destructive, so this adds valuable behavioral context without contradiction.

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 sentences with no filler: front-loaded purpose, alternatives, approval, and encryption. Every sentence 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?

Given the tool's complexity (sensitive data, approval flow, two params, output schema exists), the description covers all necessary aspects: what data is returned, when to use, approval process, and encryption. No gaps.

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 basic descriptions, but the description explains the approval_id parameter workflow (first call without, then retry with it), adding meaning beyond schema. This warrants a score above baseline 3.

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 returns decrypted PAN, CVV, expiry, and balance, and distinguishes from get_card_balance, citing specific use cases. This is a specific verb+resource with sibling differentiation.

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 states when to use (for filling payment forms) and when not (prefer get_card_balance for just balance). Also describes the approval workflow, including when to call approve_request, providing complete 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?

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it must be called before `buy`, which is a behavioral prerequisite beyond annotations.

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?

Single sentence front-loading the critical prerequisite and purpose, with no extraneous words.

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 parameters and output schema present, the description fully covers what the agent needs to know: its role as a pre-step and what it returns.

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?

No parameters exist, so baseline is 4. The description does not need to add parameter details.

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 returns a usage guide for shopping and checkout, and explicitly ties it to the `buy` tool, distinguishing it from siblings.

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 'Call this BEFORE using `buy`', providing clear when-to-use 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?

Annotations already declare readOnlyHint and idempotentHint. Description adds useful behavioral info (returns state and next step), but is not essential beyond annotations.

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, no wasted words. Front-loaded with purpose, followed by usage. Highly efficient.

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 zero parameters and the presence of an output schema, the description fully covers the tool's purpose, usage, and behavior. Complete for this context.

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?

Input schema has zero parameters, so schema coverage is 100% automatically. Description adds no parameter info, but none is needed. Baseline 4 for 0 parameters.

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 explicitly states the tool checks KYC status, returns verification state and next step. It clearly distinguishes from sibling tools like start_kyc or submit_kyc_document.

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 explicit guidance: poll after face scan or when create_card reports kyc_required. Offers clear context for when to use.

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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds context about the specific data returned (plan, limits, usage), which is useful but not beyond annotations.

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 purpose, every sentence provides value. No wasted words.

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 tool with no parameters and an existing output schema, the description fully explains what it does, when to use it, and what it returns. 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?

No parameters so baseline is 4. Description does not need to add param info.

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 shows the user's current subscription plan, card limits, and monthly usage, using specific verbs and resources. It distinguishes itself from siblings like cancel_plan.

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 to call before create_card for per-card amount cap or remaining quota, and for user queries about plan, limits, billing, or upgrading. Also mentions cancel_plan as an alternative for cancellation.

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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds valuable context: what data is shown (balance, lifetime, recent activity) and explains tokenback mechanics (rate, AI card boost). No contradictions with annotations.

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?

Extremely concise (3 sentences, ~55 words). Every sentence serves a purpose: describes output, explains tokenback value, and provides cross-reference to redeem_rewards. No redundancy.

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 zero parameters, existing output schema, and annotations, the description fully covers what the tool does, what it returns, and how it fits with sibling tools. Complete for a simple read-only tool.

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?

No parameters; baseline 4 is appropriate. Schema is empty, so description adds no parameter info, but none is needed.

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?

Clearly states 'Show the user's tokenback' with specific components (balance, lifetime earned, recent activity). Distinguishes from sibling tools like redeem_rewards, so agents know this is the read-only view.

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 tells when to use this tool vs. alternatives: 'Redeem with redeem_rewards' for redemption. Also implies use for viewing reward details, not for other actions.

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 the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral detail by specifying which settings are read-only (authorization settings) and that the rest can be changed via update_settings. It does not contradict annotations, and the practical guidance on using the returned data goes beyond what annotations provide, though it stops short of disclosing rate limits or pagination 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?

The description is a single long sentence with multiple clauses, but every clause adds substantive value: it enumerates the data returned, explains the practical importance of each, and points to the update tool. It is dense but not bloated, and the front-loaded 'View the user's notification preferences' immediately orients the reader.

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 that an output schema exists, the description need not enumerate return fields. It provides rich context about the meaning and use of each data category, states that authorization settings are read-only, and references the update tool. For a zero-parameter, read-only tool, this description is 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?

The tool has zero parameters, so the schema is empty. According to the rubric, a baseline of 4 applies. The description appropriately does not attempt to document nonexistent parameters; it focuses on the content of the read operation instead.

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 the specific verb 'View' and precisely enumerates the four categories of information returned: notification preferences, default payment source, default delivery address, and authorization settings. This clearly distinguishes it from sibling tools like get_balance or get_plan, and the additional context on how to use each piece of data reinforces the tool's purpose.

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 consult the tool ('check it before picking a funding source for them', 'check it before asking them to dictate an address') and names the alternative update_settings for modifying settings. This provides both concrete triggering conditions and an explicit alternative, fully satisfying the when-to-use vs. alternatives criterion.

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 are all false and provide no safety profile, so the description carries full burden. It discloses that the link is multi-use, short-lived (~15 minutes with expiresAt), and should be re-minted after expiry. It also clarifies that identity verification runs in-page, and that the OAuth-only constraint applies. This is rich, non-obvious behavioral context beyond what any schema field captures.

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 every sentence contributes: purpose, capabilities, when to use, param mode, expiry, and OAuth constraint. No repetition or filler. Despite its length, it remains tightly structured and easy to parse.

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 (two modes, optional params, time-limited links, platform restrictions), the description covers all essential aspects: what it does, when to use, how params modify behavior, operational details (expiry, OAuth), and what to do when expired. The output schema handles return values, so no omission there.

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 parameters are described in the schema, so baseline is 3. The description adds meaning by explaining that merchant and amount_cents must be passed together to open the payment-approval sheet for that exact charge, versus the default card-list view. This clarifies the combined behavior and optional nature, going slightly beyond 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 produces a shareable URL for the user's hosted wallet, with specific detail on what it opens in the browser. It distinguishes itself from sibling tools by being a link generator rather than a card or KYC action, and explains the two usage modes (card list vs. payment-approval sheet).

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 tells when to use the tool ('whenever the user needs a browser step'), gives examples (adding/seeing cards, finishing verification), describes how to trigger the payment-approval sheet with merchant + amount_cents, and notes the limitation to app connections (OAuth) and unavailability on personal logins. This is strong when/when-not 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?

Annotations include destructiveHint: true, and the description goes beyond by explaining that accounts are merged (the identity-verified account survives) or the identifier is simply added if no account exists. It also details the two-step process and code verification, adding 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 detailed but front-loaded with the core purpose, then structured into two steps. It is slightly lengthy but every sentence adds value; no redundancy.

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 (two-step process, conditional outcomes), the description covers all necessary context: when to use, steps, possible results (merge vs. add). Output schema exists but return values are not explained; however, that is acceptable per rules.

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%, but the description adds substantial meaning beyond schema by grouping parameters into steps (Step 1: type, identifier; Step 2: ticket, code) and explaining their purpose in the flow, aiding correct invocation.

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 links or merges accounts belonging to the same person, with specific verb ('link or merge') and resource ('Agentcard account'). It distinguishes from sibling tools by describing a unique operation (merging accounts) not available in other tools.

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 tells when to use the tool: 'when the user says they already have an account under a DIFFERENT email or phone number — most often after identity verification (KYC) is rejected as a duplicate'. It provides step-by-step guidance but does not mention when not to use or alternatives, slightly reducing score.

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/idempotent/destructive, but the description adds substantial behavioral context: the list of returned fields (ids, brand, last4, expiry, status), the meaning of isDefault, and the fallback to the newest active card. No contradictions with annotations.

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 sentences, each purposeful: the first defines the tool's scope, the second explains the isDefault behavior, and the third differentiates from a sibling tool. No redundancy or irrelevant detail.

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 and no parameters, the description adequately covers the tool's purpose, selection criteria, output semantics, and behavioral nuances. It is complete without being overly verbose.

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 the baseline is 4. The description adds semantic value by explaining what the output fields mean and how the default card is chosen, but there is no parameter semantics to clarify.

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 'List the user's ADDED cards' and specifies the resource as 'their own Visa cards enrolled via add_card — the BYOC funding source'. It also explicitly distinguishes from list_cards, making it unambiguous which tool to use.

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 explicit usage guidance by contrasting with list_cards ('Not the same as list_cards (the virtual cards Agentcard issues)') and explaining how the isDefault row relates to create_card, giving clear context for when to use this tool and how its output is used.

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?

Goes beyond the readOnlyHint and destructiveHint annotations by detailing the shared wallet mode, cross-app source tagging, and the read-only restriction for cards issued by other apps/companies. This is valuable behavioral context not present in the annotations.

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 sentences, each delivering essential information: purpose, first-step usage, and shared wallet behavior. No filler or redundancy; it is well-structured and front-loads the core purpose.

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?

The description covers the main use case, edge cases for shared wallets, and cross-app restrictions. Since an output schema exists and there are no parameters, no additional return value or parameter documentation is needed.

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 0 parameters and schema description coverage is 100%, so the description is not required to add parameter details. With no parameters, baseline 4 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 tool's function: listing the user's live cards with IDs, last four digits, expiry, balance, and status. It also distinguishes from siblings by noting that cards from other apps are read-only and that get_card_details and close_card won't work on them, and points to create_card as a follow-up.

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 to 'Start here to find available cards' and directs to call create_card if no cards are returned. It also explains the shared wallet behavior and clarifies which operations are not supported on read-only cards, providing clear when-to-use and when-not-to-use 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?

Description adds details beyond readOnlyHint: includes 'when each was connected and whether it is still active'. Also explicitly states 'Read-only', consistent with annotations.

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 purpose, no waste. Every sentence adds value.

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 description for a parameterless tool with output schema. Covers purpose, data returned, and alternative tool for revocation.

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?

No parameters exist; baseline 4 per guidelines. Schema coverage is 100% trivially, no additional param info needed.

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 lists third-party apps connected via OAuth, with specific example (Kilo). It distinguishes from revoke_connection by directing to that sibling for revocation.

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 use (to list connected apps) and when not to (to revoke, use revoke_connection). Provides clear alternative.

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, destructiveHint=false, idempotentHint=true. The description adds context that this is for flight bookings only and that the default method is marked. No contradictions. Could add more on behavior like order or pagination, but currently sufficient.

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: first explains purpose and return structure, second provides usage alternatives. Front-loaded with key information, no redundant phrases, highly efficient.

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 complexity (0 params, output schema exists), the description covers the tool's purpose, what it returns, and related tools. No gaps in required information for agent selection and 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?

No parameters exist, so schema coverage is 100%. The description does not need to explain parameters, and it does not repeat schema info. The context that it returns specific fields is helpful and goes beyond 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?

The description clearly states the tool lists saved payment methods used only for flight bookings, lists the returned fields (id, brand, last 4 digits, expiry, default), and explicitly excludes cards and adding funds, distinguishing it from sibling tools.

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 explicit guidance on when to use this tool (listing payment methods) and when to use alternatives: setup_payment_method for adding, and set_default_payment_method/remove_payment_method for modifying. Also mentions that gated tools can be called by name despite not being in the tool list.

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?

Goes beyond annotations by emphasizing that approvals require user consent and the agent must not act on its own. Also discloses session scope. The readOnlyHint/idempotentHint align with 'list pending approvals', with no contradiction.

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 no filler. Each sentence adds either scope, usage rule, or session constraint; the most critical consent rule is front-loaded.

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 zero params and an output schema present, the description fully covers what the tool does, when to use it, and important guardrails. No gaps remain for an agent to select and invoke it 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?

Tool has zero parameters, so the schema is empty and there is nothing to document. Baseline for 0 params is 4; description correctly omits parameter details.

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?

Description clearly states the tool lists the user's PENDING approval requests from connected apps with specific examples (create a card, view full card details, close/pause/resume a card, change a limit). It distinguishes from sibling approve_request by framing this as the listing step.

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 explicit guidance: surface each request and let the user decide, resolve with approve_request afterward. Also states session limitation ('Personal sessions only; company-connected sessions have no personal inbox') and the rule 'NEVER approve or deny on your own'.

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 significant behavioral context beyond annotations: transactions are returned newest first, each row tagged with card when all cards, and offset is ignored for single-card queries. No contradictions with readOnlyHint and idempotentHint.

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 sentences, each purposeful: content summary, card_id usage, filtering advice, and alternative views. No redundant or unnecessary text.

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 output schema exists and schema covers all parameters, the description adequately covers behavior, filtering, pagination, and alternatives. No critical gaps remain.

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 baseline is 3. The description adds value by explaining the semantic difference for card_id (one vs all) and advising use of limit/status. However, it does not elaborate on offset behavior beyond the schema note.

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 lists transactions with specific fields (amount, merchant, status, timestamps) and distinguishes behavior with/without card_id. It differentiates from siblings by mentioning alternative gated views, making the purpose 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?

The description provides usage guidance on filtering via limit and status, and explains when to include or omit card_id. It references alternative views but does not explicitly state when to prefer them over this tool, slightly reducing clarity.

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, idempotentHint, and destructiveHint. The description adds that data is masked (bank name and last four only), providing transparency beyond annotations. No contradictions.

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 purpose, followed by workflow guidance. No wasted words, every sentence adds value.

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 zero parameters and an output schema existence (not shown but present), the description covers what the list contains, how to use results, and fallback action. Complete for its 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 input schema has zero parameters, achieving 100% coverage. Baseline for 0 params is 4, and the description doesn't need to add parameter info. It focuses on output behavior, which is acceptable.

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 lists saved bank accounts for withdrawals, with masking of details. It distinguishes itself from siblings like create_withdrawal_recipient and withdraw by explaining the workflow.

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 provides context: use the returned id as recipient_id for withdraw, and if empty, call create_withdrawal_recipient. This guides the agent on when and how to use the 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds key behavioral details: no payment taken, auto-billing, actions like skip/unskip affecting deliveries, and the need to link the merchant first. This fully compensates for minimal annotation info.

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 fairly concise given the complexity, with front-loaded purpose. Every sentence earns its place, though it could be slightly more structured (e.g., bullet lists). Still effective.

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 (8 parameters, various actions), and existence of an output schema, the description covers all necessary context: actions, settings, prerequisite linking. It is complete enough for an agent to use 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?

With 100% schema coverage, baseline is 3. The description adds significant value by explaining the action enum values and providing a detailed list of settings for 'update_setting', which goes beyond the schema's brief 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 clearly states it manages recurring meal/grocery subscriptions (e.g., Locale), explicitly distinguishes from one-time purchases, and lists specific actions. This differentiates it from sibling tools like 'buy', which are likely for purchases.

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: it's for subscription management, not one-time purchases, and no payment is taken. It also mentions linking the merchant first. However, it lacks explicit when-not-to-use guidance relative to siblings, though many are unrelated.

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 non-destructive and idempotent. Description adds reversibility and mentions resume_card. Also specifies that it blocks all new charges, though missing details on pending transactions.

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 main purpose, then constraints and parameter usage. No redundant words.

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?

Covers action, when to use, card type constraints, and a key parameter detail. With only 2 simple params and output schema present, description is fully sufficient.

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%. Description adds critical context for approval_id, explaining the flow for cards from another app, which goes beyond 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?

Clearly states 'Pause a multi-use card: temporarily blocks ALL new charges', with specific verb (pause) and resource (multi-use card). Distinguishes from siblings like close_card (permanent) and resume_card (reverse).

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 states when to use: 'Right for stop this subscription for now or a card the user suspects is compromised' and when not to: 'Only multi-use cards can be paused; single-use cards... cannot be paused.'

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which sufficiently convey the tool's safety and behavior. The description adds the detail about reading 'message history' but does not provide additional behavioral traits beyond the annotations.

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, front-loaded sentence that conveys the essential purpose with zero waste. Every word 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?

With a single parameter, high schema coverage, and an output schema present, the description is largely sufficient. It does not cover potential limitations like pagination or message ordering, but for a simple read operation with strong annotations, this is acceptable.

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 a single required parameter conversation_id. The description confirms the tool reads a support conversation but adds no new meaning beyond the schema field description 'The conversation ID'.

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 the specific verb 'Read' and states the resource 'message history of a support conversation'. It clearly identifies the tool's action and distinguishes it from siblings like start_support_chat or send_support_message.

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 guidance is provided on when to use this tool versus alternatives such as start_support_chat or send_support_message. There is no mention of prerequisites or context for choosing 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description discloses critical behaviors: credit lands within 1-2 minutes, some codes are gated on KYC approval, the claim locks instantly, and list_codes is a gated tool accessible by name. This adds significant context not present in 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?

The description is front-loaded with the core purpose and uses three sentences, each earning its place. The second sentence explains timing and KYC exceptions, the third offers a useful pointer to list_codes. No wasted words.

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?

The description fully covers what an agent needs to know: purpose, idempotency, delay, KYC dependencies, and a hidden tool reference. An output schema exists to explain return values, so no additional return-format information is required.

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 schema covers the only parameter (code) with a clear description that case and dashes are forgiven. The tool description adds no additional parameter syntax, but it does provide behavioral context such as idempotency and KYC gating. This meets the baseline for high schema coverage.

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 specific verb and resource: 'Redeem a promo code that adds money to the user's cash balance.' This clearly states what the tool does and distinguishes it from similar siblings like redeem_rewards or add_funds by focusing on promo codes and cash balance.

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 implies when to use (when a user provides a promo code) and adds contextual guidance (each code works once per user, delay, KYC conditions). It also mentions list_codes as an alternative for viewing history, but does not explicitly exclude other tools or name alternatives for redeeming.

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 discloses important behavioral details beyond annotations: tokens convert at a fixed rate, the rewards card is permanent, locked to specific merchants, created on first redemption, and topped up afterward. Since annotations only indicate non-read-only but don't specify effects, these details add significant transparency. It could further mention irreversibility but is not required for basic use.

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 sentences, front-loaded with the core action and effect, then a key restriction, then brief usage guidance. Every sentence adds essential information with no redundancy or fluff, making it highly concise and well-structured.

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 tool with an output schema, the description covers all essential aspects: what happens, conversion rate, card behavior, merchant restriction, prerequisite check, and user consent. It doesn't explain every edge case but points to get_rewards for balance/minimum, which is sufficient for correct invocation. This is complete for the tool's simplicity.

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 for the single parameter 'tokens' already provides a full description including the conversion rate and an example, giving 100% coverage. The tool description repeats the rate but adds no new parameter-level constraints or format details. Therefore, it meets the baseline for schema-covered parameters.

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's purpose: 'Redeem tokenback' with a specific conversion rate and effect on the rewards card. It distinguishes itself from sibling tools like redeem_code and withdraw by describing the unique reward card mechanism and AI-lab merchant restrictions. The verb 'redeem' plus the specific resource 'tokenback' makes the purpose 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?

The description provides clear usage context: 'Check get_rewards first for the balance and the minimum' and 'Ask the user before redeeming.' This gives a prerequisite and consent requirement, but it does not explicitly name alternatives or when-not-to-use conditions, so it stops short of a 5. The guidance is still effective for the agent.

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 indicate destructiveHint=true and non-read-only. The description adds substantial behavioral details: irreversibility, that virtual cards are closed first, network-level unenrollment, and the mandatory confirmation step. This enriches the agent's understanding far beyond the basic annotations.

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 tight and well-structured: it states the action, explains consequences, provides a safety warning, tells where to find the ID, and notes reversibility via re-adding. Every sentence adds value with no redundancy.

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 destructive, irreversible action, the description covers the full context: what happens (closure of virtual cards, unenrollment), the required confirmation, how to obtain the ID, and that the card can be re-added later. With an output schema present, nothing critical 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 schema already provides 100% coverage with a clear description for attached_card_id. The description reinforces this by directing users to list_added_cards for obtaining the ID, adding practical context for the parameter's value sourcing, which goes slightly beyond 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?

The description clearly states the action ('Remove (unenroll)') and the specific resource ('one of the user's added cards'), distinguishing it from sibling tools like close_card and list_added_cards. It further clarifies that unenrollment is the intended meaning, making the purpose 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?

The description provides clear context by instructing to get IDs from list_added_cards and emphasizing the need to confirm with the user. However, it does not explicitly contrast with alternative tools like close_card or add_card, leaving some room for interpretation about when to prefer 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 indicate non-read-only, non-destructive, and idempotent behavior. The description adds that the card will 'accept charges again,' but does not cover the two-step approval flow hinted by the 'approval_id' parameter, leaving a behavioral gap.

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 extremely concise, with two sentences that front-load the main action and efficiently link to the sibling tool. Every sentence serves a purpose.

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 moderate complexity (2 parameters, one with conditional usage), the description plus schema covers the essential behavior. However, omitting a summary of the two-step approval pattern (for cards from another app) is a minor completeness gap.

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 schema covers both parameters with descriptive comments (100% coverage). The description adds no additional meaning beyond what the schema already provides, so it meets the baseline but does not exceed it.

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 action ('Resume a paused multi-use card'), the resource ('paused multi-use card'), and distinguishes from the sibling 'pause_card' by calling itself the inverse.

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 by referring to 'pause_card' as the inverse, implying it is used after pausing. However, it does not explicitly state when not to use it or mention alternatives like 'close_card'.

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 discloses that the action is destructive (aligning with destructiveHint=true) and adds details beyond annotations: it invalidates tokens and requires reconnection via OAuth. No contradiction with annotations.

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 the primary action, no redundant information. Every sentence 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?

Given the tool's simplicity (1 param, full schema coverage, output schema present), the description covers purpose, behavior, and parameter source completely. No gaps.

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 parameter, so baseline is 3. The description adds value by specifying the source of the client ID ('from list_connections'), which helps the agent determine the correct value.

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 action ('Revoke a third-party app's access'), the resource (user's Agentcard account), and the mechanism ('Disconnects the app and invalidates its OAuth tokens'). It distinguishes itself from sibling tools like list_connections by specifying the required input source.

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 tells the agent to 'Pass the clientId shown by list_connections', providing clear usage guidance. While it doesn't list when not to use it, the context of revoking access versus other actions is clear.

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 indicate readOnlyHint=false, destructiveHint=false, etc. Description adds no behavioral context beyond annotations. No disclosure of permissions, rate limits, or side effects.

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?

Single sentence that efficiently conveys purpose. No extraneous 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?

Adequate for a simple tool with output schema and fully described params. Lacks usage guidance and behavioral details, leaving gaps for an AI agent.

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 descriptions for both parameters. However, descriptions are minimal ('Your message', 'The conversation ID'). Description adds no extra meaning beyond schema, so baseline 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?

Description clearly states verb 'Send' and resource 'message' in context of 'existing support conversation'. It is specific but does not differentiate from sibling tools like 'read_support_chat' or 'start_support_chat'.

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 when-to-use or when-not-to-use guidance. No mention of alternatives despite having similar sibling tools. Agent must infer usage from name 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 description discloses key behavioral traits beyond the minimal annotations: the fare is charged via a hold at booking, no virtual card is created for flights, and it returns a secure checkout URL. It also clarifies what the tool does NOT do, which is important given the annotations provide no safety or side-effect 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?

The description is composed of three concise, information-dense sentences. It front-loads the primary purpose, then provides exclusions and an alternative, and ends with the return value. Every sentence earns its place with no redundant 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?

Given the tool has no parameters but does have an output schema, the description is complete: it states the action, the specific use case, what it does not do, and the return value. It also references a sibling tool for alternative behavior, making it fully self-sufficient for an agent to select and invoke.

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 the baseline is 4. The description does not need to explain parameter syntax, but it adds contextual meaning about the tool's purpose and return value, which helps the agent understand the invocation context.

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 ('Save') and resource ('payment method') plus a clear scope: used ONLY to pay for flight bookings. It distinguishes itself from sibling tools by explicitly stating it does not fund cards or cash balance, which sets it apart from tools like add_card and add_funds.

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 usage guidance: this tool is for saving a payment method for flight bookings only. It provides an explicit exclusion ('does NOT fund cards or the cash balance') and names the alternative tool ('see add_funds'), making it clear when not to use this tool and what to use 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?

Adds detailed behavioral context beyond annotations: explains the interactive process, which fields are automatically read vs. asked, that occupation/income are never asked, and the return value structure (next step, upload options, hosted URL). No contradiction with annotations.

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?

Packs much information but includes instructions to the agent ('Relay each step as one short message') that could be considered extraneous. Front-loaded purpose, but could be more concise.

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 complexity of identity verification, the description covers the process, input constraints, and expected outputs. Output schema exists to define return values, so description need not detail them.

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 baseline is 3. Description adds value by clarifying that 'terms_accepted' is deprecated and 'agreements_accepted' expects specific keys (e_sign, etc.), and explains the acceptance process.

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?

Clearly states 'Begin (or resume) identity verification.' Describes the conversational flow and differentiates from siblings like check_kyc_document or submit_kyc_fields by specifying this is the initial step.

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?

Describes when to use (starting/resuming KYC) and provides conversational guidance, but does not explicitly state when not to use or mention alternatives among siblings.

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 show readOnlyHint=false and destructiveHint=false; description adds that tool is rate-limited, returns masked destination and whether code was sent, and explains behavior when phone is already verified. No contradictions.

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?

Single well-written paragraph that front-loads the main action and includes all necessary details without fluff. Could be slightly more structured, but efficiently conveys all key 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?

Given no parameters and presence of output schema (inferred), description covers return values, next step (verify_phone), and contrasts with sibling tools. Completely sufficient 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?

Input schema is empty (0 params), baseline 4 per instructions. Description does not need to add parameter info, but does not provide extra semantics beyond 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?

Description clearly states the tool sends a one-time verification code, distinguishes it from add_funds (which auto-sends) and verify_phone (next step). Specific verb 'send/re-send' and resource 'verification code' are explicit.

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 to use only to re-send when code never arrived, mentions rate limits, that unexpired codes still work, and when phone is already verified to go straight to add_funds. Provides clear when-to-use and when-not-to-use.

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 provide idempotentHint=true, but the description says 'start a new conversation', which may imply non-idempotent behavior. No additional context on side effects, authentication, or conversation limits is given, so transparency is moderate.

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, efficient sentence with no wasted words. It is front-loaded and gets to the point, though it could be slightly more informative.

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 tool with one parameter and output schema, the description is sufficiently complete for an AI agent to use. Missing behavioral clarifications are minor given the 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 single parameter 'message' is fully described in the schema with clear meaning. The description adds no extra detail, so the baseline of 3 applies due to high schema coverage (100%).

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 'start' and resource 'support conversation', and specifies the action of sending the first message. It distinguishes itself from sibling tools like 'send_support_message' (for existing conversations) and 'read_support_chat'.

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 implies when to use (initiate a new chat), but lacks explicit guidance on prerequisites or alternatives. However, the context from sibling tools provides enough distinction for an AI agent.

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 discloses key behaviors beyond annotations: the tool returns extracted fields that should be shown to the user, if no details are read the image is not an ID (don't insist), supported formats (JPEG/PNG/WebP up to 12MB), and conversion of HEIC. Annotations only provide readOnlyHint=false and destructiveHint=false, so description adds significant value.

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 paragraph but well-structured: it starts with the core purpose, then enumerates the three input methods, followed by behavioral instructions, and ends with technical constraints. Every sentence is necessary and imparts actionable information without redundancy.

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 complexity (8 parameters, multiple input modes, behavioral nuances), the description covers all aspects: input methods, parameter usage rules, format/size limits, and post-submission behavior (show results, handle failed reads). The presence of an output schema further reduces the need to describe return values.

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 coverage, the description adds meaning beyond the schema: e.g., back_base64 is 'optional, recommended — the barcode reads most accurately'; front_base64 warns 'never type or reconstruct image bytes yourself'; document_type and issuing_country should only be passed if user volunteered. This prevents misuse.

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's purpose: 'Submit the user's ID photo for identity verification.' It specifies the verb 'submit' and resource 'ID photo for KYC'. It also distinguishes from siblings like check_kyc_document and start_kyc by focusing on the submission action.

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 explicit guidance on when to use each parameter (base64 for programmatic data, file_path for local mode, or omit for upload link). It also instructs not to ask the user for document type or country unless volunteered, and when to relay questions from the result.

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?

Discloses that SSN is forwarded to verification provider and never stored by Agentcard, and agreements must be presented verbatim. Annotations show readOnlyHint=false so write behavior is expected; description adds data handling details. Slightly lacking idempotency or side-effect info, but strong overall.

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, then concise details. Every sentence adds value, no redundancy. Efficiently covers all important aspects without extraneous text.

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 13-parameter tool with output schema, the description covers boundary behaviors (what not to ask), data retention policy, and required user interaction for agreements. Thorough and 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 coverage is 100%, and description adds critical meaning: explains which params correspond to missingFields vs corrections vs agreements, clarifies SSN handling, and mandates agreement presentation. Goes far beyond 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?

Description clearly states 'Submit identity fields for verification' and lists specific categories (missingFields, corrections, agreements). Distinguishes from sibling tools like submit_kyc_document and start_kyc by specifying its unique role.

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 explicit when-to-use: when ID photo didn't carry fields, corrections needed, and agreements acceptance. Includes explicit 'NEVER ask' instructions for irrelevant fields. Implicitly distinguishes from siblings like submit_kyc_document (document upload) and start_kyc (initiation).

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 indicate this is a mutation (readOnlyHint=false) but not destructive. The description correctly implies a write operation and explains the expected outcome (saves data then retry). No contradictions.

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 coherent paragraph with no redundancy. It efficiently conveys purpose, usage, and exclusions. Could be slightly more structured but is 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 complexity of the sibling tools and the orchestration context, the description thoroughly explains the tool's role in the broader flow, including post-submission actions and limits on user prompts.

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 already provides full coverage with descriptions for both parameters (phone_number format, terms_accepted must be true). The description does not add significant new semantic details beyond the schema, though it contextualizes them within the workflow.

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 identifies the tool's purpose: submitting phone number and terms acceptance for a virtual card. It distinguishes this from other flows like KYC and explicitly ties it to the create_card workflow.

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 explicit when-to-use guidance: call after create_card returns user_info_required. Also states what not to ask (occupation, income, etc.) and what to do after submitting (retry create_card).

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?

Describes the multi-step workflow: brainstorms ideas, picks one, builds cart, shows item+total. Notes it requires explicit user confirmation through a separate tool. Annotations support this (readOnlyHint=false, openWorldHint=true). Adds context beyond annotations.

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?

Well-structured: main action first, then workflow, then limitations. Every sentence adds information. Slightly long but justified by complexity; no wasted words.

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?

Covers usage, workflow, integration with sibling tool, and constraints. Missing output schema details but description states what is shown. Sufficient given openWorldHint annotation and no undefined behavior.

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 covers 100% with descriptions, but description adds value: explains default max_dollars (10), hard clamp (25), and 'merchant' being optional. Provides behavioral nuance not in schema alone.

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?

Description clearly states verb (buy), resource (something unexpected), and scope (under a small dollar cap, default $10, hard max $25). Distinguishes from sibling tools like 'buy' which handles normal orders and checkout.

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 use: 'when the user cannot decide what to order or just wants a fun surprise'. Also clarifies when not to rely on it for checkout: 'It NEVER checks out by itself' and directs follow-up via the 'buy' tool on the same conversation_id.

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 set readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds key behaviors: raising reserves extra balance, lowering frees difference, limit floor of current spent, and the need for approval_id with cross-app cards. No contradictions with annotations.

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 one concise paragraph starting with the main action, then effects, then restrictions. Every sentence adds value without waste. Minor improvement could be shorter phrasing but overall well-structured.

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 4 parameters, 1 required, and an output schema, the description covers the core behavior, special case of approval_id, and single-use restriction. It omits edge cases like what happens if limit unchanged but balance affected, but output schema likely covers return. Adequate for an update tool.

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. The description provides a high-level overview but does not add meaningful detail beyond what the schema already describes for each parameter (e.g., card_id, approval_id, etc.).

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 the verb 'Change' with the specific resource 'multi-use card's total spending limit', clearly distinguishing it from siblings like close_card or pause_card. It also explicitly states that single-use cards cannot be resized, further differentiating tool scope.

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 explains when to use the tool (to adjust spending limit), provides context for raising (needs balance, use add_funds if short) and lowering (frees balance, cannot go below spent), and warns against use with single-use cards. However, it does not explicitly compare to other card modification tools.

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?

Description discloses that the tool returns a Stripe Checkout URL the user must open, that the plan updates automatically after checkout, and the default behavior. Annotations (readOnlyHint=false etc.) are consistent and this adds detailed behavioral context beyond annotations.

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?

Description is front-loaded with the action and resources, but includes some redundancy (e.g., 'Defaults to 'basic' if omitted.' is repeated from schema). However, every sentence adds value for the agent, so it's moderately concise.

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 one optional parameter and an output schema, the description fully explains the checkout flow, post-update verification, and when to use it. No gaps for a focused mutation tool.

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 includes the default. The description adds meaningful context about pricing limits per plan, which goes beyond the schema's enum labels, providing extra semantic value for agent decision-making.

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's purpose: 'Start a paid-plan upgrade.' It specifies the target plans (basic and pro) with pricing and limits, and distinguishes itself from the sibling cancel_plan, which is explicitly mentioned.

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 'Use only when the user explicitly wants to upgrade.' Provides alternative (cancel_plan) and instructs to call it by name. Also mentions verifying with get_plan after checkout, giving a clear usage workflow.

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 are minimal (readOnlyHint=false, etc.). The description adds key behavioral context: on success the balance unlocks for funding, verification lasts 60 days, and wrong/expired codes return a recoverable status. However, it doesn't detail the exact structure of the recoverable status or any other side effects.

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, no wasted words. Front-loaded with purpose and immediate usage context. Every sentence provides necessary information without redundancy.

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 tool with an output schema, the description covers input expectations, success/failure behavior, and next steps. It is fully adequate for an agent to select and invoke 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% with one parameter (code). The description adds crucial semantic instruction: 'keep any leading zeros — do not send it as a number'. This exceeds the schema's description, which only says 'as a string'.

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 a one-time code from start_phone_verification. It distinguishes itself from siblings by naming start_phone_verification and add_funds as related but distinct actions.

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 use (after start_phone_verification, before add_funds), what to do on success (call add_funds), and how to handle failure (ask user to re-check or resend). Provides clear contextual guidance.