Palmyr

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

With no annotations provided, the description carries full burden and does an excellent job. It discloses the fee structure (3% min 0.50 USDC), the exact total in 402 instructions, the asynchronous flow (returns 202, requires polling), the non-reloadable nature, and the issuer limit. All critical behaviors are surfaced.

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 serves a purpose: defining the product, explaining pricing and flow, and listing restrictions. It is front-loaded with the core purpose and efficiently structured with no 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?

For a complex async purchase tool with no output schema, the description fully covers the lifecycle: payment instruction, total cost, operation_id, polling, and retrieval via card_get. It also references sibling tool names for the next steps, making the overall flow 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% with both parameters already described. The description adds value by explaining how 'amount' translates to the exact loaded balance and how 'payment' fits into the x402 flow, including the fee calculation. This goes beyond the schema without redundancy.

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 'Buy a USA prepaid Visa card', using a specific verb and resource, and immediately clarifies the exact balance range ($5–$1000). It clearly distinguishes from sibling tools like card_get, card_status, and card_list by focusing on the purchase 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?

It provides explicit instructions: the dynamic pricing formula, the 202 response with operation_id, polling via card_status (~10s), then fetching the card with card_get. It also states constraints (US merchants only, non-reloadable, max 6 per 24h), giving clear context 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly discloses the ownership verification requirement (0.01 USDC proof, paying wallet must be buyer) and the two-step payment flow for accessing sensitive card data. This goes beyond a simple 'get' and informs the agent of important prerequisites and consequences.

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 two well-structured sentences. The first sentence states the purpose and return data, and the second adds the critical ownership proof requirement. No filler or redundancy; 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?

Although there is no output schema, the description explicitly lists the returned fields (card number, CVV, expiry, live balance), covers the payment flow (first call vs. subsequent), and states the ownership verification constraint. For a sensitive financial data retrieval tool, this is comprehensive given the available schema and 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 schema already documents both parameters with 100% coverage, providing a baseline of 3. The description adds meaningful context about the payment parameter by explaining the ownership proof and its relationship to the card buyer, enriching the schema's terse description. This additional context justifies 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 begins with a specific verb+resource: 'Retrieve a prepaid card you own' followed by the exact data fields returned (full card number, CVV, expiry, live balance). This clearly distinguishes it from siblings like card_list (which likely lists cards) and card_status (which likely shows status), 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 for when to use the tool: it is for retrieving a card you own, and it explains the ownership proof requirement. It also gives specific usage guidance for the payment parameter ('omit on first call to receive payment instructions'). However, it does not explicitly mention alternative tools or when not to use this one, so it's strong but not fully explicit.

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

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

With no annotations, the description carries the transparency burden. It discloses the 0.01 USDC ownership proof and the privacy behavior of never returning full numbers, which are valuable behavioral insights beyond the raw purpose.

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 action and resource, followed by necessary caveats. No fluff or 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 simple list tool with one optional param and no output schema, the description covers key aspects: return fields, privacy limitation, and payment requirement. Minor ambiguity around whether the 0.01 USDC is a recurring fee, but overall 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%, so the param is well-documented. The description adds meaning by explaining the payment payload as a 0.01 USDC ownership proof, clarifying its purpose beyond the schema's generic 'payment payload' label.

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 cards owned by the paying wallet, with specific fields (status, last4, balance). It also distinguishes itself from card_get by explicitly excluding full numbers.

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

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

It provides clear context on what the tool returns and mentions card_get for full numbers, giving a strong usage hint. However, it doesn't explicitly state when to prefer this tool over card_status or other 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that polling is free, that done=true only when the purchase is ready or failed, and that a failed purchase triggers an automatic refund accessible via refund_status. This gives the agent clear expectations about the tool's state transitions and 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?

The description is one dense sentence that front-loads the core action ('Poll a card purchase') and efficiently packs in status conditions and next steps. No word is wasted; it achieves high clarity without verbosity.

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

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

For a simple one-parameter polling tool with no output schema, the description covers the essential behaviors: what to poll, when it's done, what the statuses mean, and what to do next (fetch details or check refund). It is complete enough for an agent to use the tool correctly in the card purchase workflow.

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 provides 100% coverage for the single parameter card_id, including its origin from card_buy. The tool description reinforces this by referencing card_buy, but does not add new semantic meaning beyond the schema. Hence, 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 polls a card purchase started by card_buy, using the specific verb 'poll' and the resource 'card purchase'. It differentiates from sibling tools by framing this as the status-checking step between purchase and detail retrieval (card_get).

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

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

It explicitly specifies when to use this tool: after card_buy, to monitor completion. It also provides workflow guidance: when done with status 'ready', use card_get for details, and when 'failed', see refund_status for auto-refund information. This effectively distinguishes it from alternatives.

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

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

With no annotations provided, the description carries the full burden. It discloses wallet keying, optional installs, and the two-step x402 payment flow via the 402 challenge. This is significant behavioral context that goes beyond what the schema alone provides.

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 two compact sentences, front-loaded with the core action, and includes essential payment and installation details without any redundant wording.

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 core deployment purpose, wallet ownership, optional installations, and the crucial x402 payment flow. It does not explicitly explain return values or mention location/SSH key specifics, but given the tool's complexity and absence of annotations, it is quite 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 description enriches parameter meaning by explaining install as auto-installing OpenClaw/skills and linking serverType to per-type pricing. Although schema coverage is 71%, the description adds value for payment and install, though location and sshPublicKey remain undocumented.

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 'Deploy a cloud VPS' with a specific verb and resource, adding wallet keying and optional OpenClaw/skills installation. It uniquely distinguishes this tool from all siblings, which are unrelated (email, phone, social media, etc.).

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 the tool is for deploying a VPS and includes payment workflow hints (402 challenge, x402), giving clear context. It does not explicitly name alternatives or exclusions, but no sibling tool competes with this functionality.

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

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

With no annotations, the description carries the burden and partially fulfills it by disclosing that the operation is free ('no payment required') and that a bare name triggers scanning of popular TLDs. It does not explicitly state that the tool is read-only or describe side effects, but the verb 'check' strongly implies a non-destructive action.

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 two sentences, front-loaded with the primary purpose and followed by usage and cost details. Every word contributes to understanding, with no filler or repetition.

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 single parameter and no output schema, the description sufficiently covers input format, behavior (scanning TLDs), and cost. It hints at the output via 'per-TLD pricing' but does not detail the exact return structure or error cases, which is a minor gap for a simple check 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?

The input schema already provides 100% coverage for the 'domain' parameter, and the description essentially repeats the schema's phrasing ('A full domain or a bare name'). No additional semantic value is added beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose with a specific verb ('check') and resource (domain availability), and adds the distinguishing feature of per-TLD pricing. This differentiates it from siblings like domain_register, which handles registration. The input format is also clarified.

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

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

The description gives clear context on how to use the tool by specifying the two acceptable input forms (full domain or bare name) and the behavior of scanning popular TLDs. It does not explicitly exclude alternatives or mention sibling tools, but the relationship to domain registration is implied through the sibling 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?

With no annotations, the description must carry the transparency burden. It discloses a key behavioral trait: pricing is per TLD and payment is handled via a 402 challenge (x402). However, it omits details about what happens after registration, potential errors (e.g., domain already taken), and the two-step call pattern (first call without payment), leaving gaps in the behavioral model.

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 two sentences, front-loaded with the core purpose. The second sentence efficiently explains the payment mechanism, which is essential for correct usage. No unnecessary words or repetition.

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 (two parameters, payment flow) and lack of annotations/output schema, the description adequately covers purpose and payment but misses the return value and the explicit two-step invocation (omit payment first, then include it). The schema hints at the two-step pattern, but the description alone isn't fully self-contained for an agent to know what to expect on success.

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 provides 100% coverage with clear descriptions for both 'domain' and 'payment' parameters. The description adds no parameter-specific information beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states 'Register a domain to your wallet,' specifying the action and resource. It distinguishes from sibling domain_check by focusing on registration rather than checking availability. The payment detail adds specificity without confusing the core 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 provides clear context on when to use the tool: when you intend to register a domain and are ready to handle the x402 payment flow. However, it does not explicitly mention alternatives like domain_check or state conditions when not to use this tool, so it falls short of a 5.

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

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

With no annotations, the description carries the transparency burden. It discloses cost, payment method, and wallet linkage, which is valuable. However, it does not mention side effects like DNS changes for custom domains, potential name conflicts, or that omitting payment returns instructions. It is more transparent than a bare 'Create inbox' but still leaves out key behavioral details.

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 two sentences, front-loaded with the core action, and every sentence earns its place—first the what, then the cost/payment. There is no fluff or repetition of schema fields.

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 primary purpose and cost, but given the tool's complexity (5 parameters, payment flow, no output schema, no annotations), it omits important operational details like the two-step payment flow (omit payment to receive instructions) and domain prerequisites (must be Namecheap-registered). The schema covers some of this, but the description itself leaves gaps for an agent deciding whether to invoke it.

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 description coverage is high (80%), so the schema already explains most parameters. The tool description adds cost context and renames the address pattern, but it does not provide additional parameter-level meaning beyond what the schema offers. 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 a specific action ('Provision an email inbox') with a concrete resource format ('{name}@palmyr.ai or a custom domain you own'). It distinguishes itself from sibling tools like email_create_temp by implying a permanent, wallet-keyed inbox rather than a temporary one.

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

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

The description gives clear context for use: it costs 2.00 USDC, is paid per-action via x402, and is keyed to a wallet. It does not explicitly exclude alternatives or name sibling tools, but it provides enough context for an agent to understand when this tool is appropriate for provisioning a persistent inbox.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It explicitly mentions the cost (0.50 USDC per-action via x402), auto-expiry (default 24h), and the plaintext access for the owning wallet. It also states receive-only, which is a key behavior. It does not cover all edge cases (e.g., payment failure handling, idempotency), but the provided context is substantial and actionable.

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 focused sentences: purpose and ideal use, return value, and behavioral characteristics (expiry, read access, cost). No wasted words; the description is front-loaded with what the tool does and who should use it. Each sentence adds essential information for an agent deciding to invoke the 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?

The description covers key contextual points: use case, return value, expiry, access model, and cost. However, it does not mention the two-step payment flow (first call to receive instructions, second call with payment), which is only in the schema. It also omits any reference to related tools like email_read_messages for consuming the inbox. These gaps prevent a 5, but the description is complete enough for a straightforward create operation with a clearly scoped purpose.

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

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

Schema description coverage is 100%, with both 'payment' and 'ttl_seconds' already documented in the input schema. The description echoes the default TTL (24h) and adds cost context, but it does not materially enhance parameter understanding beyond what the schema provides. Baseline 3 is appropriate given the 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 uses a specific verb ('Provision') and a distinctive resource ('disposable, receive-only email inbox'), clearly distinguishing it from the sibling tool email_create_inbox. The mention of 'temp' and 'auto-expires' reinforces the temporary nature, 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 usage context: 'ideal for receiving a one-off verification or order-confirmation email during a checkout/signup flow.' This implies when to use the tool, but it does not explicitly name alternatives (e.g., permanent inboxes via email_create_inbox) or state when NOT to use it, so it stops short of a perfect 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals the exact effect (pushes expires_at 7 days further, stackable, no cap), ownership requirement, that expired inboxes cannot be revived, and the cost (0.50 USDC via x402). This is strong transparency for a paid mutation tool, though it omits error scenarios or return format.

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 two sentences, front-loaded with the primary action, and each clause adds essential information (duration, stacking, ownership, expiration handling, cost). No wasted words; it reads naturally and is 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?

For a tool with no annotations and no output schema, the description covers the core purpose, constraints (owner-only, expired cannot be revived), cost, and alternative action. It does not describe the response format or what happens on success/failure, but the input schema is simple and the behavioral context is strong.

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 already covers both parameters (inbox_id, payment) with descriptions, so the baseline is 3. The description adds value by explaining the effect of calling repeatably ('stackable, no cap') and tying the payment param to a per-action cost of 0.50 USDC, reinforcing ownership constraints. This goes beyond what the schema states.

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: 'Rent another 7 days on a live disposable temp inbox' with a specific verb and resource. It distinguishes from sibling tools like email_create_temp and phone_extend_temp by focusing on extending an existing temp inbox, and it explicitly mentions 'Owner-only' and the alternative for expired inboxes.

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 for when to use this tool: to extend a live, owned temp inbox by 7 days. It explicitly excludes expired inboxes ('cannot be revived') and directs users to email_create_temp for that case. It does not explicitly list all alternative tools, but the guidance is sufficient for the main use case.

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

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

No annotations are provided, so the description carries the full burden. It discloses the per-action cost (0.02 USDC via x402) and the ownership/payment wallet matching constraint. However, it does not describe pagination behavior, return shape, or error handling, leaving some behavioral traits unspecified.

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 two sentences, front-loaded with the core action, and includes only necessary information (ownership and cost). No filler or redundant details.

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 straightforward read tool, the description covers purpose, ownership, and cost effectively. The schema fills in pagination and payment instructions. It does not explicitly state return format or error conditions, but 'read decrypted messages' implies the return content, making this sufficient overall.

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

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

Schema descriptions already cover all four parameters, providing clear meaning for limit, cursor, payment, and inbox_id. The description adds no extra parameter-specific semantics beyond the schema, so it stays at the baseline.

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 reads decrypted messages from an owned inbox, using the specific verb 'read' and resource 'decrypted messages'. It distinguishes from sibling tools like email_send and phone_read_messages by specifying inbox ownership and message type.

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 usage (read messages from your own inbox) and notes an ownership prerequisite, but it does not explicitly mention alternatives like phone_read_messages or state when not to use the tool. The cost and payment condition are provided but not framed as 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?

No annotations are provided, so the description must carry the burden. It discloses the cost (0.08 USDC) and the payment mechanism (x402), which is valuable. However, it does not describe the two-step payment flow, return behavior, or any side effects beyond sending. This is a minimal but non-trivial disclosure.

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 with no fluff. Every word earns its place, conveying action, scope, and cost clearly.

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 tool has a complex payment flow (omitting payment on first call to receive instructions) that is not mentioned in the description. Without an output schema, the agent gets no guidance on what to expect in return. The description is too brief for a paid, multi-step operation with 6 parameters.

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 only 50%, with body, html, and subject lacking descriptions. The description adds no parameter-level details for these fields, and only indirectly clarifies inbox_id via 'an inbox you own.' It does not compensate for the missing schema descriptions, so parameter semantics are weak.

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 ('Send'), the resource ('an email'), and adds a scoping constraint ('from an inbox you own'). This distinguishes it from email_create_temp and email_read_messages, and the ownership detail implies a prerequisite.

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: you must own an inbox and pay a fee via x402. It implies you need an inbox_id from email_create_inbox, but it does not explicitly list alternatives or when not to use this tool. It gives enough context for an agent to choose this over temp-inbox 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?

With no annotations, the description carries the burden, and it discloses key behavior: the cost per plan, per-action x402 payment, and the output as an ordered list of x402 calls. It does not mention the first-call payment handshake or any side effects, but core behavioral expectations are transparent.

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 core value proposition and followed by essential cost and execution details. Every sentence earns its place and there is no 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 lack of annotations and output schema, the description provides a solid high-level mental model: input intent, output ordered x402 calls, cost and payment model. It does not detail the payment handshake or plan format, but the schema covers the payment parameter, and the overall picture is reasonably complete for an orchestrator 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?

The schema already covers 75% of the 8 parameters, including descriptions for intent, payment, budget_usdc, and allow_budget_exceeded. The tool description adds no per-parameter meaning beyond reinforcing the intent and budget concepts, so the schema does the heavy lifting.

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

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

The description uses a specific verb ('get') and a clear resource ('priced execution plan'), then elaborates that it turns natural-language outcomes into an ordered list of x402 calls. This clearly distinguishes the orchestrator role from sibling tools that perform direct actions like domain_register or email_send.

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 implies when to use it: when the agent has a natural-language outcome that needs to be broken into a sequence of x402 actions. It does not explicitly state when not to use it or mention alternatives for single-action tasks, but the context is clear enough for an agent to select it appropriately.

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

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

With no annotations provided, the description carries the burden. It discloses the read-only nature ('List') and the cost behavior ('Free — no payment required'), but does not clarify whether any auth is needed, what the response structure looks like, or whether there are rate limits. For a simple catalog listing, this is adequate but not rich.

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

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

A single concise sentence that front-loads the action and resource, then adds the cost note. Every word earns its place with no filler or repetition.

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, no output schema, and no annotations, the description covers the essential purpose and cost. It may not detail the return format, but for a catalog list the output is straightforward. It would benefit from clarifying whether it returns names, descriptions, or both, but it remains sufficient for such a simple 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?

The tool has zero parameters, so the baseline is 4. The description adds context about what is listed (capabilities, intent-resolver catalog) even though there are no parameters to document. This fully covers the schema's empty property set.

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 ('List'), the resource ('i402 capabilities Palmyr can plan and execute'), and identifies it as the 'intent-resolver catalog', which distinguishes it from sibling tools that perform actual actions. This is a specific, unambiguous 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 implies usage: if you need to know what capabilities Palmyr can plan/execute, list them. It also notes the tool is free, hinting that other tools may require payment, but it does not explicitly state when to prefer this over alternatives or provide exclusions. No alternatives are named.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tool is free to call and returns live prices, which is transparent for a read-only listing. However, it does not address output format or behavior when no paid capabilities exist.

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 with zero waste, front-loaded with the action and entity. Every clause adds value: paid capabilities, live x402 price, network, and 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?

For a zero-parameter tool with no output schema, the description adequately explains the return value (list of paid capabilities with prices). However, it could be more complete by explicitly differentiating from palmyr_capabilities to aid tool selection.

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 baseline is 4. The description adds context about what the listing includes (paid capabilities, USDC pricing) beyond the empty schema.

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

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

The description clearly specifies the action ('List'), the resource ('every paid Palmyr capability'), and the price context ('live x402 price (USDC on Solana/Base)'). It distinguishes from siblings by focusing specifically on paid capabilities and pricing.

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

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

Implied usage as a pricing lookup, but no explicit guidance on when to use this tool vs sibling palmyr_capabilities or i402_plan. The note 'Free — no payment required' provides a usage hint but no exclusions.

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

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

With no annotations, the description carries the full burden. It discloses the cost (3.00 USDC) and payment method (x402 per-action), which are important behavioral traits. However, it does not explain the payment flow (e.g., initial call without payment), eventual number lifecycle, 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?

The description is two sentences, front-loaded with the main action and cost. Every word contributes, with no fluff or repetition.

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 tool involves a payment flow (schema notes 'omit on first call to receive payment instructions') and no output schema, but the description omits this procedural detail and does not indicate what the response contains. For a 3-parameter purchase tool with no annotations, this is inadequate.

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 covers country and payment with descriptions, but areaCode lacks a description. The tool description does not add any parameter-level meaning, failing to compensate for the missing areaCode semantics. Schema coverage is 67%, but the description provides no additional 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 uses a specific verb ('Provision') and resource ('real phone number (SMS + voice)'), clearly distinguishing it from temporary number sibling tools like phone_temp_number. It also states the purpose ('for your agent') and adds cost context.

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 usage for a real, paid, likely permanent number ('real phone number' and cost), but does not explicitly mention when to use this tool versus alternatives such as phone_temp_number. There is no when-not-to-use guidance, leaving usage to be inferred.

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

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

With no annotations, the description carries the full burden and excels: it discloses stackability ('each call pushes expires_at 30 min further'), a cap ('up to 24h total lease'), ownership restriction, unrecoverable expiration, and the exact cost (0.20 USDC) and payment mechanism. This is comprehensive behavioral disclosure.

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 two concise sentences, front-loaded with the primary action. Every clause adds a specific constraint, behavior, or cost—no filler or 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 this is a simple extension operation with two params and no output schema, the description provides all necessary context: what it does, how accumulation works, exceptions (expired), alternative path, and cost. The agent has enough to decide when and how to invoke it.

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 already provides 100% coverage of both parameters, so the baseline is 3. The description adds context that number_id is a lease id from phone_temp_number, but does not add significant parameter-level semantics beyond what the schema already states.

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 ('Rent another 30 minutes') and resource ('live disposable temp number'), and explicitly contrasts with a fresh lease via phone_temp_number, distinguishing it from the sibling tool.

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

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

It provides clear usage context: 'Owner-only' indicates who can use it, and 'expired temp leases cannot be revived (lease a fresh one via phone_temp_number)' gives an explicit when-not case and alternative. It also mentions the payment method (x402) for each 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?

No annotations are provided, so the description carries the burden of disclosing behavioral traits. It adds valuable context: the per-action cost of 0.02 USDC via x402 and the ownership requirement. However, it does not disclose return format, pagination, or what happens if payment is not provided. The payment flow is partially covered by the schema's payment field description, so a score of 3 reflects that it adds some context but is not rich.

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 with no filler. It conveys the primary action ('Read SMS messages'), a scoping condition ('on a phone number you own'), and a key operational detail (cost). Every word earns its place; appropriately 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?

For a read tool with two parameters and no output schema, the description covers the core purpose, ownership requirement, and cost. It does not explicitly state that the first call may return payment instructions, but the schema's payment field description covers that. The tool is relatively simple, and the combination of description and schema is sufficient for 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?

Schema description coverage is 100%, and both parameters (payment, number_id) have clear descriptions in the schema. The tool description adds no extra parameter semantics beyond the schema. Baseline of 3 is appropriate because the schema already fully documents the 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 states a specific verb and resource: 'Read SMS messages received on a phone number you own.' This clearly distinguishes it from siblings like phone_send_sms (send) and email_read_messages (email). The phrase 'you own' adds a meaningful scoping condition that differentiates from temporary-number 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 implies usage context (reading SMS on an owned number) but does not explicitly state when to use this tool versus alternatives. It mentions a prerequisite ('a phone number you own') but does not name alternative tools or exclusion conditions. The cost and payment mechanism are mentioned, giving some operational guidance, but no direct or indirect comparison with similar 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?

With no annotations provided, the description carries the full burden. It discloses a notable behavioral trait: the per-action cost (0.05 USDC) and payment mechanism (x402), plus the ownership requirement. However, it does not mention delivery status, rate limits, or 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?

A single efficient sentence that front-loads the action, then adds cost information. Every word earns its place; no redundancy or 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?

The description covers essential operational context: action, ownership prerequisite, cost, and payment method. However, it omits the two-step payment flow (first call omit payment) and return behavior, which are not covered by an output schema. Still, for a simple send tool, it is reasonably 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 already provides descriptions for to, payment, and number_id with 75% coverage. The description adds semantic context for number_id by emphasizing ownership, but does not elaborate on body or payment behavior beyond what the schema states. Baseline of 3 is appropriate since schema covers most 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?

Description clearly states the action ('Send an SMS') and resource ('from a phone number you own'), immediately distinguishing it from sibling tools like phone_read_messages or phone_buy_number. The verb+resource construction is specific and 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 implies usage by naming the action, but does not explicitly explain when to use this tool over alternatives or mention prerequisites (e.g., needing a number_id from phone_buy_number). It lacks explicit when-not-to-use or alternative guidance.

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

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

With no annotations, the description fully discloses behavioral traits: the number is receive-only, costs $0.20 USDC via x402, has a TTL clamped between 300 and 1800 seconds, is returned to the pool at expiry, and is recycled after lease. It also mentions compatibility limitations and the one-time-use restriction, which is comprehensive for a tool with zero annotation coverage.

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 purpose, then covers behavior, usage guidance, limitations, and cost. It is somewhat long with slight redundancy (cost mentioned twice: '$0.20 for 30 min' and 'Costs 0.20 USDC'), but each sentence contributes meaningful 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?

The description covers purpose, cost, payment, usage, compatibility, and limitations, and points to wait_for_otp for catching the code. It does not explicitly state the tool's return value (the phone number), but that is strongly implied by 'lease a phone number'. Given no output schema, this is a minor gap, but otherwise the description is highly 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% (both payment and ttl_seconds have detailed descriptions). The description reinforces ttl_seconds clamping and connects it to the $0.20/30min cost, but this adds only marginal value beyond the schema's own parameter documentation.

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 leases a cheap, instant, receive-only US phone number from a pool to receive one SMS verification code. It distinguishes itself from phone_buy_number (dedicated number) and references wait_for_otp, making its role 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?

It explicitly says the tool is good for one-time SMS verification and phone-gated signups, warns that Telegram, WhatsApp, and OpenAI may reject VoIP numbers, and directs users to phone_buy_number for strict sites. It also cautions against using pooled numbers for long-term 2FA, 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?

No annotations are provided, so the description carries the full burden. It adds useful behavioral context: the operation is a read (list) and costs 0.001 USDC per action via x402. However, it does not disclose the payment flow (e.g., first call may return payment instructions without data) or whether the response is paginated, though the schema partially covers the payment payload. The cost disclosure is a positive, but more behavioral detail (e.g., idempotency, auth assumptions) would be beneficial.

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, focused sentence that front-loads the primary action and includes only high-value context (session health fields, cost). No filler or 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 is a simple list operation with 2 optional parameters and no output schema, the description provides sufficient context: it lists the key return fields (status, profile_present, hours_since_success, last_error_code) and mentions cost/payment. It could be improved by specifying the response shape (e.g., array of account objects) and the 'first call for payment instructions' behavior, but the schema covers the payment parameter. Overall, it is mostly 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% for both parameters ('tag' and 'payment'), so the schema fully documents their purpose. The description adds only indirect reference to x402 via the cost statement, but does not elaborate on the parameters themselves. The baseline of 3 applies because structured data already handles parameter semantics.

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

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

The description clearly states the action ('List') and resource ('TikTok accounts the paying wallet owns'), with explicit detail on what is returned (session health fields). It differentiates from siblings like tiktok_connect (which likely adds an account) and tiktok_connect_status (which checks connection status) by focusing on listing owned accounts with login health.

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 the primary use case: checking which owned accounts are still logged in ('i.e. which of your accounts are still logged in'). It also mentions cost and x402 payment method, indicating when a payment is required. However, it does not explicitly name alternative tools or exclusions, so it provides clear context without formal 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?

With no annotations provided, the description carries full burden and does an excellent job: it discloses the async nature (returns an operation to poll), the per-action cost of 0.005 USDC via x402, and the side-effect of recording a sample for tiktok_series. It also clarifies authentication nuance (omit cookies if connected via tiktok_connect), which is beyond the schema.

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

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

Three sentences, no filler. The first sentence states what it does, the second explains async behavior, and the third covers cost. All information earns its place and 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?

Given the tool's complexity (async, payment, auth modes, integration with tiktok_series), the description covers all major operational aspects: purpose, return value (operation to poll), cost, and cookie handling. No output schema exists, but the description tells the agent how to follow up, which is 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 60%, so the description adds meaningful context on top. It explains that cookies should be omitted for a connected account (matching the schema's own note), and that payment is omitted on first call to receive instructions. While country and proxy_session_id lack descriptions, the description's clarification of the tricky parameters elevates it above baseline.

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 scrapes per-post analytics (views, likes, comments, shares) for a TikTok account you control, and also records a sample for tiktok_series. The verb 'scrape' and resource 'per-post analytics' are specific, and it distinguishes itself from sibling tools like tiktok_post or tiktok_connect by focusing on analytics and series integration.

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 context on when to use it (for accounts you control) and its relationship to tiktok_series, as well as the async polling pattern via tiktok_operation_status. However, it doesn't explicitly state when NOT to use it or name alternative tools, so it lacks exclusionary 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?

No annotations are provided, so the description carries the full burden. It discloses that TikTok has no unschedule, so the video is deleted; that cancellation is only recorded after success; that it is asynchronous; and that it costs 0.001 USDC. This is rich 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 three sentences long, front-loaded with the purpose, and includes only essential details about behavior, async handling, and cost. 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 async behavior, payment requirements, and no output schema, the description covers all critical aspects: why the video is deleted, how cancellation is confirmed, where to poll, and the cost. It is complete enough for an agent to use the 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 67% (4 of 6 parameters have descriptions), but the description itself adds no new parameter semantics beyond what the schema already provides. Parameters like country and proxy_session_id remain unexplained, and the description does not compensate for this gap.

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 ('cancel') and the target resource ('a post queued with tiktok_post(schedule_at)'). It differentiates from related tools by referencing tiktok_post and tiktok_operation_status, making it specific and 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 for when to use this tool (to cancel a scheduled post) and references the polling tool for async results. It does not explicitly list exclusions or alternatives, but the context is sufficient to distinguish it from 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?

With no annotations, the description carries full burden. It discloses critical traits: server-side login, persistent browser profile, async nature, cost (0.01 USDC via x402), and that 'the paying wallet becomes the account's owner'. It also notes the browser-authenticates-acts coupling. It omits details like timeout or failure modes, but is generally transparent about side effects and prerequisites.

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 of about 80 words, front-loaded with the main action 'Attach a TikTok account'. Each sentence adds a new facet: the flow, the rationale, ownership, async polling, and cost. There is no fluff or repetition, making it highly concise while covering essential 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?

This is a complex tool (async, cost, ownership transfer) and no output schema is provided. The description covers the flow, next steps, and cost, and mentions the return of a connect_url and token. It lacks explicit output structure details and error/timeout handling, but given the complexity, it provides a solid foundation. The guidance to poll tiktok_connect_status helps complete the workflow.

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 80% (4/5 params have descriptions), so baseline is 3. The description does not add parameter-specific meaning beyond the schema; it only mentions the connect_url and token output, not details about parameters like proxy_session_id (which is undocumented). This is acceptable given the schema coverage, but no extra value is added.

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+resource: 'Attach a TikTok account by logging in ON THE SERVER'. It clearly distinguishes itself from siblings by detailing the server-side login and persistent browser profile, which is the foundation for other TikTok tools. It also explains the return value (connect_url) and the overall flow, making its purpose unmistakable.

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 is 'the recommended path' and explains why, as the authenticating browser will later act and other TikTok tools work without cookies. It also gives sequential guidance to poll tiktok_connect_status with the returned token. However, it does not explicitly name alternative tools or state when NOT to use it, leaving some room for interpretation.

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

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

With no annotations provided, the description carries the full burden. It discloses that done=true when state is 'completed' (with cookies omitted) or 'failed', which is useful. However, it does not describe the full response structure, other possible states, or error handling, leaving gaps in behavioral expectations.

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 states the action, the context, and the key completion condition without any fluff or repetition. It is 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?

Since there is no output schema, the description needs to explain return values. It only covers the condition for done=true, but not the full response structure or the behavior when done=false. While the tool is simple, the description is not fully complete without this information.

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 has 100% coverage, with the token parameter clearly described as 'Connect token returned by tiktok_connect'. The tool description reinforces this by mentioning 'started by tiktok_connect', but adds no further semantic detail 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 uses the specific verb 'Poll' and identifies the resource as 'a server-side login started by tiktok_connect'. It clearly distinguishes the tool from siblings by referencing its counterpart and explaining the done condition.

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 this tool is used after tiktok_connect to check login status, providing clear context for when to use it. However, it does not explicitly state alternatives or exclusion scenarios, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden. It discloses pricing per mode, x402 payment flow with the 402 challenge carrying exact price, and the constraint that account and niche analyses are never blended. This goes beyond basic safety and adds meaningful operational 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 four sentences, front-loaded with the core purpose. Every sentence adds concrete information—modes, pricing, payment, and exclusions—without fluff or redundancy. It is dense but 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?

The description covers the main use cases, pricing, and payment flow, which is substantial for a tool with 7 parameters and no output schema. It does not specify return format, but given the descriptive nature, it provides enough context for correct invocation. Minor gaps remain around error handling or prerequisites, but these are not critical.

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 semantic value by clarifying which parameters are alternative modes (account_id/tag vs niche) and the purpose of caption classification. It also links pricing to specific parameter choices. While it does not detail recency_days and maturity_days, these are already well-covered in 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 analyzes caption openings that earn views. It distinguishes three distinct modes (account/tag, niche, caption classification) with specific verbs and outcomes, and differentiates from siblings like tiktok_niches and tiktok_analytics.

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 explains when to use each mode: account_id or tag for measuring one's own accounts, niche for niche-wide reporting without posting history, and caption for draft classification. Also notes the two main modes are never blended and references tiktok_niches as a free listing of niches.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It discloses that the tool is free to use, which is valuable cost-related behavior. It also highlights that it reports freshness of each corpus, giving context about the data quality. This goes beyond a bare 'list' statement.

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 two sentences, extremely concise, and front-loaded. The first sentence conveys the core function; the second adds a critical cost directive. 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 zero-parameter, no-output-schema tool, the description is sufficiently complete. It specifies what is listed (niches) and includes freshness information. The reference to tiktok_hooks provides contextual linkage. It could have stated output format, but for a simple list tool this is not a significant 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 input schema has zero parameters, so the baseline for this dimension is 4. The description adds no parameter-specific details because there are none, but it does not need to compensate for any schema gaps since there are no 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 function: 'List the niches tiktok_hooks can report on, with how fresh each corpus is.' It uses a specific verb ('List'), names the resource ('niches'), and ties it to a sibling tool ('tiktok_hooks'), which distinguishes it from other listing 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 implies usage: an agent should call this to discover available niches before using tiktok_hooks. The second sentence, 'Free — an agent should not pay to learn what it may ask for,' explicitly advises using this free tool instead of paying elsewhere, which serves as a clear usage guideline.

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

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

With no annotations, the description carries the full burden. It discloses key behavior: done=true when status is 'posted'/'done' (carrying video_url or result) or 'failed' with payment auto-refunded and refund_status. It lacks details on polling frequency or error handling, but the provided semantics are valuable.

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, compact sentence that front-loads the action ('Poll') and packs essential status/refund details without fluff. Every clause 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?

For a simple polling tool with one required parameter and no output schema, the description adequately explains the result semantics (done=true and status meanings). It could mention that polling should be repeated until done, but the 'done=true' flag implies this. Overall 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 coverage is 100% with operation_id described as 'returned by the tool that started the operation.' The description adds the specific list of starting tools (tiktok_post, tiktok_analytics, tiktok_cancel_scheduled), giving more precise guidance than the 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?

The description clearly states it polls an async TikTok operation and names the specific tools that start such operations (tiktok_post, tiktok_analytics, tiktok_cancel_scheduled). This distinguishes it from siblings like tiktok_connect_status or tiktok_analytics.

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 it: after starting an async TikTok operation via the listed tools, to poll for completion. It does not explicitly contrast with alternatives, but the scope is clear and the mention of 'free' adds practical context.

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

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

With no annotations, the description carries a significant burden and it discloses key behaviors: the operation is asynchronous ('returns an operation to poll'), it costs 0.01 USDC via x402, and it can be immediate or scheduled. It does not detail schedule constraints or payment mechanics, but these are covered in the parameter descriptions, so the description adds meaningful transparency without being exhaustive.

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 serving a distinct purpose: stating the core action and input methods, explaining the async behavior, and disclosing the cost and payment method. It is front-loaded with the primary purpose and contains no fluff or 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 (10 parameters, no output schema, no annotations), the description provides essential operational context: async polling, payment, and scheduling modes. The parameter descriptions in the schema fill in many gaps, but the description itself could be more explicit about the contents of the returned operation and the required account setup. Still, it is largely complete for an agent to understand the tool's role and flow.

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 60%, and the description itself adds minimal parameter-level detail beyond summarizing the two video input methods (video_base64 and video_url), which the schema already describes. It does not clarify ambiguous parameters like country, privacy, or proxy_session_id, so it does not significantly enhance parameter understanding 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's action: 'Post a video to a TikTok account you control (from video_base64 or video_url), immediately or scheduled.' It uses a specific verb ('Post') and resource ('TikTok account'), and distinguishes it from siblings like tiktok_connect, tiktok_scheduled, and tiktok_analytics, which serve different purposes.

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 for when to use the tool (posting a video to TikTok) and mentions the async operation to poll with tiktok_operation_status, guiding the agent on subsequent steps. However, it does not explicitly state exclusions or contrast with alternatives like tiktok_scheduled or tiktok_cancel_scheduled, so it falls short of a 5.

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

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

With no annotations provided, the description fully carries the burden. It discloses that it reads Palmyr's own record, not TikTok's authoritative state, and explicitly mentions the 0.001 USDC cost via x402. These are crucial behavioral details beyond the basic 'list' operation.

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 earning its place: the core purpose, the data-source caveat, and the cost. No fluff, and the most important information 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?

Despite lacking an output schema, the description conveys return semantics (statuses pending, due, published) and covers critical operational details (cost, data-source limitation). Combined with complete parameter documentation, this is fully adequate for an agent to use the 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?

The schema describes all three parameters (payment, account_id, include_done) with 100% coverage, so the description doesn't need to add much. The description adds context about the schedule_at relationship but doesn't elaborate on the parameters themselves, which is acceptable given the schema's completeness.

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 lists queued TikTok posts with their status (pending, due, published). It explicitly references tiktok_post(schedule_at) as the source of queued posts, distinguishing it from sibling tools like tiktok_cancel_scheduled and tiktok_post.

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

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

The description gives clear context on when to use this tool (to view Palmyr's scheduled posts) and warns that edits made directly in TikTok Studio are invisible, implying users should rely on this tool for Palmyr-managed schedules. It does not explicitly name alternative tools, but the context is strong.

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

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

With no annotations, the description carries the full burden. It discloses read-only behavior, data provenance, per-action cost, and payment method via x402. It doesn't cover edge cases like empty results or rate limits, but covers the most important behavioral aspects.

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 convey purpose, three modes, data provenance, cost, and payment method without any wasteful words. The structure front-loads the main action and resource.

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 output schema, it explains the three query modes and data availability constraints. It could detail the output format more, but for a simple read tool, it covers the essential context adequately.

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 combinational semantics beyond individual parameter descriptions: video_id yields full series, hours yields growth, neither yields latest sample. This clarifies how parameter combinations behave, adding significant 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 tool reads stored per-post history for an owned account, and explicitly lists three modes (video_id for full series, hours for growth, neither for latest sample). It distinguishes from tiktok_analytics by noting history comes from analytics runs.

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

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

It provides context on when to use the tool: history exists only for what has been scraped by tiktok_analytics. It also explains how to select the desired mode via parameters. However, it does not explicitly name alternative tools for exclusion, making it clear but not fully explicit.

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

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

With no annotations, the description carries the burden of disclosing behavioral traits. It mentions the cost (0.001 USDC) and authentication method (session cookies), which is helpful. However, it does not disclose the two-step payment flow (first call returns instructions) or potential failure modes, leaving a moderate 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 only two sentences, with the primary action front-loaded. It is lean and readable with no filler, scoring high on conciseness.

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 gives necessary high-level context (action, auth, cost) but omits details about the payment progression and the optional parameters. Given the tool's moderate complexity and lack of output schema, the description is adequate but not 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?

Schema coverage is 67% with 4 of 6 parameters described. The description adds minimal meaning beyond the schema, only reinforcing 'session cookies' and adding cost context. It does not help clarify the undocumented parameters community_id and proxy_session_id, which remain opaque.

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 posts a tweet to X (Twitter) using session cookies, distinguishing it from sibling posting tools like tiktok_post. The verb 'Post' and resource 'X account' are specific and 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 useful guidance by noting the account must be controlled via injected session cookies and that payment occurs per-action via x402, implying this is for authorized posting. While it doesn't explicitly exclude alternatives, the X-specific context and payment model give clear usage contours.

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

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

With no annotations provided, the description fully discloses behavior: blocking behavior, timeout defaults, polling interval, lookback behavior, extraction logic, pattern failure handling, and cost (0.02 USDC). It also clarifies that a timeout returns found:false and is not an error. This is comprehensive behavioral transparency.

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 serves a purpose: purpose, behavior, lookback semantics, pattern override, return format, and cost. It is front-loaded with the primary function and efficiently covers all necessary details 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 (5 parameters, no output schema), the description is remarkably complete. It explains return values (found/code/message_text vs found/waited_s), error semantics, timeout limits, cost, and edge cases. No significant behavioral aspect is left unexplained.

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?

Although schema coverage is 100%, the description adds significant semantic value beyond the schema: it explains parameter defaults, the meaning of lookback_s (early arrival matching), the impact of pattern failures (pattern_timeout), and the payment flow. This contextualizes parameters in a way the schema alone cannot.

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 waits for an SMS OTP and returns the parsed code, distinguishing it from sibling phone_read_messages by framing it as a replacement for hand-rolled polling. The verb ('wait'), resource ('SMS verification code'), and outcome ('return the parsed code') are all specific and clear.

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 when-to-use guidance: 'during account signups and 2FA flows,' and identifies the alternative (phone_read_messages). It also gives concrete usage nuances for lookback_s and pattern overriding, including edge-case handling for reused numbers. This goes beyond general context to actionable direction.

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