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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description adds genuinely new behavior — the two cancellation timings and the `409 subscription_canceled` outcome for repeated calls — but says nothing about reversibility, reactivation, proration, or what the call returns.

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 opening sentence is a verbatim duplicate of the title, which is pure waste, and the parenthetical restates the same idea a third time. The remaining content is compact and front-loads the mode choice correctly, but the redundancy costs it.

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

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

For a destructive mutation tool with no output schema, an agent would benefit from knowing what a successful cancellation returns (canceled object, effective date, whether the subscription becomes read-only). The description covers the two timing modes and the error case but leaves that return/effect picture incomplete.

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%, and the description reinforces the meaning of `at_period_end: true` beyond the schema's one-line note. However, the `reason` parameter is undocumented in both the schema and the description, so the description does not fully compensate for the coverage 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 names a specific verb and resource ('Cancel a subscription') and immediately distinguishes the two modes of cancellation. It is clearly separable from siblings like get_subscription, list_subscriptions, and create_subscription, though that separation comes from the verb itself rather than any explicit sibling differentiation.

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

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

It gives real conditional guidance: use `at_period_end: true` to cancel at the end of the period versus immediately by default, and it documents the 409 error for re-canceling. It does not mention alternatives (e.g., plan changes via update_subscription) or when not to cancel, so usage context is implied rather than complete.

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 flag destructiveHint=true and readOnlyHint=false, so the description adds real value on top: the downstream effect (account stops receiving money), the guard error for dynamic accounts, and the no-op behavior for already-closed accounts returning unchanged. It doesn't say whether closure is reversible or what the response body contains, which keeps it below a 5.

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?

Short and front-loaded, with the error case and the idempotent no-op placed where an agent will read them. The first sentence merely restates the title before the useful sentence that follows, a small redundancy.

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

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

For a destructive, no-output-schema mutation, it covers the effect, the failure mode, and the already-closed case, which is most of what an agent needs. It omits any return-value indication and why `reason` is required, leaving a slight 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 coverage is 67%; `id` and `idempotency_key` are documented in the schema, but `reason` has no description anywhere. The description adds no meaning about any parameter, so it neither compensates for the gap nor adds beyond the schema — baseline 3.

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

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

States a specific verb and resource ("Close a dedicated virtual account") and immediately defines the effect: it stops receiving money. The qualifier "dedicated" separates it from dynamic accounts and from the create/list/get virtual account siblings.

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

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

Gives a clear when-not rule: dynamic accounts can't be closed this way and are closed by their payment, with the exact error surfaced (`400 invalid_operation`). It lacks an explicit named alternative tool for the dynamic case, but the routing condition is unambiguous.

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

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

Annotations only declare it is a non-read-only, non-destructive, non-idempotent, closed-world call. The description adds substantial behavior: the payment is created only when the customer opens the page, the session expires after `expires_in` (default 1h, max 3h, 3h cap for one-time bank accounts), completes on `checkout.session.completed`, and returns 409 duplicate_reference on reused references. It notably warns that redirect/callback is not proof of payment and must be confirmed via webhook or session retrieval — a genuinely useful caveat not implied by the annotations. It does not mention the idempotency_key retry semantics.

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 action, then the two integration paths, then lifecycle, then the confirmation caveat — a sensible ordering. It is dense and slightly redundant (the first line restates the title, and the opening is then repeated as 'Create a checkout session'), and a few sentences pack multiple clauses that could be split for scanability.

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

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

With no output schema, the description carries the return-value burden and does so by naming the `url` and `token` response fields and explaining what each is for. Combined with expiry rules, the completion event, the duplicate_reference error, and the payment-confirmation caveat, an agent has everything needed to create a session and tell the user how to finish the 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 coverage is 75%, so most parameters are already documented. The description adds non-obvious semantics beyond the schema: why `expires_in` is capped (one-time bank accounts last up to 3 hours), the per-mode uniqueness constraint on `reference` and how to retrieve the session by it, and the fact that `amount` is the amount that will actually be charged at session open time. It says nothing about `split`, `metadata`, or `customer`, leaving those to 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?

States a specific verb+resource (create a checkout session) and immediately distinguishes it from adjacent resources by describing the two consumption modes (redirect to `url` vs `token` in the Pletopay popup). This separates it from siblings like create_payment and create_payment_link without requiring the schema to be opened.

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?

Gives concrete integration guidance: use `url` for hosted redirect, or hand `token` to the front end with the browser SDK and publishable key. Also states when to supply `reference` (uniqueness per mode, retrievable via a specific endpoint). It does not explicitly say when to prefer this over create_payment_link or create_payment, so it stops short of full alternative routing.

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 generic mutation and safety annotations, it discloses that every field may be omitted and that a duplicate email produces the concrete `409 customer_exists` failure. It does not explain other side effects or success behavior, but the uniqueness rule is actionable 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 definition is short and front-loads the operation, rationale, optionality, and conflict behavior without unnecessary detail. Repeating 'Create a customer' at the start of both paragraphs is mildly redundant.

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 relatively simple six-field creation operation, the purpose, optionality, duplicate-email behavior, and schema-level idempotency guidance are sufficient for a correct basic invocation. Remaining gaps include the unexplained phrase 'in this mode' and the absence of an explicit existing-customer 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 description adds meaningful semantics for email through its mode-scoped uniqueness constraint and states the global optionality of all fields. With only 33% schema description coverage, it does not fully compensate for undocumented fields such as name, phone, and metadata.

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

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

The description clearly identifies the operation as creating a customer and explains the record's role in issuing virtual accounts, invoices, and subscriptions while grouping payments. It does not explicitly distinguish the operation from siblings such as update_customer or list_customers.

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 downstream uses provide clear context for when a customer record is useful. However, there is no explicit when-not guidance or instruction to find and reuse an existing customer rather than create another one.

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 it usefully discloses two behaviors: totals are server-computed and the result is an editable draft rather than a payable invoice. However, it says nothing about retry behavior, even though idempotentHint=false while the schema exposes an idempotency_key — an agent could reasonably worry about duplicate invoices and gets no guidance here.

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

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

Four short sentences, front-loaded with the action and followed by the mechanics and lifecycle. The only waste is the first line repeating the title verbatim before the more informative second sentence.

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 nested-object mutation tool with no output schema, the description covers the core concept but omits what comes back (draft/invoice id), the currency assumption behind unit_amount, and handling of the split rule. Adequate to start a call, not sufficient to call confidently.

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 38%, so the description needs to carry weight, yet it only restates the taxes basis-point convention (already documented on the 'bps' property) and otherwise lists 'customer, line items, optional taxes'. It adds nothing on due_date, split, metadata, idempotency_key, or the kobo unit of unit_amount.

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 ('Create a draft invoice') and adds the qualifying scope 'draft' versus the later finalized/payable state. Combined with the customer + line items framing, an agent can distinguish it from finalize_invoice, update_invoice and the other invoice siblings 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?

The sentence 'A draft can be edited; finalize it to make it payable.' gives clear lifecycle context and implicitly routes the agent to finalize_invoice as the follow-up step. It stops short of explicit when-not-to-use guidance (e.g. use update_invoice to modify an existing draft, not this tool).

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

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

The description carries substantial behavior beyond the annotations: it discloses the side effect (a dynamic virtual account is provisioned and expires with the payment), specific error contracts (`400 expiry_out_of_range` with `details.min_seconds`/`max_seconds`, `409 duplicate_reference`), and the success condition tied to a webhook event. This does not conflict with `idempotentHint: false` — the annotation correctly says a repeat call would create a second payment, and the description explains the caller-supplied key that prevents it.

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

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

Paragraphs are front-loaded and each carries a distinct operational fact (account handoff, amount rule, expiry, success semantics, uniqueness/idempotency), so there is little filler. The one flaw is the opening sentence duplicated almost verbatim ("Create a bank-transfer payment.\n\nCreate a bank-transfer payment."), which wastes the highest-attention position.

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 12-parameter creation tool with nested objects and no output schema, the description covers the full lifecycle an agent needs: what is created, what to show the customer, how long it lives, how success is proven, and the two failure modes it will most likely hit. Left unaddressed are the response envelope beyond the `bank_transfer` account and the untouched parameters (`split`, `expand`, `metadata`, `customer`).

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

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

With 67% schema coverage, the description meaningfully extends the schema on the parameters that matter: it states the default for `amount_rule`, that `amount` becomes optional under `any`, the hard range and default for expiry, and the uniqueness constraint on `reference`. It does repeat some schema text verbatim (the 300–10800 expiry seconds) and says nothing about `split`, `expand`, `metadata`, `customer`, or `description`, leaving a quarter of the surface to 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 gives a specific verb and resource ("Create a bank-transfer payment") and immediately explains the mechanism — Pletopay opens a single-use virtual account returned under `bank_transfer` — which separates it functionally from payout tools like create_transfer and from create_checkout_session. It never names a sibling, so an agent must still infer the boundary between accepting a bank transfer and accepting a card checkout.

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

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

It sets clear conditions for the key decisions: `amount_rule: exact` versus `any` (and that `amount` may then be omitted), the 5-minute-to-3-hour expiry window and its default, and when to send an Idempotency-Key. It also warns how NOT to confirm payment — don't trust a redirect or client-side callback, listen for `payment.succeeded` or retrieve the payment. The gap is that it never tells the agent when to pick this over create_checkout_session or create_payment_link.

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 this is a non-read-only, non-destructive, non-idempotent, closed-world create operation. The description adds genuinely new behavior: each visit to the link spawns a separate checkout session, and the link terminates itself on `max_uses` or `expires_at`. It stays silent on the idempotency behavior and what is returned, so it adds real value but not a complete behavioral picture.

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 tight sentences, front-loaded with the core definition before the configuration rules. Every sentence carries distinct information: what it is, how pricing works, and how the link expires.

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 12-parameter create tool with no output schema and low schema coverage, the definition covers the essential decision points (pricing mode, expiry, usage cap). The gaps are the unexplained URL callbacks and the `split` rule, plus no indication of what the created link object contains – acceptable but not exhaustive.

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 only 33% across 12 parameters, so the description must carry weight – and it does for the highest-risk semantics: the mutual exclusivity of fixed `amount` versus the `min_amount`/`max_amount` range, plus the stopping conditions for `max_uses` and `expires_at`. It leaves `split`, `metadata`, `cancel_url`, `success_url`, and `name` unexplained, so it compensates partially rather than fully.

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 (create a payment link) and immediately defines what that is: a reusable hosted page where each visit starts its own checkout session. That reusability framing implicitly separates it from create_checkout_session, but no sibling is named, so the differentiation is inferential rather than explicit.

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

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

Gives useful configuration guidance: use a fixed `amount`, or omit it and set `min_amount`/`max_amount` to let the customer choose, and use `max_uses`/`expires_at` to auto-stop the link. That is conditional logic for parameters, not tool-selection guidance – nothing says when to reach for this versus create_checkout_session or update_payment_link.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the mutation profile is covered. The description adds conceptual context about recurring billing but says nothing about prerequisites, whether a plan can be modified afterward (update_plan exists), or what the response contains. Note the schema offers an idempotency_key even though idempotentHint=false, which is a nuance the description does not clarify.

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?

Short overall, but the first sentence 'Create a plan.' is pure repetition of the title and the second sentence restarts with the same phrase. The substantive content (billing period formula, subscription hand-off) is good, but one sentence is wasted.

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 7-parameter mutation with no output schema, the description covers the core concept and the natural next step adequately; return shape is unspecified but the plan object model is at least implied. Slightly incomplete on idempotency behavior and post-creation editability, but nothing critical is missing for a correct call.

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 43%, so the description should compensate. It does add real meaning for the compound `interval_count` × `interval` billing period, the trickiest parameter pairing, but it leaves name, description, metadata and idempotency_key unaddressed (amount's kobo unit is covered only by 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?

States a specific verb and resource plus the domain meaning: 'an amount billed every `interval_count` × `interval` (for example every 3 months)'. That clarifies what a plan actually is, and it names the downstream consumer (create_subscription via POST /api/v1/subscriptions), so an agent can separate it from subscription creation. The only weakness is the redundant restatement of 'Create a plan' twice.

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 a follow-up path ('Subscribe customers to it with POST /api/v1/subscriptions'), which implies the tool is a prerequisite for subscriptions, but there is no explicit when-to-use/when-not guidance versus siblings like create_subscription or update_plan. Usage is inferable rather than 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?

Beyond the annotations, it discloses that this sends real money in live mode, cannot be undone, affects payment status only after payout, and requires confirming amount and destination with the user. It also explains idempotency behavior and the resulting error conditions in useful detail.

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 content is front-loaded and organized around key concerns such as destination and idempotency. However, the opening repeats the title and then restates the same sentence, which is unnecessary.

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

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

For a destructive, live-money mutation with seven parameters and no output schema, the description covers refundability, destination rules, idempotency, payout timing, and confirmation requirements. Nothing essential for correct invocation appears to be missing.

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

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

The description adds substantial meaning beyond the schema for `amount`, `destination`, `reference`, and `idempotency_key`, including defaults and relevant error cases. It does not explain `reason` or `metadata`, so it is strong but not exhaustive.

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: refund a payment, fully or partially. It clearly distinguishes this mutation from read-oriented siblings such as get_refund and list_refunds.

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 when-to-use conditions, including that only `succeeded` or `partially_refunded` payments can be refunded, and explains when to omit or pass `destination`. It does not explicitly name sibling alternatives, so it falls just short of the top score.

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

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

Adds substantial behavior beyond the annotations: background execution model, the report.ready event, file retention tied to expires_at, exact decimal naira amounts, UTC timestamps, and a concurrency cap with the concrete error code 429 reports_in_progress. These are exactly the operational facts an agent cannot infer from the schema or the readOnly/idempotent hints.

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

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

Four tight sentences, front-loaded with the purpose, then constraints, then operational notes. Nothing is repeated and every sentence carries information the caller needs.

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

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

With no output schema, the description carries the return-handling burden and does so well: it explains that a report is produced asynchronously, must be polled or awaited via an event, then downloaded before expiry. The one gap is that it never says what the create call itself returns (a report id/object), which the agent needs to poll or fetch.

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 only 33%, so the description has to compensate; it does explain the 366-day cap and that period_end is exclusive, though the schema already repeats the exclusivity note. The type enum (payments, transfers, refunds, settlements, balance_statement, customers, invoices, subscriptions) is never discussed, so an agent gets no guidance on which report type to pick.

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 (generate) and resource (CSV report) and immediately frames the async lifecycle: 'poll the report or listen for report.ready, then download it.' That phrasing implicitly separates this from the sibling read/download tools (get_report, download_report, list_reports), so an agent can place it in the workflow without opening a 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?

Gives clear context for when this is the right call (period-bounded report generation) and how to proceed afterward (poll or listen for report.ready, then download). It never explicitly names the alternative tools or states when NOT to use it, e.g. a single payment lookup should use get_payment rather than a report.

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 destructiveHint=true and readOnlyHint=false, but the description goes well beyond them by explaining that live mode moves real money, that the action cannot be undone, and that the split is frozen onto each payment at creation time. That freezing rule is non-obvious behavioral context an agent could not infer from the schema or annotations.

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

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

The safety warning is front-loaded in the final sentence and every sentence carries information. Minor waste: the opening line "Create a split rule" duplicates the title, and the second sentence restarts with the same phrase rather than continuing the thought.

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

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

For a destructive, nested-parameter mutation tool with no output schema, the description covers the economics, the units, the downstream wiring, and the safety requirement. It stops short of saying what the call returns (the new rule id, presumably) or what constraints apply to `name`, which matters given there's no output schema to fall back on.

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

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

With schema description coverage at only 20%, the description carries real weight and delivers the important part: that `percentage` shares are basis points (2500 = 25%), that `flat` shares are in kobo, and that flat shares are capped at the net amount. It does not explain `name` or `metadata`, and it never mentions `idempotency_key`, so the less obvious parameters are left to 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?

States a specific verb and resource ("Create a split rule") and immediately defines the resource's semantics: it shares each payment's net amount after fees with subaccounts while the remainder stays in the creator's balance. The create verb also separates it cleanly from the list/get/update split-rule siblings in the tool list.

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 concrete downstream usage: pass the rule id as `split` when creating a payment, checkout session, payment link, invoice or subscription, and it warns to confirm amount and destination with the user before calling in live mode. What's missing is explicit guidance on when to use `update_split_rule` instead of creating a new rule, or whether multiple rules may coexist.

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, the description discloses the verification behavior of the payout account and the concrete failure mode '400 account_not_resolved', which an agent cannot infer from the schema. It also reinforces the destructive/live-mode stakes ('sends real money or changes where money is paid, and it cannot be undone'), consistent with destructiveHint=true. Minor imprecision: creating a subaccount registers a payout destination rather than itself moving money, and idempotency behavior is left entirely to 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?

The first sentence repeats the title verbatim and the second sentence restates the same definition ('a seller, vendor or branch...'), so the opening is redundant. The remaining content (verification failure, live-mode irreversibility, confirmation step) is useful and reasonably front-loaded, but the wasted restatement and the irrelevant amount reference cost it.

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

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

For a destructive, money-adjacent mutation with no output schema and only 50% parameter coverage, the description covers the key risk and one error code but omits what is returned (e.g. subaccount identifier and verification status) and whether a resolve_account call should precede it. Its completeness is adequate but leaves real gaps an agent would need to fill.

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

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

With 50% schema description coverage, the description partially compensates by explaining that the payout account is verified by name enquiry, which gives meaning to account_number and bank_code. But 'name', 'email' and 'metadata' get no semantic treatment, and the 'amount (in kobo)' phrase references no parameter at all, adding noise rather than meaning.

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 gives a specific verb and resource ('create a subaccount') and defines the resource conceptually as 'a seller, vendor or branch on your platform with its own balance and payout account'. It also relates subaccounts to split rules, which hints at how it differs from create_customer and the split-rule tools. It stops short of explicitly naming a sibling to prefer instead, so a 4 rather than a 5.

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 genuine pre-call guidance ('confirm the exact amount (in kobo) and the destination with the user') and implies when to use it (when you need a seller with its own balance and payout account). However, the 'confirm the exact amount (in kobo)' instruction does not correspond to any parameter of this tool and reads as guidance copied from a transfer/payment tool, which could mislead an agent. No explicit when-not-to-use or alternative routing is provided despite several nearby siblings (resolve_account, create_customer, create_split_rule).

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

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

Annotations already declare the non-read-only, non-destructive, non-open-world profile, and the description adds genuinely new behavior: nothing is debited automatically, invoices are issued at `start_date` then at each period end, and a dedicated virtual account is provisioned for the `dedicated_account` path. The 409 subscription_exists conflict is a useful disclosed failure mode. It does not describe the returned subscription object or confirmation timing.

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 lead sentence 'Subscribe a customer to a plan.' is duplicated immediately, which is pure waste. The `collection_method` explanation largely restates the enum description in the schema. The remaining content is well-structured and front-loads the important scoping facts.

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 an 8-parameter mutation with no output schema and nested `metadata`, the description covers the things an agent cannot infer: the billing schedule, the no-auto-debit payment model, and the duplicate-subscription error. Only the shape of the success response and the `split`/`metadata` semantics are left unaddressed.

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

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

With 75% schema coverage the schema already documents most parameters, including the `collection_method` enum values almost verbatim as the description. The description does add real meaning about how `start_date` and `days_until_due` interact across periods, but it says nothing about `split`, `metadata`, or `idempotency_key`.

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 definition states a specific verb and resource ('Subscribe a customer to a plan') and immediately scopes it with billing-cycle mechanics. The distinction from siblings like cancel_subscription or get_subscription is obvious from the verb, though the description never names an alternative explicitly.

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 operational context: the subscription is never auto-debited (push payments), and it explains when to pick `invoice` versus `dedicated_account`. It also surfaces the blocking condition (one live subscription per plan, 409). It stops short of naming sibling alternatives such as create_invoice or create_checkout_session for one-off charges.

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?

Far beyond the annotations, it discloses idempotency-Key retry semantics, immediate reservation of amount plus fees with an insufficient_funds error, the ₦10 minimum and 50-character narration cap, the never-failed-until-confirmed status model with transfer.succeeded/transfer.failed events, and the full set of 403 refusal reasons. This is exactly the operational context an agent needs before an irreversible money 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?

Front-loaded with the action and the idempotency requirement, then layered with reservation, status, and error details in scannable paragraphs. The final sentence restates idempotency_key guidance already given twice, which is slight redundancy against an otherwise dense, purposeful text.

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

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

For a destructive, open-world mutation with seven parameters and no output schema, the description covers funds flow, failure semantics, event notifications, and error codes well. It never describes the shape of the returned transfer object (fields besides status), which is the main remaining ambiguity given the absent output schema.

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 only 43%, but the description compensates for the critical fields: it clarifies amount is in kobo with a minimum, ties narration to its 50-character limit, and explains idempotency_key semantics. It leaves reference and metadata behavior to the schema, which is acceptable since those are self-explanatory.

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?

It states a concrete action and resource: sending money from available balance to any Nigerian bank account, with scope (funds held in balance) that separates it from read siblings like list_transfers. It does not explicitly distinguish itself from the other money-movement sibling, create_payment, so the agent must infer which of the two write tools to reach for.

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?

Gives clear preconditions: resolve the account first via name-enquiry, confirm exact amount in kobo and destination with the user, and note live mode sends real money. It never names an alternative tool (e.g. that simulate_transfer exists for sandbox) or states when not to use this, but the context for correct invocation is strong.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds real substance: dedicated accounts generate a `succeeded` payment with `source: dedicated_virtual_account` on every inbound transfer, and dynamic accounts are consumed by a single payment. It also surfaces the idempotency_key retry semantics ("retrying with the same key returns the original result"), which usefully nuances the idempotentHint=false annotation rather than contradicting it. It stops short of describing failure modes, limits, or whether created accounts can be deleted vs only closed.

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 and well structured, with bolded mode labels that make scanning easy. The only waste is the opening "Create a virtual account." fragment, which restates the title and is immediately repeated by the full first sentence.

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 8 parameters, a nested metadata object, conditional requirements, and no output schema, the description supplies exactly what is otherwise missing: mode-specific required fields and, for the dynamic case, what the return value contains (the account plus the payment id in `payment`). The only unchecked box is that return shape for dedicated accounts is left implicit.

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 already high (88%), so the baseline is 3, but the description adds genuinely new constraints: it states `customer_id` is needed for dedicated and `amount` + `reference` are needed for dynamic, which the schema does not mark as conditionally required (only `type` is in the required list). That conditional-required mapping is the most valuable thing it could add, so it earns 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?

"Create a virtual account (a real NUBAN that routes into your balance)" states a specific verb and resource and defines the domain term inline. It then splits the tool into its two supported modes (dedicated vs dynamic) and even names the equivalent sibling endpoint (`POST /api/v1/payments`) for the dynamic case, so an agent can distinguish it from create_payment and create_customer.

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?

Clear selection guidance between the two types: dedicated is a permanent per-customer account, dynamic is a single-use account for one exact amount, and dynamic is functionally equivalent to create_payment. It also implies the closing path ("Close it when you no longer want to receive money"), pointing at close_virtual_account. No explicit exclusions or prerequisites (auth/scope, sandbox behavior) are stated, keeping it below 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?

The description adds substantial behavior beyond the annotations: public reachability is required, HTTPS is mandatory in live mode, private network addresses are refused, and the signing secret appears only in the creation response. It also explains how the secret is used, discloses the 16-endpoint-per-mode limit, and supplies the exact quota error.

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 important operational constraints are front-loaded and expressed compactly. Repeating the title's opening and then restating the one-time-secret warning introduces noticeable redundancy, preventing a perfect conciseness score.

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

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

Despite the absence of an output schema, the description discloses the most important response behavior: the `whsec_…` secret is available only once and must be stored for signature verification. Combined with the schema, it covers required inputs, event selection, idempotent retries, endpoint validation, limits, and a relevant failure mode, which is sufficient for correct invocation and result handling.

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

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

With only 25% schema description coverage, the description compensates well by explaining the reachability and protocol constraints on `url` and the wildcard behavior of `enabled_events`. Together with the schema's event enum and idempotency-key documentation, this gives the agent enough meaning to populate all consequential parameters correctly.

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 and resource: registering a publicly reachable webhook endpoint to receive subscribed events. It does not explicitly contrast creation with siblings such as update_webhook_endpoint, test_webhook_endpoint, or rotate_webhook_secret, so sibling differentiation remains implicit.

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: create an endpoint to receive either selected events or all events using `*`. However, it gives no explicit when-not guidance or alternatives, such as updating an existing endpoint or rotating the secret of one already created.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds real value beyond that by stating two consequences the annotations cannot express: deliveries stop and delivery history is retained rather than purged.

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 content is short but entirely duplicated: the title repeats the sentence and the description then restates it twice. The same clause ("deliveries stop; history is kept") appears three times across title and body, wasting the agent's attention.

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 destructive tool with rich annotations and no output schema, the coverage is nearly adequate — the side effects are stated. It stops short of noting what happens on an unknown or already-deleted id, which matters for an idempotent delete.

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 the single `id` parameter is documented in the schema with the `we_…` prefix hint. The description adds no meaning about the identifier beyond what the schema already provides, so the baseline 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 names a specific verb and resource ("Delete a webhook endpoint"), so an agent can identify the operation immediately. It doesn't differentiate from nearby siblings like update_webhook_endpoint or list_endpoint_deliveries, but the delete semantics 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?

There is no guidance on when to delete versus update or leave an endpoint inactive, and no mention of prerequisites such as confirming the endpoint id. The only usage-adjacent statement is the consequence that deliveries stop.

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 establish readOnly, idempotent, non-destructive behavior, so the bar is lower, and the description still adds real operational detail: the X-Content-SHA256 response header for integrity verification and the two concrete failure modes with status codes (409 report_not_ready, 409 report_expired). It does not say what the body looks like on failure or how long before expiry, but the added context is well beyond the annotations.

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

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

The content is front-loaded and short, but the first line duplicates the title verbatim and the second sentence restates it a third time ('Download a finished report as CSV'). The error-state and header information is valuable; the repeated framing is not.

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

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

For a single-parameter read tool with no output schema, the description covers the essential behavior an agent needs: the returned payload is CSV, the hash is available in a header for verification, and both blocking conditions return 409. Only minor gaps remain, such as whether the hash header is mandatory or how long an expired report retained.

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 single `id` parameter is already documented as `rpt_…`; the description adds nothing about the identifier's meaning beyond implying it must reference a completed report. Baseline 3 is appropriate when the schema carries the 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 gives a specific verb and resource ('Download a finished report as CSV'), which clearly separates the file-fetch action from metadata siblings like get_report and list_reports. It stops short of naming those siblings explicitly, so the differentiation is inferable rather than stated.

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 word 'finished' plus the two 409 cases implies the precondition (report must be completed before download) and tells the agent what happens otherwise. There is no explicit routing guidance such as 'use get_report for metadata, this tool for bytes', leaving the agent to infer the boundary with get_report and create_report.

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 destructiveHint=true and idempotentHint=false. The description adds real value beyond them: the business effect (customer can no longer pay) and the error semantics (409 when the session is already complete or expired), which tells the agent how to handle a repeat call or a stale id. It does not say what is returned on success, but annotations carry the safety profile.

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, front-loaded with the action and immediately followed by the effect and the 409 edge case. The opening sentence merely restates the title and tool name, which is the only wasted line.

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

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

For a single-parameter mutation tool with no output schema, the description covers effect, precondition and error case, and annotations cover the safety profile. The remaining gap is the success response shape, which is minor but non-trivial for an agent needing to confirm the expire succeeded.

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 the only parameter 'id' is documented in-schema as the checkout session id with the `cs_…` prefix. The description adds no further meaning about the id, so the schema does all the work and baseline 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 states a specific verb ('Expire') and resource ('an open checkout session'), which cleanly separates it from the many read/create checkout-session siblings such as get_checkout_session, list_checkout_sessions and create_checkout_session. No other sibling performs this operation, so an agent can route to it 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 the operative context — 'so the customer can no longer pay through it' — and an implicit precondition that the session must still be open, since already-complete or expired sessions return 409. It does not explicitly contrast with alternatives (e.g. leaving a session to naturally expire), so it stops short of full when/when-not guidance.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation. The description goes beyond them by naming what actually changes (number assigned, amounts frozen, payable URL exposed) and by disclosing two failure conditions: zero total or a past due date. It stops short of saying what happens on a repeated call or what permissions are needed, so a 4 rather than a 5.

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 paragraphs with the operative effects front-loaded and the blocking conditions placed last where they are easy to scan. The opening sentence restates the title verbatim and earns nothing, which is the main deduction.

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 with full annotation coverage, the definition supplies what an agent needs: the required state (draft), the observable effects, and the two conditions that cause failure. The absence of any note on the response shape is a minor gap, since there is no output schema to fall back on.

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

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

Schema coverage is 100% and the single `id` parameter is fully documented as the `inv_…` identifier, so the schema carries the load. The description adds only the implicit constraint that the referenced invoice must be a draft; it gives no further detail on the id's form or accepted sources. 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?

States a specific verb and resource ("Finalize a draft invoice") and enumerates the concrete effects: it gets its number, amounts freeze, and `hosted_invoice_url` becomes a payable page. That is far more specific than the title. It does not explicitly distinguish itself from nearby siblings like void_invoice or mark_invoice_uncollectible, which is the only thing keeping it off a 5.

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 via preconditions -- the invoice must be a draft, have a non-zero total, and not be past due -- which tells an agent when the call will succeed. However, it never states when to choose this over update_invoice, void_invoice, or mark_invoice_uncollectible, so the alternative-selection guidance is left to inference.

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 fully covered structurally. The description adds meaningful context by disclosing that values come from a double-entry ledger and defining each balance category, but it says nothing about freshness, caching, currency, or snapshot timing for a read tool whose whole value is numeric accuracy.

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 statement followed by a compact, scannable definition list for each balance field. The opening line largely repeats the tool title, which is a small redundancy, but the rest is dense and earns its space.

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 field-by-field definitions are exactly the compensation needed, and the returned shape is now inferable. Remaining gaps are minor: it does not say whether balances are per-currency or aggregated, or how the 'total' interacts with 'settled_total' across currencies.

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?

Zero parameters, so the baseline is 4 and there is nothing further to document. The schema is closed with additionalProperties=false, which the description does not need to restate.

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 ('Retrieve your balances') and scopes it to 'this mode', implying account-level rather than subaccount balances. It never names the nearby sibling get_subaccount_balance, so an agent must infer the distinction rather than being told it.

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?

There is no explicit when-to-use or when-not-to-use guidance and no alternative routing to get_subaccount_balance or get_settlement. The phrase 'in this mode' is the only contextual hint and is never explained.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered elsewhere. The description adds nothing beyond that: no note on error behavior for expired or unknown sessions, no auth or scope requirements, no pagination or expansion concerns.

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 body is a near-verbatim restatement of the title followed by a second sentence that repeats the first with the id detail appended. Two sentences that say the same thing waste space rather than front-loading useful 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?

For a one-parameter read tool with full schema coverage and rich annotations, this is minimally sufficient to call correctly. It falls short of complete because the sibling disambiguation an agent needs at selection time is absent.

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

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

Schema coverage is 100% and the single 'id' parameter is documented in the schema with the same `cs_…` format. The description merely repeats that format, so it adds no meaning beyond the structured field; baseline 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 names a specific verb and resource ('Retrieve a checkout session') and the 'cs_…' prefix hints that lookup is by session id. However, it does not differentiate itself from the sibling get_checkout_session_by_reference, which is exactly the alternative an agent must choose between.

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?

There is no when-to-use or when-not-to-use guidance, and no prerequisites such as whether the session must be unexpired. The id-vs-reference distinction with get_checkout_session_by_reference is left entirely implicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real behavioral value by disclosing the failure mode for an unknown reference ('404 resource_missing') and the 'unique per mode' scoping of references — information an agent cannot get from the annotations.

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

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

Very short and front-loaded, with the 404 behavior placed immediately after the core statement. The opening sentence duplicates the title and the second sentence restates 'retrieve a checkout session by the reference', so a small amount of the text is redundant rather than additive.

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

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

For a single-parameter, read-only lookup with rich annotations and no output schema, the description covers what the tool does, the key semantics, and the not-found behavior. It is nearly sufficient; only the sibling alternative for ID-based lookup is absent.

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 parameter's type and meaning are already documented. The description goes beyond that by clarifying the reference is the one supplied at creation and is unique per mode, which matters for constructing a valid lookup key across test/live modes.

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 ('Retrieve a checkout session') and qualifies it by lookup key ('by the reference you gave'), which separates it from the ID-based 'get_checkout_session' sibling. It stops short of naming that sibling explicitly, so the differentiation is inferable rather than stated.

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

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

Usage is only implied: the agent must already hold the reference it supplied at creation time. There is no explicit when-to-use/when-not-to-use guidance and no pointer to 'get_checkout_session' for agents that only have the session ID, which is the most likely wrong-tool confusion among the siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond them — no note on error behavior for unknown ids, no mention of what is returned or whether the call is a hard lookup failure.

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?

It is short and front-loaded, but the two sentences say the same thing twice, so the second sentence does not earn its place. There is no wasted prose beyond that redundancy, but also no structure that helps the agent.

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 single-parameter read tool with rich annotations and a fully described schema, the definition is minimally adequate — the agent can call it correctly. It is not complete as a selector, since nothing in it helps an agent choose it over list_customers or get_customer-related siblings.

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

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

Schema description coverage is 100%, so the single `id` parameter is fully documented in the schema. The description only echoes the same `cus_…` format hint, adding no meaning beyond the structured fields; per the coverage rule this is baseline 3.

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

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

The description restates the title almost verbatim ('Retrieve a customer' / 'Retrieve a customer by id'), and the id format `cus_…` is already in the schema. The only added signal is 'by id', which weakly distinguishes it from list_customers, but the definition is effectively tautological.

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_customers, get_customer-adjacent tools, or update_customer. The agent must infer the distinction from the tool name alone; there is no explicit when/when-not or alternative routing.

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 establish readOnly, idempotent, and closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing the return format ('as markdown'), which the annotations and schema do not convey.

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?

One sentence with zero filler, front-loading the return format and then the key, with the slug provenance in parentheses. Nothing is redundant or misplaced.

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 supplies the return format (markdown), and the enum makes failure modes moot. For a single-parameter read tool this is essentially complete, with only marginal room for more detail.

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 the single parameter is an enum with an example, so the schema already documents it fully. The description adds only that slugs can come from search_docs, which is minor incremental meaning above the schema 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?

States a specific verb and resource ('Returns one Pletopay guide as markdown') and identifies the lookup key ('by its slug'). It also points at the sibling search_docs as the source of slugs, which helps distinguish the read-one pattern from search, though it stops short of an explicit contrast statement.

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?

Clear implied usage: call this when you already have a slug, and obtain slugs either from search_docs or from the enumerated list. There is no explicit when-not guidance (e.g. 'do not use for listing'), but the routing to search_docs covers the main alternative.

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

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

The annotations already declare this as a safe, idempotent, read-only, closed-world operation. The description adds no meaningful behavioral context such as error behavior, permissions, or what retrieval returns; it only restates the id format already present in 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?

The description is short and front-loaded, but the second sentence largely repeats the first and duplicates information already in the schema. It is concise but somewhat redundant.

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 lookup, the definition is sufficient to invoke the tool correctly. However, with no output schema, it provides no context about the returned event data or failure cases.

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

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

Schema description coverage is 100%, so the id parameter is already documented. The description repeats the `evt_…` format but adds no further semantics 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 states a specific verb and resource: retrieve an event by id. It is clear what the tool does, but it does not explicitly distinguish it from siblings such as list_events or replay_event.

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 implies use when an event id is available, but gives no explicit when-to-use guidance, prerequisites, or comparison with alternatives like list_events.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no statement about what is returned, what happens with a voided or nonexistent invoice, or any auth/rate considerations.

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 text is short and front-loaded, but it is effectively the same sentence twice, so the second sentence does not earn its place. Brevity here reflects under-specification rather than disciplined concision.

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 simple single-parameter read tool with rich annotations, but there is no output schema, so the description should at minimum sketch what a retrieved invoice contains. It also omits not-found behavior, leaving an agent with only the id format to go on.

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?

There is a single parameter with 100% schema description coverage, so the schema carries the semantics and the baseline is 3. The description's mention of the `inv_…` prefix duplicates the schema text rather than adding new meaning.

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 restates the title and name almost verbatim: 'Retrieve an invoice' followed by 'Retrieve an invoice by id.' It does not differentiate this from siblings such as list_invoices, update_invoice, or finalize_invoice, nor does it say what an invoice retrieval returns or what scope it covers.

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?

There is no when-to-use guidance, no mention of when to prefer list_invoices versus a single fetch, and no indication of prerequisites or failure conditions (e.g., unknown id). The only implied usage is that an id is required, which the schema already enforces.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond them by telling the agent this is the authoritative check and which returned fields to validate, though it says nothing about errors or not-found behavior.

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

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

Two short, front-loaded sentences that are easy to scan. Minor waste: the first line repeats the title verbatim before the more useful second sentence.

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 usefully names the return fields to validate (status, amount_received), which is the key missing piece for this tool. It omits any mention of the expand parameter's behavior, leaving a small 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 coverage is 100%, and the description only restates the id format already documented in the schema. The optional 'expand' parameter and its effect are not mentioned at all, so the description adds no meaning beyond the structured field.

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 ('Retrieve a payment by id') and adds a purpose ('authoritative way to verify a payment server-side'). It does not, however, distinguish itself from the obvious sibling get_payment_by_reference, which an agent could easily confuse it with.

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 for when to use it: server-side verification before delivering value, with concrete success criteria (status 'succeeded', amount_received matches expectation). It stops short of stating exclusions or pointing at get_payment_by_reference for reference-based lookups.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the 'verify' framing, saying nothing about what happens when no payment matches the reference or whether the call errors versus returns empty — the main behavioral gap an agent would care about.

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 with the lookup key front-loaded, but the opening restates the tool title near-verbatim and then repeats 'Retrieve a payment by the reference' again in the next sentence. Tightening to a single sentence would lose nothing.

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 two-parameter read-only lookup with no output schema, the description leaves the return value and the not-found behavior undescribed; an agent cannot tell whether a miss raises an error or returns null. What is present is accurate but thinner than the tool's surface warrants.

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

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

Schema description coverage is 100%, so both `reference` and `expand` are documented in the schema itself. The description repeats that the reference is one 'you gave it' but adds no format, length, or uniqueness constraints, and never mentions `expand` — which is acceptable under full schema coverage, hence the baseline 3.

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

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

The description names a specific verb and resource (retrieve a payment) plus the lookup key (your `reference`), and the second sentence implicitly contrasts with the by-id sibling by noting you may have stored an order id but not the Pletopay payment id. It never names `get_payment` explicitly, so the differentiation must be inferred from the sibling list rather than read directly.

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 clause 'useful when you stored your order id but not the Pletopay payment id' gives a concrete situation that selects this tool over the by-id alternative. It stops short of an explicit 'do not use when you have the payment id' instruction, so the routing cue is clear but not fully spelled out.

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 without the description. The description adds nothing beyond that — no statement about what happens with an unknown or expired link id, no error/not-found behavior, and no return-shape context (and there is no output schema to cover it).

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

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

It is short and front-loaded, but it is also redundant — the second sentence says exactly what the first already said, with only the id format added. Nothing is bloated, but nothing earns its place beyond the name restatement.

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 single-parameter getter the annotations and schema carry most of the weight, but the description is effectively a name echo with no error semantics, no return information, and no dispatch rule against list_payment_links. With no output schema, the description should at minimum indicate what a retrieved payment link includes.

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 the single `id` parameter is fully documented in the schema, so baseline is 3. The description merely echoes the same `plink_…` format hint already present in the schema, adding no new semantics such as validation, prefix constraints, or what happens if the prefix is wrong.

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 restates the name and title ('Retrieve a payment link') and then repeats the same statement with the id format appended. It never distinguishes this from siblings such as get_payment_link-relevant alternatives (list_payment_links, update_payment_link, create_payment_link) or explains what a payment link is in this API. Only the parenthetical `plink_…` prefix adds any information at all.

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?

There is no when-to-use guidance and no mention of alternatives — an agent is not told to prefer list_payment_links when it lacks an id, nor whether to use update_payment_link instead when mutating. The only implicit cue is 'by id', which is already evident from the required parameter.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no note on behavior for an unknown or malformed id, no indication of what a plan record comprises, and no environment/livemode caveats.

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?

It is short and front-loaded, but the second sentence is essentially a restatement of the first with the word "id" added. The duplication consumes half the text without advancing understanding.

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

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

For a single-parameter read tool with full schema coverage and rich annotations, the minimal description is close to sufficient. However, with no output schema, the agent gets no indication of what a retrieved plan contains (amount, interval, currency, active status), leaving a real 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 100% and the sole parameter already documents the `plan_…` id format. The description repeats the same prefix hint without adding meaning such as whether ids are reusable across livemode/test or what happens on a non-plan id.

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

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

The description states a specific verb and resource ("Retrieve a plan") and narrows it to a lookup by id, which is clearly distinct from create_plan, list_plans, and update_plan by name alone. It stops short of explicitly contrasting itself with list_plans or get_subscription, so it is clear but not fully sibling-differentiated.

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?

There is no guidance on when to use this versus list_plans (to enumerate) or get_subscription (to resolve a subscription's plan). The only implied condition is that a plan id is known, which is restated from the schema rather than offered 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds nothing beyond them — no note on behavior for an unknown or malformed id, and no indication of what a refund record contains. The only extra detail, the `re_…` id prefix, is already in 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?

Very short and front-loaded, but the first sentence is a verbatim duplicate of the title and the second sentence repeats the verb and resource again. Roughly half the text is redundant restatement rather than added 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?

For a single-parameter read tool with full annotations, complete schema coverage, and no output schema, the definition is minimally sufficient to call correctly. It falls short of explaining the lookup-key distinction from its two closest siblings, which is the main open question an agent would have.

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

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

Schema coverage is 100% and the single parameter is fully documented, so the baseline is 3. The description's mention of the `re_…` format merely restates the schema description and adds no new meaning such as a valid/invalid example or a partial-id capability.

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+resource ("Retrieve a refund") and qualifies the lookup as by id, which implicitly separates it from get_refund_by_reference and list_refunds among the siblings. It doesn't explicitly name those alternatives, but the lookup key is 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_refunds (browse/unknown id) or get_refund_by_reference (lookup by external reference). The agent must infer the routing from the id argument alone.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the bar is lower; the description still adds value by stating that unknown references return `404 resource_missing` and that refunds created without a reference receive a generated one, which is exactly the kind of response-semantics detail 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?

The lead sentence is front-loaded and the follow-up sentences each add a distinct fact (uniqueness, auto-generation, 404). The first sentence largely restates the title, a minor redundancy, but nothing else is wasted.

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 lookup with no output schema, the description covers what is looked up, what an unknown reference yields, and how references originate. The only missing piece is how this differs from `get_refund`, which would make the routing decision unambiguous.

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

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

Schema coverage is 100% and the single parameter is documented, so the baseline is 3. The description goes beyond the schema by explaining that references are unique per mode and are auto-generated when omitted, which clarifies what a valid reference actually is.

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 gives a specific verb and resource ('Retrieve a refund by its `reference`'), which is more precise than the bare tool name. It does not, however, explicitly contrast with the sibling `get_refund`, so an agent must infer that one looks up by ID and this one by reference.

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

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

Usage is only implied: the reference-based lookup is the natural choice when you hold a reference, and the 'unique per mode' note hints at scoping. There is no explicit when-to-use versus `get_refund`, no prerequisites, and no statement about mode requirements.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds nothing beyond that, omitting what happens on an unknown id, whether the report must be finalized before retrieval, or any auth scoping.

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?

Very short and front-loaded, but the opening sentence is fully redundant with the second. The id-format detail could have been spent instead on disambiguating this tool from its closest sibling.

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 read tool with full schema coverage and a complete annotation set, the description is minimally sufficient to invoke correctly. It is not sufficient to choose correctly among the several other report- and statement-reading siblings.

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 the single id parameter is already documented with its `rpt_…` format. The description repeats that format without adding constraints such as case sensitivity or cross-account validity, so it neither helps nor hurts.

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 (retrieve a report by id) but the second sentence merely restates the first with the id prefix added. It gives no differentiation from plausible siblings such as download_report, get_statement, or list_reports, so an agent cannot tell from the text alone which retrieval tool fits.

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?

There is no when-to-use guidance, no mention of prerequisites, and no named alternative. The description never explains why an agent would call get_report rather than download_report or list_reports, leaving selection entirely to inference from tool names.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: exceeding a limit causes transfers and refunds to be refused with `403 risk_limit_exceeded`, while received payments over `high_value_payment` are only flagged. That consequence detail materially helps an agent interpret results.

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 first sentence is a verbatim restatement of the title, and the second sentence repeats the unit and the '0 = no limit' rule already given. Only the final clause about 403 refusals and flagged high-value payments earns its place, so roughly half the text is 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?

With no output schema and no parameters, the description does not explain which named limits the response contains (transfer, refund, high_value_payment thresholds, etc.) or their structure. It covers the enforcement semantics well but leaves the return shape underspecified for a tool whose entire value is the returned values.

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

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

The input schema has zero parameters, so there is nothing for the description to clarify; the baseline for a 0-param tool applies. The 'in this mode' phrasing usefully signals that results are scoped to the current API mode (e.g., sandbox vs live) without any argument being supplied.

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 the resource ('Your effective risk limits in this mode, in kobo') and its unit, so an agent knows this is a read of applied limits rather than configured policies. It does not distinguish itself from sibling tools such as list_risk_events or set_customer_risk_status, leaving the agent to infer that this one returns current thresholds.

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?

There is no explicit when-to-use guidance, no mention of when not to use it, and no pointer to the alternative risk tools in the sibling list. The agent must infer that this is the read counterpart to set_customer_risk_status from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description usefully adds that the response includes fee data and the payout transfer's status, which is real value given no output schema, but it says nothing about behavior for an unknown or malformed id.

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, front-loaded sentences with no filler, though the opening 'Retrieve a settlement.' duplicates the title and the first clause of the following sentence, which is mild 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 one-parameter read tool with no output schema, the description covers what it returns (fees, payout transfer status), which compensates for the missing output schema. Only error/not-found behavior and pagination-free confirmation are absent, both minor here.

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

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

Schema coverage is 100% and the single param already documents the 'stl_…' format, so the description merely repeats it. Baseline 3 is appropriate since the schema carries the 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?

States a specific verb and resource ('Retrieve a settlement by id') and adds the id prefix format and the payload contents (fees, payout transfer status). It does not name a sibling such as list_settlements or list_settlement_items as the way to obtain an id, so the boundary is only implied.

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

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

Usage is implied by the 'by id (stl_…)' requirement – the agent infers it needs a settlement id already in hand – but there is no explicit when-to-use versus list_settlements/list_settlement_items, and no stated fallback when the id is unknown.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond them — no not-found/error behavior, no mention of what a returned rule contains, no rate-limit or permission 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?

It is short, but the first sentence duplicates the title and tool name verbatim while the second carries all the information. Roughly half the text is redundant, though nothing is verbose or poorly ordered.

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 getter with complete annotations and full schema coverage, the essentials are present. However, no output schema exists, so the description is the only place a return-shape hint could live, and it offers none.

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 the single `id` parameter is already documented as 'The split rule id (`spl_…`)'. The description only echoes that same prefix hint, adding no meaning beyond the schema, so the baseline 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 second sentence states a specific verb and resource with the lookup key: 'Retrieve a split rule by id (`spl_…`)'. An agent can tell this is a single-object fetch, but nothing distinguishes it from siblings like list_split_rules or update_split_rule, and the opening sentence merely restates the title.

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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The phrase 'by id' weakly implies the prerequisite (you must already hold a `spl_…` id), which is only implied usage rather than stated routing guidance.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive, closed-world operation. The description adds only that figures are computed from the ledger and cover each balance over a period; it does not add auth, rate-limit, pagination, or output-shape detail beyond what annotations and schema provide.

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

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

The definition is short and front-loaded, but the first sentence is essentially the title and the second repeats opening/credits/debits/closing while adding period and ledger context. It is redundant rather than efficiently informative.

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

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

For a simple read-only statement tool, the description identifies the returned components and the ledger basis, and the schema fully defines the two period parameters. It is adequate for invocation, though it would be stronger with a note on how it differs from get_balance.

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

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

Schema coverage is 100% and both period_start and period_end have inclusive/exclusive ISO 8601 descriptions. The description only says "over a period" and adds no format or boundary semantics beyond the schema, so this is a baseline 3.

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

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

The description states a specific resource (balance statement) and its components (opening, credits, debits, closing), scoped per balance over a period and computed from the ledger. It does not explicitly name or contrast sibling tools such as get_balance or list_transactions, so it earns a 4 rather than a 5.

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?

There is no explicit when-to-use guidance, no when-not-to-use guidance, and no named alternative. The period parameters imply a reporting use case, but the description leaves the choice versus get_balance or list_transactions to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no note on what is returned, what happens with an unknown or malformed id, or whether inactive subaccounts are retrievable.

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?

Very short, but the first sentence is a verbatim restatement of the title and the second largely duplicates the parameter schema. Roughly half the text is redundant rather than additive.

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

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

For a single-parameter read tool with rich annotations this is close to sufficient, but with no output schema the description could at least hint at what a subaccount object contains. It is minimally adequate rather than complete.

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

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

Schema coverage is 100% and the single parameter's schema description already states the `sub_…` format, which the description merely repeats. Baseline 3 applies since the schema carries the parameter meaning.

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 second sentence gives a specific verb and resource ("Retrieve a subaccount by id") plus the id format, which is enough to identify the operation. It does not distinguish this from near-siblings such as get_subaccount_balance or get_virtual_account, so it stops short of a 5.

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?

There is no guidance on when to use this versus list_subaccounts, get_subaccount_balance, or get_virtual_account, and no prerequisites or error conditions mentioned. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and repeatability are covered. The description adds value beyond them by disclosing the content of the read — pending, available and settling balances sourced from the ledger — which matters because there is no output schema to reveal the return shape.

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?

It is short and front-loaded, but the first sentence is a near-verbatim restatement of the title, and 'from the ledger' appears twice in two sentences. Roughly half the text is redundant repetition rather than new 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?

For a one-parameter read tool with no output schema, the definition covers what is read and from where, which is the minimum an agent needs. It still omits the distinction from the sibling get_balance and any note on balance freshness or currency, leaving a gap on the main selection decision.

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 the single `id` parameter is documented as the subaccount id with the `sub_…` prefix pattern. The description adds no further parameter meaning such as where to obtain the id or whether a non-subaccount id errors, so the schema does all the work.

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 (read) and resource (a subaccount's pending, available and settling balances) and notes the ledger as the source, so the agent can tell it returns balance figures for one subaccount. It does not name or distinguish itself from the sibling get_balance, which is likely the account-level counterpart, so the differentiation is left implicit.

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?

There is no explicit when-to-use guidance: nothing says to call this for a `sub_…` id versus get_balance for the top-level account, nor any prerequisite (e.g., the subaccount must exist or be active). Usage is only inferable from the resource name and the required `id` parameter.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds nothing beyond that — no error/not-found behavior, no note on whether the subscription is returned live or cached, no auth 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?

It is short, but the second sentence repeats the first almost verbatim, so the only new information is the `sbs_…` prefix, which is already in the schema. Two sentences where one would have done.

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

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

For a single-parameter read-only getter with full annotation coverage, complete schema documentation, and no output schema, very little is required of the description. It would be improved by noting not-found behavior, but nothing an agent needs to invoke it 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 100% and the single `id` parameter is documented with the same `sbs_…` format hint. The description repeats rather than extends the schema, so the baseline of 3 is correct.

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?

It says 'Retrieve a subscription by id' — a verb plus resource, and the `sbs_…` prefix signals the id namespace. However, it largely restates the name and title, and gives no way to distinguish it from siblings such as list_subscriptions or get_subaccount beyond the obvious read-one-vs-list-many distinction the name already implies.

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?

There is no when-to-use guidance at all: no statement of when a single-subscription fetch is appropriate versus list_subscriptions or get_customer, no prerequisites, and no mention of what to do when the id is unknown.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no mention of not-found behavior, error semantics, or what a retrieved transfer contains. It is pure restatement.

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?

Very short and front-loaded, but the first line duplicates the title verbatim and earns nothing; only the id-format clause carries information, and even that is redundant. Brevity here comes from under-specification rather than discipline.

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

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

For a single-parameter read tool with rich annotations and full schema coverage, the bar is low and the definition is barely adequate. It omits any hint about failure modes or the relationship to the reference-based sibling, which is the one genuinely useful thing it could have said.

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 the single parameter documents the `trf_…` format itself. The description repeats that same prefix, adding no syntax, validation, or identifier-source detail beyond the schema. Baseline 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?

States a specific verb and resource ('Retrieve a transfer') and notes it works by id, which implicitly separates it from get_transfer_by_reference. However, the first sentence only restates the title, and no sibling is named, so the differentiation is inferred rather than stated.

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 'by id (`trf_…`)' phrasing implies the condition for choosing this over get_transfer_by_reference, but the alternative is never named and no when-not guidance is given. Usage is left to inference.

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 cover read-only, idempotent, non-destructive semantics, and the description adds real value beyond them: references are unique per mode, and an unknown reference yields `404 resource_missing`. It does not describe the returned object, but no output schema exists and the error contract is the more useful 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?

Two short sentences, front-loaded with the action, then the safety rationale and error behavior. Nothing is repeated and nothing is superfluous.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description covers purpose, selection rationale, and failure behavior. Only the shape of a successful response is left implicit, which is acceptable here.

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

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

Schema coverage is 100% and the single parameter is already documented. The description adds one meaningful nuance, that uniqueness is scoped per mode, but no format or length constraints beyond that. 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 gives a specific verb and resource ('Retrieve a transfer') and immediately narrows the lookup key to 'the reference you gave when sending it', which cleanly separates it from the id-based get_transfer sibling without naming it.

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 states a concrete situation for use: checking a transfer after a timeout when you never received its id. There is no explicit when-not or named alternative (get_transfer), but the scenario described is enough to route an agent correctly.

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 entire behavioral profile is supplied structurally. The description adds nothing beyond that — no note on error behavior for unknown ids, no indication of what the account object contains.

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?

It is short, but the second sentence restates the first with only the id format added, so a third of the text is redundant. Front-loading is fine but there is little substance to front-load.

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 read-only getter with full schema and annotation coverage, this is minimally adequate. However, there is no output schema and the description never indicates what a virtual account record includes, so an agent cannot anticipate the response.

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

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

Schema coverage is 100% and the single `id` parameter is already documented in the schema with the same `va_…` format note. The description merely repeats it, so the baseline 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 states a specific verb and resource ("Retrieve a virtual account") and hints at the id form (`va_…`), which slightly separates it from get_virtual_account_by_reference. But it largely restates the tool name and title, and never distinguishes it from list_virtual_accounts or the by-reference sibling in terms of when each applies.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_virtual_account_by_reference or list_virtual_accounts. An agent must infer that this is the id-based lookup purely from the name.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description still adds real value by disclosing the failure mode: an unknown reference yields 404 resource_missing. It stops short of describing the returned object's shape, but the error contract is the main behavioral gap an agent needs.

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 content is front-loaded and tightly written: identity of the tool, its precondition, its exclusion, and its error case in two short sentences. The opening line largely restates the title, which is the only wasted 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?

For a one-parameter lookup with full annotation coverage, the description supplies everything needed to choose and call it, including the 404 case. The only minor omission is that no output schema exists and the description says nothing about what the returned account object contains.

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

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

Schema description coverage is 100%, so the single parameter is already documented. The description reinforces that the reference is the one given at creation and is the same as the associated payment's reference, which clarifies provenance but adds little beyond the schema text.

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 names a specific verb and resource ("Retrieve a dynamic virtual account"), and crucially scopes it to dynamic accounts retrieved by reference. It explicitly contrasts this with dedicated accounts, which have no reference, and points to the id/list alternatives, so an agent can distinguish it from get_virtual_account 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?

It states the exact precondition (a reference you supplied at creation time) and an explicit exclusion: dedicated accounts have no reference and must be fetched by id or listed by customer. That is a genuine when-to-use / when-not-to-use rule plus the fallback path.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds no behavioral context at all — nothing about failure modes for an unknown id, whether secrets are masked in the response, or what the response contains.

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 short, but it is effectively one sentence duplicated: "Retrieve a webhook endpoint" then "Retrieve a webhook endpoint by id (`we_…`)." The repetition wastes the little space available and the id-prefix detail is already in the schema.

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, read-only lookup with rich annotations, this is minimally sufficient to invoke the tool correctly. With no output schema, though, the description could reasonably have said what a webhook endpoint object returns (URL, status, enabled events), and it omits that entirely.

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

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

Schema coverage is 100% and the single `id` parameter is documented with the same `we_…` prefix format. The description merely restates that format, adding no meaning beyond the schema, so the baseline 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 states a specific verb and resource ("Retrieve a webhook endpoint") and the lookup key (id `we_…`), so the basic action is unambiguous. However, it does not distinguish this from the many sibling retrieval tools, notably list_webhook_endpoints or test_webhook_endpoint, so an agent gets no help telling them apart beyond the name.

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?

There is no guidance on when to use this versus list_webhook_endpoints (when the id is unknown) or test_webhook_endpoint. The only implicit signal is the id parameter, which the schema already provides.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely new behavioral fact beyond the annotations: the list is cached for an hour, which tells the agent results may be stale and that repeated calls are cheap. It does not mention ordering or full page-size behavior, but for a closed static list that is minor.

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 purpose front-loaded, followed by the practical payoff (which field to reuse) and the caching caveat. No redundant phrasing 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?

For a zero-parameter, annotation-rich lookup with no output schema, the description covers purpose, the key returned field, and a caching caveat. It stops short of describing the other returned attributes (e.g., the human-readable bank name) or the ordering of results, which is the only remaining 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 tool takes zero parameters, so the baseline is 4. The description goes slightly beyond by explaining that the returned 'code' field is what should be passed as 'bank_code' elsewhere, adding downstream meaning rather than restating 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?

States a specific verb and resource ('List supported banks') and immediately qualifies the scope: the banks you can send transfers to. No sibling tool in the list does bank enumeration, so the resource is unambiguous and the purpose is fully identifiable.

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

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

Usage is only implied: the agent can infer it should call this before create_transfer to obtain a bank_code. There is no explicit statement of when to use this versus alternatives (e.g., resolve_account for resolving a specific account, or list_sandbox_test_values for test data) and no exclusions or prerequisites.

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 nothing on top: no mention of default page size, cursor-based pagination behavior, or how results are ordered, even though both cursor parameters exist in 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?

The description opens by repeating its own first sentence verbatim, which is pure waste. The remaining sentence is tight, but the duplication means it is not front-loaded cleanly.

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 six parameters, a nested date-range object, and cursor pagination but no output schema, the description should at least explain paging and default result size. It covers only two of the six filters and says nothing about the returned collection shape.

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

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

Schema description coverage is 100%, so all six parameters, including the nested created range object and the two cursors, are already documented in the schema. The description restates the status and payment_link filters without adding format, interaction, or default semantics beyond that 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?

Names a specific verb and resource ('List checkout sessions'), so an agent immediately knows the operation. However, it does not differentiate itself from siblings like get_checkout_session, create_checkout_session, or expire_checkout_session, which would have raised this to a 5.

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 offers no when-to-use guidance or exclusions relative to the sibling read tools (get_checkout_session, get_checkout_session_by_reference). The mention of filtering by status or payment_link is parameter guidance, not selection guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds essentially nothing beyond that: no mention of default page size, pagination semantics, ordering, or what a response looks like, so it does not enrich the behavioral picture.

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?

It is short and front-loaded, but the first two sentences ('List customers.' / 'List your customers.') are redundant restatements of the name, so there is minor wasted space.

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-only collection tool with full schema documentation and no output schema, the description covers the core purpose and the primary filter use case. Gaps around pagination behavior and return shape are real but modest given the annotation and schema richness.

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%, including the nested created date filter and both cursors, so the schema fully documents all five parameters. The description's email mention is consistent but adds no syntax or meaning beyond what the schema already provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('List customers'), which is enough to distinguish it from the many payment, invoice, and subscription list tools. It does not, however, differentiate itself from its closest sibling get_customer, so an agent must infer that this returns a collection rather than a single object.

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?

'Filter by email to find a customer you created earlier' gives an implied when-to-use for the email filter, but there is no explicit guidance on when to prefer this over get_customer or why one would page through customers. The usage context is present but thin.

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 this a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds value by enumerating what each delivery record contains (status, error, timing), but says nothing about pagination behavior or how deep the delivery history goes. Adequate, 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 body is a tight two-clause sentence with the resource scope front-loaded, but the opening line 'Deliveries to this endpoint' duplicates the title verbatim and earns no space. Structure is otherwise clean 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 six parameters, a nested object, and no output schema, the description does useful work by describing what a delivery record contains. However, it omits pagination guidance (cursor direction, default limit of 10) and the lifecycle meaning of pending/succeeded/failed/dead, which the enum alone does not explain.

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%, including the nested created[gte]/[lt] filter and cursor semantics, so the baseline is 3. The description only restates the status filter and mentions no limit, cursor, or date-range behavior, adding essentially nothing 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 names a specific resource ('delivery attempts to this endpoint') and states the returned fields (response status, error, timing), which is more concrete than the title alone. It implies scoping to a single webhook endpoint, distinguishing it from list_event_deliveries, but never explicitly contrasts the two siblings, so it stops short of a 5.

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?

'Filter by `status`' is the only usage hint; there is no statement of when to pick this tool over list_event_deliveries or when to follow up with replay_event. No prerequisites or exclusions are given, leaving the agent to infer the endpoint-vs-event distinction.

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 no behavioral context beyond that — nothing about pagination, ordering, whether failed/retried attempts are included, or how far back history goes. It essentially restates the title, so credit above the minimum is not earned.

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?

It is short and front-loaded, but the second sentence largely repeats the first, only adding the 'to your endpoints' qualifier. Every sentence should earn its place, and here the redundancy costs it.

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 read-only list tool with one well-documented parameter and rich annotations, the definition is minimally adequate. However, without an output schema the description should at least hint at what a delivery record contains or whether results are paginated, and it does neither.

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

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

With a single parameter and 100% schema description coverage, the schema already documents that id is the event id in evt_… format. The description adds no meaning about the identifier or any implied constraints, so the baseline 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 states the resource (deliveries of an event) and implicitly the operation (history/list), and the second sentence clarifies that these are deliveries sent to the caller's webhook endpoints. It does not distinguish this from the sibling list_endpoint_deliveries, which covers a very similar surface from the endpoint side, so an agent must infer the difference.

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?

There is no guidance on when to use this versus alternatives such as list_endpoint_deliveries, list_events, or get_event, nor any mention of prerequisites like needing an existing event id. The agent is left to guess the selection rule from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and a closed-world profile, so safety needs no restating. The description adds the semantic link to webhook payloads and the backfill use case, but says nothing about ordering of results, how far back events are retained (critical for a 'catch up after downtime' tool), or rate limits. That retention gap is a real behavioral omission.

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 opening 'List events.' is a bare restatement of the name and title, consuming a line without adding information before the substantive sentence arrives. The remaining text is tight and front-loads the webhook-equivalence claim, but the redundant lead-in costs it a point.

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 six optional parameters, a nested date filter, an enum, and no output schema, the description should say more about what a result looks like and how to page through a large backlog. It covers the two main filters and the purpose but leaves ordering, retention, and the cursor-based traversal strategy unaddressed.

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

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

Schema description coverage is 100%, so the enum values, limit bounds, created[] operators, and cursor directions are all already documented. The description adds a little interpretation — that filtering by resource_id shows 'everything that happened to one object' — but gives no syntax hint for the type enum or the cursor workflow. 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 gives a specific verb and resource and adds a useful identity claim: these are 'the same objects delivered to your webhooks,' which separates event records from the delivery records handled by list_event_deliveries. It does not, however, explicitly distinguish itself from get_event or list_event_deliveries by name, so an agent must infer the boundary from the sibling names alone.

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?

One concrete use case is offered — 'Use it to catch up after downtime' — which tells the agent this is a polling/backfill tool rather than a real-time mechanism. There is no guidance on when to prefer get_event for a single event, when list_event_deliveries is the right call, or what happens past the retention window, so alternatives are left implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond filtering surface—no mention of default page size (limit defaults to 10), result ordering, or cursor behavior, so it leaves behavioral gaps that annotation coverage only partly offsets.

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?

Very short, but the phrase "List invoices" is repeated verbatim in the title, first line, and second line, so a third of the content is pure duplication. Front-loading is fine; the redundancy is not.

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 read-only list tool with no output schema, the description is adequate but thin: it never mentions pagination via starting_after/ending_before, the created date-range object, or the default/max limit, all of which an agent must know to use it well.

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

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

Schema description coverage is 100%, so baseline is 3; the description adds a useful gloss that the subscription filter selects invoices issued by that subscription (sbs_…). It still omits the created date-range filter and the cursor parameters, but the enum and format semantics are already carried by 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?

States a specific verb and resource ("List invoices") in the first line, which is enough to distinguish it from siblings like get_invoice or create_invoice. It does not explicitly contrast with those siblings, but the intent is 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 second sentence names which filters are available (status, customer, subscription), which implies how to narrow results. However, it gives no guidance on when to use this versus get_invoice or how to page through results, so usage is only implied.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is fully covered by structured data. The description adds nothing beyond the schema: no pagination behavior, no default page size, no ordering or cursor semantics, and no hint about what the collection response looks like.

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?

'List payment links.' appears twice, once as a standalone line and once opening the second sentence, so roughly half the text is verbatim duplication. What remains is front-loaded and short, but the waste is disproportionate for a two-sentence description.

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 five optional parameters including a nested created date object, and no output schema, yet the description says nothing about pagination, defaults, or result shape. For a list endpoint whose main invocation risk is unbounded or mis-paged retrieval, this leaves key behavior undocumented.

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%, including per-field docs for limit, status, the nested created time filters and both cursors, so the baseline is 3. The description only restates the status filter that the enum already documents and adds no meaning to limit or the cursor 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?

States a specific verb and resource ('List payment links'), which cleanly separates it from get_payment_link, create_payment_link and update_payment_link in the sibling set. It loses a point because it offers no scope or differentiation statement beyond the verb, and it simply repeats the title.

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?

There is no when-to-use or when-not-to-use guidance at all. The only directive is that a status filter exists, which is already declared by the schema enum, so an agent gets no routing or exclusion logic from the description.

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