marutap

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds meaningful consequence detail: canceling spends no money and permanently prevents future merchant charges. This clarifies the real-world effect beyond the flags, though it never states what happens on a repeat call or an already-cancelled mandate.

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 short sentences, action first, effect second. No filler and nothing repeated from the annotation block.

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

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

For a one-parameter mutation tool with annotations covering safety and idempotency, the description conveys action, permanence, and no-spend behavior. The remaining gap is where mandate_id comes from, which is not explained anywhere given the empty schema descriptions.

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 0% for the single mandate_id parameter, and the description only implies that it identifies a subscription mandate. It gives no format, source, or lookup hint, so it fails to compensate for the schema gap, though the parameter's purpose is at least inferable.

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

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

States a specific verb and resource ('Cancel a subscription mandate'), which is clearly distinct from siblings like request_subscription, list_subscriptions, and request_payment. It does not explicitly name an alternative tool, but the action and target are 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?

No guidance on when to use this versus list_subscriptions (to find the mandate) or how to obtain a mandate_id. There are no stated prerequisites or exclusions, leaving the agent to infer the workflow.

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

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

Goes well beyond the annotations (readOnlyHint/destructiveHint=false only cover the safety profile): it discloses the long-poll timeout behavior via wait_seconds, the complete status enumeration including failure states, that a single-use `card` locked to the purchase is returned on approval, and that the first approval yields a `connect_token` to be persisted and sent as a Bearer on all future calls. This is exactly the kind of auth and lifecycle context an agent needs to drive the flow correctly.

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

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

Front-loads the core purpose and the status list, then the claim-specific and connect_token instructions. Content is dense and mostly earns its place, though the status enumeration and the connect_token instructions sit in separate paragraphs that could be tightened slightly.

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

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

With no output schema, the description must explain returns, and it does: it enumerates every possible status value and calls out the conditional `card` and `connect_token` fields. Combined with the polling-loop guidance and auth instruction, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: charge_id is identified as the 'clm_…' poll_id from request_payment for claims, agent_secret is explained as the secret received for a claim, and wait_seconds is tied to the long-poll duration. All three parameters gain meaning not present in the bare schema.

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

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

States a specific verb and resource ('Poll for the outcome of a payment request') and immediately names the result states, making it unmistakable against siblings like request_payment. An agent can tell this is the read-side counterpart to request_payment without opening either schema.

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

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

Explicitly says to call again while the status is pending/claim_pending and references the upstream sibling by name ('the clm_… poll_id from request_payment'), which gives the agent a clear routing context. It stops short of stating when not to use it or naming alternative siblings, so it is strong but not a full when/when-not/alternatives statement.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral details: each item includes a status field with enumerated values (pending, approved, settled, declined, expired), and pending requests include an approval_url to re-surface to the user. This adds context beyond the annotations without contradicting them.

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 well-structured and front-loaded with purpose, then usage guidance, then parameter docs. Every sentence earns its place; there is no filler. The parameter explanations are compact and precise.

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 two optional parameters and no output schema, the description provides sufficient information: the purpose, what each response contains (status, approval_url), and the routing to get_payment_result. It doesn't detail the exact response shape, but the described fields are enough for an agent to interpret results. Minor gap: no mention of pagination beyond 'newest first' and a cap, which is acceptable for this scale.

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 0%, so the description carries the full burden for parameter meaning. It thoroughly explains both parameters: status ('open' default vs 'all') and limit (default 20, capped at 100, newest first). This fully compensates for the schema's bare type/default definitions.

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

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

The description opens with a specific verb and resource: 'List this agent's payment requests and whether each has been approved yet.' This clearly distinguishes it from siblings like get_payment_result (single charge) and request_payment (creation). The agent can immediately tell what this tool does without ambiguity.

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

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

Explicit guidance is given: 'Use this to see the state of every request you've made — not just poll one saved charge_id.' It also directs the agent to a sibling tool for post-approval: 'once a request is approved, call get_payment_result(charge_id) to fetch the card.' This fully covers when to use this tool versus 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that results include status, with no note on scoping to the authenticated user's mandates versus any other account.

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 front-loaded sentence with no filler. 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?

For a zero-parameter read tool with full annotation coverage and no output schema, the description is nearly complete. It only lacks detail on the returned status values and whether results are paginated, which is minor for this shape of 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 takes zero parameters, so the baseline of 4 applies. There is no argument semantics to explain beyond what the description already implies about scope.

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

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

States a specific verb (List) and resource (the user's subscription mandates) plus the status field returned. It is distinguishable from write-oriented siblings like cancel_subscription and request_subscription, though it doesn't explicitly name any alternative.

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

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

No guidance on when to use this versus the sibling tools (cancel_subscription, get_payment_result, request_subscription). The implied 'read your current subscriptions' usage is inferable from the verb but never stated.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so safety is covered. The description adds real value beyond them by explaining the operational intent: this links a charge to the merchant's reference so a later refund is possible, which tells the agent the write is a bookkeeping association, not a fund movement.

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 short sentences; the primary action and its purpose come first, followed by a compact parameter clarification. Nothing is padding.

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

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

With no output schema and a trivial two-parameter input, the description covers purpose, timing, and one parameter. The unexplained charge_id and the absence of any note on what happens if the same order is recorded twice (beyond the idempotent annotation) leave a visible 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?

Schema description coverage is 0%, so the description must compensate, and it does explain order_ref well (merchant payment id, e.g. Stripe PaymentIntent). But charge_id, the other required parameter, is never explained, leaving half the inputs 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?

States a specific action (record the merchant's order reference) and its trigger point (after checkout), which is enough to distinguish it from siblings like request_payment or cancel_subscription. It's clear but doesn't explicitly contrast with any 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?

The phrase 'after checkout' implies the timing/context for use, and the refund rationale hints at why it matters. However, there is no explicit statement of when not to use it or which alternative to pick if the order has not been paid.

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

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

Annotations mark it non-read-only and open-world but say nothing about return shapes or workflow. The description goes well beyond them by documenting the two concrete return payloads (auto_approved false with approval_url vs. true with card/status), the follow-up call, and the auto-approval condition. That is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the core action, then the two return branches, then args. Slightly longer than minimal but each sentence explains a distinct branch or parameter; little waste.

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 non-idempotent, open-world payment-initiation tool with no output schema and no schema parameter descriptions, the definition supplies the return shapes, the workflow handoff, and all parameter semantics. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 0%, so the description carries the full burden. It documents all four parameters including units for amount (major units, with a dollar example), the purpose of merchant, the exact shape of line_items, and the default for currency. This fully compensates for the missing schema descriptions.

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

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

States a specific verb (request approval to pay) and resource (purchase payment), and distinguishes itself from siblings by naming get_payment_result as the follow-up step. An agent can immediately tell this initiates a payment flow rather than recording or querying 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?

Explicitly describes both branches: the normal case where approval_url must be shown and then get_payment_result called, and the auto-approval case where the card is used directly. This is a complete when/how guide for this tool's role in the workflow.

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

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

Beyond the annotations (non-read-only, open-world, non-idempotent), it discloses meaningful behavioral traits: a user approval round-trip yielding an approval_url, a merchant-locked mandate, a hard per-period cap, and user-initiated cancellation that permanently blocks future charges. This is exactly the operational context an agent needs before invoking a money-moving tool.

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

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

The purpose and the two key constraints are front-loaded in the first two lines, followed by a compact Args block. Every sentence earns its place 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?

With no output schema, the description correctly describes what the call returns (an approval_url) and the lifecycle of the resulting mandate, and it documents all three parameters. Nothing an agent needs to select or invoke the tool correctly is missing.

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

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

Schema coverage is 0% and the schema even lacks an enum for interval, so the description carries the full load: it defines merchant, clarifies cap as 'max amount per period in major units' with a decimal example, and enumerates the allowed interval values ("weekly" | "monthly" | "yearly"). This meaningfully exceeds the bare schema titles.

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

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

States a specific verb and resource ('Set up a recurring subscription mandate') and immediately scopes it with a concrete example ('Netflix at up to $16/month'), which distinguishes it from one-off siblings like request_payment and record_order. An agent can tell what this does without opening the schema.

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 gives clear context — this is for recurring, capped, merchant-authorized charges — and states the prerequisite that the user must explicitly approve, returning an approval_url. It does not explicitly name an alternative (e.g. request_payment for one-time charges) or state when-not-to-use, so it stops 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.