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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds genuinely new behavior: irreversibility with the concrete consequence ('its buyer can no longer pay it'), the fact that later payments are still captured and routed to review, and a live-key refusal. It does not state the resulting invoice state or what the call returns, so it falls just short of exhaustive.

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

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

Short and front-loaded, with the destructive consequence and confirmation requirement surfaced before the call. The telegraphic fragments ('Only while nothing has arrived') cost a little clarity for the space they save.

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 mutation with no output schema, it covers preconditions, environment restriction, irreversibility and the human-in-the-loop requirement. The main omission is the post-call outcome — what state the invoice ends in and what is returned — which matters when no output schema documents it.

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

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

Schema coverage is 100% and the schema already defines both `id` and `confirm`, including that confirm means the person agreed. The description reinforces confirm as a human-agreement gate but adds no syntax or semantics beyond that, 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?

States a specific verb and resource ('Cancel an invoice') that is unambiguous against siblings like retrieve_invoice, create_invoice or simulate_payment. It does not explicitly name a contrasting sibling, but the operation is distinct enough that no disambiguation is needed.

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 real preconditions: 'Only while nothing has arrived' and 'Test keys only: refused with a live key', plus a confirmation protocol ('Ask the person first, then call with confirm: true'). It stops short of naming an alternative path (e.g. refund) for the case where money already arrived, which would have earned 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered and the bar is lower. The description contributes 'One call' (single round trip) and the identity inputs needed. It does not disclose the response shape, how an unknown customer or product is handled, or that the answer is a non-cached point-in-time result despite openWorldHint=true.

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 question the tool answers, then the parameter routing. No filler. Slightly tight to the point of omitting the required-input guidance.

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 is the only place an agent could learn that the answer is a boolean-ish entitlement verdict plus context, and it stays silent. Combined with no statement of which identifiers must be supplied, the definition is adequate but incomplete for a decision-making tool.

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

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

Schema coverage is 60%, and the description does add real meaning by grouping the five parameters into customer identity (`customer`, `customer_email`, `customer_external_id`) versus product (`product` or `price`), including the alternative relationship between product and price. It never states that at least one customer identifier and one product identifier are functionally required, even though the schema marks zero required — a meaningful gap for a 5-parameter tool.

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 pair and frames it as a point-in-time question: 'One call: may this customer use this product now?' That is materially clearer than the title 'Check access' and distinguishes it from listing-type siblings. It does not explicitly contrast itself with `list_entitlements` or `consume_entitlement_credits`, so it falls 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?

'One call' implies this is the consolidated path for an access decision, which hints at when to prefer it over enumerating entitlements. However, no sibling is named, no when-not condition is given, and nothing says whether this should precede `consume_entitlement_credits`. Usage is implied 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?

Adds substantial behavior beyond the annotations: atomicity of the spend, refusal on insufficient balance, and the conditional-idempotency nuance ("with an Idempotency-Key a retry never spends twice") which meaningfully qualifies idempotentHint=false rather than contradicting it. The test-mode-only restriction is exactly the sort of context annotations cannot 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?

Front-loaded with the core action, then constraints, then the alternative — no filler. The opening "Spend credits." duplicates the title and is the only wasted line in an otherwise tight block.

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

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

For a mutation with no output schema, it covers failure conditions, idempotency, environment restriction, and the alternative endpoint. It stops short of saying what comes back (remaining pack balance?) or whether the spend is attributable to a customer, which would round out a spend operation.

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 coverage that exists is thin ("id" is only "The object's id."), so the description's "from one credit pack" usefully pins down what id refers to, and it explains action's reporting purpose beyond the schema's modest wording. The credits parameter's bounds and semantics are left entirely 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?

"Spends credits from one credit pack, atomically" states a specific verb, resource, and scope, and the closing line rules out the multi-pack variant. An agent can distinguish this from the many credit/entitlement siblings (check_entitlement, list_credit_usage) 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?

Explicitly routes the multi-pack case to POST /credits/consume and states a hard precondition ("Test keys only: refused with a live key"). It doesn't say when to prefer this over check_entitlement or list_credit_usage first, but the primary alternative is named with its selecting condition.

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 mutation/open-world/non-idempotent profile, and the description adds real value on top: a live-mode refusal with 403 `bill_overdue` when a Perly Pay bill is past 14 days, and the constraint that test keys are required. That is exactly the kind of failure-mode context annotations cannot convey. It stops short of describing the returned session object's 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?

Three short sentences, front-loaded with the payload shape before the redirect mechanics, then the edge-case refusals. The trailing 'Test keys only: refused with a live key.' is terse to the point of being clipped, but nothing 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?

No output schema exists, and the description covers the essential return value (`url`) and how to embed it, plus the principal failure conditions. An agent could call this correctly on the first attempt; only the full set of response fields and expiry semantics of the returned session are 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 75%, and the description compensates with semantics the schema cannot express: line_items is constrained to a single currency across the cart, and return_url/cancel_url are explained as success vs. abandonment destinations rather than merely 'An http(s) URL.' The 20-item/one-currency business rule is the single most important thing to get right here and it is stated plainly.

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

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

The description opens with the specific verb+resource ('Create a checkout session') and immediately characterizes the payload ('A cart of 1–20 prices in one currency'), so the agent knows this is a session-creation tool rather than a one-off charge. It does not explicitly distinguish itself from siblings like create_payment_link or create_invoice, which is the only thing keeping it from 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 concrete operational context: redirect the buyer to `url`, embed via pay.js overlay with `data-session`, and where the buyer lands on success vs. abandonment. Missing is any statement of when to prefer this over create_payment_link or create_invoice, but the usage flow itself 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 already disclose readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so mutation semantics are covered. The description adds genuinely new information — the tool refuses live keys — but omits important behaviors such as duplicate-email handling and the consequence of non-idempotency (retries creating duplicate customers).

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, and the test-key sentence earns its place. But the brevity reads as under-specification rather than discipline — the body omits essentials for a six-parameter creation tool with a nested metadata object.

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 params, a nested metadata object, no output schema and no required fields, the description should explain what the created customer response contains, what happens on duplicate email/external_id, and the retry hazard implied by idempotentHint=false. It covers none of this, leaving the caller to guess on a non-idempotent write in an open-world system.

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

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

Schema description coverage is only 50%: country, metadata and external_id are documented in the schema, but name, email and locale carry no explanation anywhere. The description compensates for none of this, so an agent gets no guidance on formats, constraints, or that external_id uniqueness can cause rejections.

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 is effectively a restatement of the tool title 'Create a customer' with no additional specificity about scope, resulting object, or differentiation from the many sibling create_* tools (create_subscription, create_invoice, etc.). An agent learns nothing about the tool beyond its 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?

'Test keys only: refused with a live key' is an environment constraint rather than usage guidance — it does not say when to create a customer versus calling retrieve_customer/list_customers, nor what prerequisites exist (all six params are optional, and no required field is named). The one useful constraint is stated, but no alternatives or exclusions are given.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), the description discloses real operational traits: the 403 `bill_overdue` refusal while a Perly Pay bill is unpaid past 14 days, that already-created invoices are still paid, that test keys only are accepted, and that payment happens out-of-band at `url` in bitcoin or a stablecoin. It stops short of describing what the created object contains or any rate limits, so not 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?

Front-loaded with the one-line purpose, then dense but non-redundant sentences covering line shapes, customer form, discount scope, payment rail, and key-mode constraints. No filler and no repetition of schema field definitions verbatim.

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

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

For a 13-parameter mutation with nested objects and no output schema, the description covers the primary composition paths and error behavior well, but leaves several parameters (`coupon`, `locale`, `metadata`, `subscription`, `expires_in_minutes`) with no narrative, including `coupon` and `locale` which have no schema description either. It also never indicates what is returned (id, `url`, status), which an agent needs to chain a follow-up retrieve_invoice or simulate_payment 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?

With 77% schema coverage the baseline is 3, and the description adds genuine meaning on top: it explains the two line shapes and that `amount` + `description` is shorthand for a single line, that all lines share one currency, that `customer` accepts an id or `{ email }`, and that `discount` is scoped to this invoice alone. It leaves `coupon`, `locale`, `metadata`, `subscription`, and `expires_in_minutes` unaddressed, which keeps it at 4.

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

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

The opening line states a specific verb and resource ("Create an invoice"), and the body clarifies the resource's shape (lines, customer, discount, pay url). It never names a sibling it is not, so an agent must still infer when to prefer create_invoice over create_payment_link or create_checkout_session, which keeps it below 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?

Usage is implied rather than stated: the buyer pays at `url`, and the tool is refused in live mode under an overdue-bill condition or with a live key against test mode. There is no explicit "use X instead when..." routing against the many create_* siblings, so the agent gets context but not alternatives.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, openWorld=true, so the safety profile is covered. The description adds non-obvious context the annotations cannot: the tool is refused under a live key, and the output is a hosted page at /l/<slug>. It omits slug-collision behavior and whether the returned link is retrievable later.

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 short sentences, front-loaded with the creation action, then the artifact model, then the key restriction. Zero filler for the amount of information conveyed.

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?

An 8-parameter creation tool with a nested object, no output schema, and half the parameters undocumented in the schema. The description does not say what is returned (presumably a link with slug and URL) nor explain the four boolean options, leaving an agent unable to configure or follow up on the call from the text alone.

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 50% and the description contributes no parameter meaning at all — it never mentions price, slug, quantity, metadata, or success_url. Four parameters (quantity, collect_name, allow_coupons, adjustable_quantity) are completely undocumented in both schema and description, so the description does nothing to 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?

Specific verb+resource ('create a payment link') followed by a concrete definition of the artifact: a page at /l/<slug> that sells one price, shareable or openable with pay.js. That is materially clearer than the title alone. It stops short of distinguishing it from the nearby create_checkout_session / pay_links siblings, which occupy overlapping territory.

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?

'Share it anywhere, or open it with pay.js' implies the delivery modes, and 'Test keys only: refused with a live key' is a real usage constraint. But there is no guidance on when to pick this over create_checkout_session, nor on prerequisites like having an existing price id.

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

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

Beyond the annotations, the description discloses that amounts are immutable and that test keys are refused with a live key, both operationally important. The annotations already cover readOnly=false, idempotent=false, and destructive=false, so the added constraints are meaningful; the only gap is that the created object's return shape is not described.

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

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

The description is dense but well organized: the model list is front-loaded and the per-model required-field mapping follows immediately. It is appropriately sized for a 12-parameter nested tool, though there is minor overlap between the model enumeration and the body-requirements paragraph.

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

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

For a complex creation tool with nested objects and no output schema, the description supplies the critical conditional requirements, immutability rule, and key restriction. It leaves the response format and some optional-field semantics to the schema, which is acceptable given the schema's documentation.

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 50% schema description coverage across 12 parameters, the description carries important weight by mapping each pricing model to its required fields (e.g., fixed_term needs term_days, subscription needs recurring), which the flat schema cannot express. It does not explain optional parameters like refunds, metadata, or nickname details, but those are partially documented in the schema.

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

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

The description states a specific verb and resource ('Create a price') and enumerates the six supported pricing models, which is far more than a tautology. It does not explicitly name sibling tools such as update_price or list_prices, so sibling differentiation is only implied by the immutability sentence.

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 through the per-model requirements and the note that amounts are immutable, which tells the agent to create a new price rather than modify one. However, it does not explicitly name alternatives like update_price or explain when to prefer this tool over creating a checkout session or subscription.

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=true, so the mutation profile is covered structurally. The description's added value is the test-key-only restriction, which is real behavioral context, but it says nothing about duplicate-name behavior, non-idempotency consequences, or what a refusal 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?

Two short sentences with no filler, and the core purpose is front-loaded ahead of the environment constraint. It is efficient, though the brevity is partly 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?

This is a 7-parameter mutation with a nested metadata object, no output schema, and no annotation covering return behavior, yet the description never mentions what is returned (e.g., an ID needed for create_price) or how nested metadata behaves on creation. For a create endpoint with this much schema surface, the description is too thin.

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 43% across 7 parameters, so the description needs to compensate and adds nothing about any parameter. Fields such as name, active, image_url, and description have no descriptive text anywhere, leaving the agent to infer semantics from property names 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 states a specific verb and resource ("Create a product"), so an agent immediately knows the operation. It does not distinguish this from siblings like update_product or list_products, but the create-vs-update split is largely self-evident from 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?

The "Test keys only: refused with a live key" line is a genuinely useful precondition that tells the agent when this call will fail. However, it offers no guidance on when to create versus update a product, or what to do after creating one (e.g., create_price).

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 exceeds the annotations: it explains the emailed address link is never returned because the holder decides where funds go, what happens with no email on the invoice, the resulting `ready_to_send`/`amount_to_send` state, the `sanctioned_sender` refusal and why not to retry, and the test-key-only restriction. This is exactly the side-effect and failure-mode detail an agent needs on a destructive call.

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 its result, then failure modes then the irreversibility warning. Dense with useful information, though the sanctions aside ('leave it and talk to a lawyer') is slightly discursive for a tool 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?

For a destructive mutation with no output schema, the description supplies the outcome states, the refusal code, the confirm gating, and the test/live key constraint — enough for an agent to call it correctly and interpret the result without further documentation.

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 the schema already documents `amount` (default = everything refundable), `confirm`, and `invoice`. The description reinforces the confirm gate ('Ask the person first'), but the `reason` parameter is described in neither the schema nor the description, and no amount/reason format guidance is added beyond what the schema states.

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

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

States a specific verb and resource ('Open a refund', 'Starts a refund in the asset that was paid') and immediately scopes it to the paid invoice, distinguishing it from the read-only siblings like list_refunds. An agent knows exactly what this creates 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?

Gives a concrete precondition — 'Ask the person first, then call with confirm: true' — and instructs the agent to stop and escalate when the `sanctioned_sender` refusal occurs. It does not name an alternative tool (e.g. against cancel_invoice), but the when-to-use context is clear.

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

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

Annotations already flag a non-idempotent, non-destructive write in an open world, so the description's contribution is the state machine: the first invoice is issued immediately via `latest_invoice` when there is no trial, and the subscription only becomes active once that invoice is paid. That, plus the live-key refusal, is real behavioral context an agent cannot infer from the annotations. It still omits what happens on failure or what identifier is returned.

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 short paragraphs with the constraint front-loaded and zero filler; every sentence carries information. The only wasted line is the opening 'Create a subscription', which duplicates the title verbatim.

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

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

For a non-idempotent creation tool with a nested metadata object, no output schema, and 67% param coverage, the description covers lifecycle and key restrictions but leaves the agent guessing about prerequisites (must the customer and price already exist?) and what the response contains. It is adequate to attempt the call but not to call it 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 coverage is 67%, so the description is expected to fill gaps and it does not — coupon, quantity, metadata, and the price/customer interactions are never mentioned. The one parameter-adjacent statement (trial timing) describes the consequence of omitting `trial_days` rather than explaining any of the six inputs.

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 opening line 'Create a subscription' merely restates the tool name and title, and the rest of the text describes a billing lifecycle rather than the operation itself. The 'renewed by invoice' detail hints at a specific collection mode, but it never states that this is one of several ways to start a paid relationship (checkout session, payment link, invoice), so the sibling boundary stays blurry.

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 only explicit guidance is a hard constraint — 'Test keys only: refused with a live key' — which is valuable but is a precondition, not a when-to-use rule. Nothing says when to prefer this over create_checkout_session, create_payment_link, or create_invoice, all of which sit in the sibling list and could plausibly start the same billing relationship.

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 context the annotations don't carry: the response includes a one-time `secret` used to verify the `Perly-Signature` header, and live keys are refused. That is exactly the operational detail an agent needs. It still omits what happens with duplicate URLs or how event defaults apply, so it isn't exhaustive.

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

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

Four short sentences, front-loaded with purpose, then the secret caveat, then the key restriction. Every sentence carries information the agent would otherwise miss.

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 small mutation tool with annotations covering safety and no output schema, this is close to sufficient — it explains the critical return value and the key restriction. Only the parameter-level details (URL format, description semantics) are left entirely to the bare 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 33% — `enabled_events` is described in the schema, while `url` and `description` have no descriptions anywhere. The tool description says nothing about URL requirements (HTTPS, reachability) or length limits, so it fails to compensate for the 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 concrete verb and resource ('Create a webhook endpoint'), which is unambiguous on its own. It never explicitly contrasts itself with create_* siblings or with list/delete_webhook_endpoint, so it stops short of full 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?

'Test keys only: refused with a live key' is a real precondition that steers the agent, which is more than most definitions offer. There is still no guidance on when to create vs. reuse an existing endpoint, or on related tools such as verify_webhook_signature.

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 destructive and non-idempotent behavior, and the description adds important context beyond that: it is irreversible, the endpoint's events stop, live keys are refused, and explicit human confirmation is required. This is exactly the behavioral detail an agent needs before invoking a destructive tool.

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

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

The description is only three short sentences and front-loads the most important constraints: deletion, test-key restriction, irreversibility, and confirmation. Every sentence adds actionable value.

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

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

For a destructive, no-output-schema tool, the description covers the crucial context: irreversibility, side effects on events, key restrictions, and the required confirmation workflow. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents both id and confirm. The description reinforces the confirm workflow but does not add new semantics beyond what the schema states, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: deleting a webhook endpoint. It is immediately distinguishable from sibling tools like create_webhook_endpoint and list_webhook_endpoints.

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 usage context: test keys only, live keys are refused, and a human must agree before calling with confirm true. It does not name sibling alternatives, but the destructive nature and key restriction make the intended context clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description still adds real behavior: results are ordered newest-first and paging is cursor-based by returning `next_cursor` as `cursor`. It does not say what a spend record contains or whether filters combine, but the essential call mechanics are disclosed.

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, zero filler, with the resource and the ordering stated up front and the pagination mechanic following. Every clause earns its place.

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

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

Five optional filters, no output schema, and rich annotations mean the structured data covers a lot, and the description adequately covers ordering and paging. However, it never explains what a credit spend is or how the action/product/customer filters interact, leaving an agent to infer the tool's role in the credits workflow.

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

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

Schema description coverage is 100%, with every parameter documented including the `next_cursor`-to-`cursor` handoff, so the schema carries the parameter burden. The description's pagination sentence restates what the `cursor` field already says, adding no new semantics for `action`, `product`, or `customer`. 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 ("List credit spends") that clearly maps to the billing/credits domain, and the resource is distinct enough from siblings like list_invoices or list_payments that an agent can tell them apart. It stops short of explicitly contrasting itself with any sibling, 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?

There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or typical contexts (e.g., reconciling spend per customer or product). The only procedural instruction is the pagination loop, which is mechanics rather than 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, so safety is covered. The description adds real behavioral context the annotations do not: results are ordered newest first, and paging is cursor-based with `next_cursor` fed back as `cursor`. It stops short of mentioning rate limits, default page exhaustion behavior, or whether filters are ANDed.

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, zero filler, and the ordering plus paging rule arrives immediately after the purpose line. Nothing here is padding.

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

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

There is no output schema, so the description carries the burden of describing what a customer record contains, yet it says nothing about returned fields or object shape. Ordering and paging are well covered, but filter behavior and result contents are missing for a 4-parameter list tool.

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

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

Schema coverage is 50%: `limit` and `cursor` are already documented in-schema, and the description only repeats the cursor contract. The undocumented `email` and `external_id` filters receive no explanation of match semantics (exact vs. partial, case sensitivity) anywhere, so the description fails to compensate for the coverage gap. Baseline 3 for a half-covered 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?

"List customers" merely restates the tool name and title; the sentence adds no verb beyond the name and no scope, filters, or resource detail. The only distinguishing content is the pagination note, which is about mechanics rather than purpose.

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

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

No guidance on when to list versus retrieve_customer, or how this relates to list_subscriptions/list_invoices when a customer is needed. The only actionable direction is passing `next_cursor` back as `cursor`, which is paging mechanics, not tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: results come newest-first and paging is a cursor hand-off (`next_cursor` → `cursor`). It still says nothing about total counts, empty results, or truncation, so it is useful but not rich.

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

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

Two short sentences, no filler, with the pagination mechanic front-loaded in the second sentence. Brevity is near-optimal, though the first sentence is pure redundancy with the name.

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?

No output schema exists, so the description should convey the shape of returned entitlements, but it never does. Annotations and a fully documented schema cover safety and inputs, so the definition is callable, but the agent cannot predict what an entitlement record contains or how filters interact.

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 each parameter is documented in the schema, so this is the baseline. The description only reinforces the `cursor` semantics that the schema already states ("`next_cursor` from the previous page") and adds no detail on `product`, `customer`, or `subscription` filtering or whether they combine.

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?

"List entitlements" restates the tool name and title verbatim, so the first sentence adds no information. The second sentence describes ordering and pagination behavior rather than what entitlements are or what scope they are listed in, leaving the agent unable to distinguish this from `check_entitlement` or `list_credit_usage`.

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 `check_entitlement` (single lookup) or `list_credit_usage`, and no mention of whether filters must be combined or which one to pick. Usage is only implied by the tool name; there are no exclusions or context cues.

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 open-world, so safety is covered. The description adds real behavioral context beyond that: a default 30-day window, newest-first ordering, and cursor-based pagination with the `next_cursor` -> `cursor` contract. It does not say what fields an event object carries or whether the window can be extended.

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 short lines, front-loaded with the resource then the semantics. Slight redundancy in repeating 'newest first' twice, 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 four-parameter read-only list tool with no output schema, the description covers ordering, default time window, filtering, and pagination — everything needed to call it correctly and to consume the response. The remaining unknown (event payload shape) is a low-risk gap for a listing endpoint.

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%, and the one undocumented parameter — `type` — is exactly what the description explains, including wildcard syntax (`invoice.*`) and a concrete example (`invoice.paid`) that the bare regex pattern does not convey. The cursor round-trip is also restated. `limit` and `object` are left to the schema, which documents them adequately.

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 events') and immediately scopes it: 'What happened in the last 30 days, newest first.' That tells an agent this is a recent-activity feed rather than an arbitrary query. No sibling tool lists events, so no explicit differentiation is needed, which is why this lands at 4 rather than 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?

Usage is implied by the framing question ('What happened in the last 30 days') and by the `type` filter examples, but there is no explicit when-to-use or when-not statement, nor any pointer to a related tool for deeper per-object inspection (e.g., retrieve_invoice). An agent must infer that this is the audit/activity feed.

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, and destructiveHint=false, so the safety profile is covered. The description contributes genuinely new behavior — default sort order (newest first) and the exact cursor round-trip contract for pagination — which annotations do not express. It stops short of noting whether filters are ANDed, whether unpaginated results are possible, or what happens past the last page.

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 no filler, and the operationally important pagination rule is stated directly. The first sentence carries no information the agent doesn't already have from the name, which is the only real waste. Structure is front-loaded with the high-value pagination note following immediately.

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?

Five optional parameters, one undocumented enum, and no output schema mean the agent has to guess at return shape and filter semantics. The description covers pagination but is silent on the four filtering parameters that make this more than an unfiltered dump. Adequate for a simple list call, but thin given the schema breadth.

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

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

Schema description coverage is 80%, so baseline is 3; the cursor line largely repeats the schema's own "`next_cursor` from the previous page." The status enum has no per-value explanation and the customer/subscription filters are never mentioned in the description. No extra meaning is layered on top of the schema beyond clarification of the cursor 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?

"List invoices." is a near-verbatim restatement of the tool name and title, adding no scope, filtering capability, or object qualification. The second sentence adds real information but is about pagination rather than identity. An agent can infer the purpose from the name, but nothing distinguishes it precisely from siblings like retrieve_invoice or list_payments.

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 retrieve_invoice when an id is known, nor on how the status/customer/subscription filters should be combined. The cursor instruction describes how to page, not when to select this tool. The agent must infer usage entirely from the name and schema.

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 value beyond that by disclosing result ordering ('Newest first') and the cursor round-trip contract, which an agent cannot infer from annotations. It stops short of noting default page size or whether filters combine.

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, ordering and pagination front-loaded, zero filler. The opening 'List payment links.' is a near-verbatim restatement of the title, 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 zero-required-parameter list tool with no output schema, the description covers pagination and ordering but leaves the agent guessing about the returned object shape and filter behavior. Nothing is wrong, but a bit more on what a page contains and how filters interact would make it 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 75%, so most parameters are self-documenting. The description only touches `cursor`/`next_cursor`, and that largely restates the schema's own 'next_cursor from the previous page'. The `active` filter and the `price` filter's semantics (e.g., whether it narrows to links for a single price) get no explanation.

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') that clearly contrasts with the create_payment_link and update_payment_link siblings. It adds the ordering semantics ('Newest first'), but does not explicitly differentiate itself from other list_* siblings or state scope (all links vs. filtered).

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

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

The description gives a concrete pagination protocol (pass `next_cursor` back as `cursor`), which is genuinely actionable, but it never says when to use this tool versus the other listing tools or what conditions make a call appropriate. Usage is implied by the name 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?

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new behavioral facts not in the annotations: results are chain-derived transfers into addresses the platform issued, and they are returned newest-first with cursor pagination.

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 short lines, front-loaded with the verb and the definition, then pagination. Minor waste: "newest first" is stated twice in consecutive sentences, which is redundant rather than harmful.

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 does enough by defining what a payment record represents and how to page through results. The remaining gap is that it never signals the response is filterable by asset or invoice, so an agent may issue unfiltered or mis-scoped calls it could have narrowed.

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% and `limit`, `cursor` and `invoice` are already documented in the schema; the description's cursor-pagination sentence largely restates the `cursor` field. Critically, it never mentions the `asset` enum filter, the one parameter whose schema entry carries no description.

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 and goes further by defining what a payment is: "Transfers seen on chain into addresses we handed out." That domain definition meaningfully separates it from siblings like list_refunds or list_invoices, though it never names an alternative tool 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?

The description explains pagination mechanics (pass `next_cursor` back as `cursor`), which is procedural guidance, but gives no when-to-use vs when-not guidance and never mentions the available `asset` or `invoice` filters that would steer an agent's invocation. Usage is implied by the tool name and domain sentence only.

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 openWorldHint, so the safety profile is covered. The description usefully adds ordering ("newest first") and the cursor round-trip pattern, but says nothing about default filtering, whether inactive prices are included, or result size behavior beyond the schema default.

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 no filler, and the pagination rule is front-loaded right after the purpose statement. Nothing is redundant, though the space is used almost entirely on pagination at the expense of filters.

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, five optional filters of which only some are documented, and enum values with unspecified semantics (e.g., what `active` does), the description leaves an agent guessing about result composition. It should at least state default filtering and what the returned price objects represent.

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

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

Schema coverage is 60%; the model and active enum parameters have no descriptions at all. The description spends its only parameter mention on cursor, which the schema already documents ("`next_cursor` from the previous page"), so it does not compensate for the undocumented filters an agent most needs to understand.

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?

"List prices" restates the tool name and title verbatim, adding no scoping detail beyond the title. It doesn't clarify what kind of prices, whether all are returned regardless of active/product state, or how this differs from create_price/update_price.

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 indication of when to use this list versus filtering by product or model, or which optional filters matter. Usage is only implied by the tool name. Pagination instructions describe mechanics, not when to choose this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: result ordering (newest first) and the pagination contract. It stops short of describing result shape or page-size behavior default, which matters since there is no output 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?

Two short sentences, front-loaded, with the operational detail (pagination) where an agent will read it. The opening sentence is essentially the title restated and could carry more information, but nothing is padded.

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?

Pagination is fully covered, which is the main complexity for a list tool, and annotations cover safety. Combined with the absent description for `active` and no output schema to explain the returned product shape, an agent still lacks enough to use the filter 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?

At 67% schema coverage, the two documented parameters (limit, cursor) already carry their own descriptions, and the description's cursor guidance largely restates the schema. The `active` parameter has no description anywhere and is a string enum of "true"/"false" – a filter whose semantics the description never clarifies, leaving the most confusing parameter unexplained.

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 ("List products"), which is sufficient to separate it from the create/update/retrieve product siblings and from list_prices, list_customers, etc. The name-plus-scope is unambiguous, though the body adds no further scoping detail to sharpen that distinction.

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

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

"Newest first" plus the cursor round-trip gives an agent the pagination workflow, so usage is at least implied. However there is no guidance on when to choose this over siblings, no mention of the `active` filter as a selection lever, and no stated 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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful operational context: a deterministic order (newest first) and the pagination contract (feed `next_cursor` back as `cursor`), which the annotations cannot 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?

Very tight and front-loaded; the receipt semantics come first, pagination last. The only waste is the redundant 'newest first' stated in two consecutive sentences.

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 should carry the return-shape burden; it partially does by implying a `next_cursor` field and newest-first ordering. It still omits what filters exist, whether results span all invoices, and default page size behavior for a four-parameter list endpoint.

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 75% — `limit`, `cursor`, and `invoice` are documented in the schema, but the `kind` enum has no description anywhere. The description echoes the cursor mechanics but never explains that `kind` filters to payments vs refunds or that `invoice` scopes to one invoice, so it fails to close the 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?

Specific verb+resource ('List receipts') plus a clarifying scope statement — one entry per fulfilled payment and each confirmed refund. That tells the agent what a receipt is relative to list_payments/list_refunds, though it never names those siblings 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?

No when-to-use or when-not guidance, and no mention of the available narrowing filters (`kind`, `invoice`) that would decide between this tool and list_payments/list_refunds. The agent must infer the choice purely from the tool 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds the ordering guarantee ('newest first'), which is genuinely new context. The cursor mapping it states largely restates the schema's own cursor description, and nothing is said about filtering behavior or result size.

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 no filler, and the resource identification is front-loaded. It is efficient but borderline thin given the filtering capabilities left unmentioned.

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 paginated list tool with annotations covering the safety profile, the essential calling information (ordering, pagination) is present. Gaps remain around the status/invoice filters and the shape of returned refund objects, but no output schema exists to cover that.

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 self-documenting; limit and cursor are well described in the schema. The description adds nothing about the `status` and `invoice` filters — notably the status enum has no schema description, so its filtering semantics remain undocumented anywhere.

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 refunds'), which cleanly separates it from create_refund. It does not, however, distinguish it from other listing siblings such as list_payments, list_invoices, or list_receipts.

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 the other list_* tools or when to combine it with retrieve_invoice. The only procedural hint is pagination mechanics, not tool selection.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds two genuinely new behavioral facts: default ordering (newest first) and the pagination contract. It says nothing about result shape, page-size behavior, or whether filtering narrows ordering, so this is useful but thin.

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, no filler, with the pagination hint front-loaded after the identity statement. Efficient, though the first sentence is pure repetition of the title and earns little.

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 does not describe the returned subscription objects, and for a 5-parameter list tool it never acknowledges that filtering by customer, price, or status is even possible. Ordering and pagination are the only completeness wins.

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

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

Schema description coverage is 80%, so the baseline is 3. The description only reinforces the cursor parameter ('next_cursor' as 'cursor'), which the schema already states; it says nothing about the filter parameters (price, status, customer) or limit semantics that an agent would need to use them confidently.

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 first sentence is essentially a restatement of the tool name and title ('list_subscriptions' / 'List subscriptions'), adding no scope, filter, or resource detail. An agent can tell it lists subscriptions, but nothing in the description explains what kinds of subscriptions or what distinguishes it from retrieve_subscription beyond the obvious verb.

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 pagination instructions ('pass next_cursor back as cursor for the next page') give actionable procedural guidance for iterating results. However, there is no guidance on when to use this versus retrieve_subscription, or which filters to apply for common tasks, so usage is only partially 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds two genuinely useful traits beyond that: results are ordered newest first, and pagination is a cursor round-trip. It stops short of noting rate limits, filterability, or what an endpoint record 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?

Two short sentences, zero filler, with the ordering and pagination constraint front-loaded where an agent will read it before calling. Nothing in it is redundant with the tool name alone.

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-optional-parameter read-only list tool with no output schema, the description covers ordering and how to continue paging, which is the main thing an agent needs to iterate correctly. It omits only minor details such as what terminates the cursor chain or what fields an endpoint exposes.

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

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

Schema description coverage is 100% and both parameters are documented there, including the 1–100 bounds on limit. The description's note about passing `next_cursor` back as `cursor` largely restates the schema's own wording, so it adds little beyond the baseline.

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

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

States a specific verb and resource ("List webhook endpoints"), so an agent knows immediately what it retrieves. It does not explicitly differentiate itself from the sibling create_webhook_endpoint / delete_webhook_endpoint, though the verb makes the distinction obvious in practice.

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 by the verb — the description never states when to call this versus create_webhook_endpoint or delete_webhook_endpoint, nor any prerequisites. The second sentence addresses pagination mechanics rather than selection guidance, leaving context 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, non-destructive and openWorldHint=false. The description adds crucial context beyond them: these are human-only steps with no API-key path, and the intended interaction is to hand the link to a person. It doesn't describe the response shape, but with no output schema and annotations covering safety, this is a strong add.

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

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

Two sentences, front-loaded with the resource and scope, and the second sentence delivers the actionable instruction. The topic enumeration is long but each item maps to a real page, so it largely earns its place; minor redundancy with the enum values.

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 optional-enum parameter tool with no output schema and rich annotations, the description supplies the human-in-the-loop context an agent needs to use it correctly. Only the returned link/format is unstated, which is a minor gap given no output schema exists.

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 enum property already has a description ('One page; all of them when left out'), establishing the baseline of 3. The body enumerates the topic meanings and adds a nuance like '(public key only)' for connect_wallet, but mostly restates what the enum values already convey. Adequate but not materially 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 resource ('Perly Pay dashboard pages') and scope ('steps no API key can take'), enumerating exactly which pages it covers. An agent can distinguish this from sibling action tools because it returns links rather than performing the actions. It never states the bare verb 'returns URLs', relying on the phrase 'Give the person the link' to imply output, which keeps it just 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?

It tells the agent both when to use it ('steps no API key can take') and what to do with the result ('Give the person the link and say what to do there'), plus an explicit exclusion ('do not try these through other tools'). The negative guidance rules out attempting these tasks via sibling tools, which is exactly the routing decision an agent needs.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds no behavioral context of its own — nothing about error behavior for unknown ids, whether expired sessions are returned, or what state the session comes back in.

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 one short sentence with no waste, so it is not verbose — but this is under-specification rather than earned conciseness. The single sentence adds no information beyond the title, so it does not justify its own length as a useful signal.

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 itself is simple (one id, rich annotations), but with no output schema the description is the only place to explain what a retrieved checkout session contains (status, line items, amount, expiration). It supplies none of that, leaving the agent unable to predict the response 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?

There is a single required parameter with 100% schema coverage ('The object's id.'), so the schema already carries the parameter meaning. The description adds nothing on identifier format (e.g., cs_ prefix) or where to source the id, which is the baseline-3 outcome when the schema does the heavy lifting.

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

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

The description 'Retrieve a checkout session' merely restates the tool name and title verbatim, adding no specificity about what a checkout session is or what retrieval returns. It does not distinguish this tool from siblings like retrieve_customer, retrieve_invoice, or retrieve_subscription, which follow the same pattern.

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 tool versus alternatives such as list_* or create_checkout_session. The id-only schema implies lookup-by-identifier, but the description never states preconditions, when-not-to-use, or how to obtain a valid id.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — notably it does not mention openWorldHint=true, meaning a live API call that can fail or return not-found, which is the one behavior an agent would benefit from knowing.

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 with no filler, but the brevity is under-specification rather than efficiency — the single sentence does no work beyond naming the operation, so it fails to earn its place as the only guidance provided.

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 openWorldHint=true, the description should explain that this performs an external lookup and can fail for an unknown id. For a retrieval tool whose result shape is otherwise undocumented, the definition leaves the agent without enough to call it 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 100% with a single required id parameter, so the baseline of 3 applies. The description contributes no additional meaning about the id (e.g. format or prefix) beyond the schema's "The object's 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?

"Retrieve a customer" restates the title and tool name almost verbatim, adding only a verb+resource pairing. It does not distinguish this from list_customers or create_customer in the sibling set, nor state what identifying information is needed or returned.

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

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

No when-to-use guidance is given, and no alternative is named. An agent must infer on its own that this takes a single id and that list_customers is the bulk alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds nothing on top — no mention of error behavior for missing IDs, required auth, or what the returned 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?

One short, front-loaded sentence with no filler, but the brevity comes at the cost of under-specification rather than efficient communication.

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, so little is required, but with no output schema the description should at least hint at what the retrieved invoice contains or how a bad ID is handled. It provides none of that.

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 there is a single required 'id' parameter, so the baseline is 3. However, the schema's phrasing 'The object's id' is generic and the description does not clarify that this must be an invoice ID rather than a customer or payment 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 'Retrieve an invoice' merely restates the tool name and title with no added specificity. It does not distinguish this from sibling list_invoices or explain what 'retrieve' returns beyond a single invoice 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?

No guidance on when to use this versus list_invoices, retrieve_payment, or retrieve_receipt. The agent must infer that this is the single-object lookup counterpart to the list endpoints.

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 and destructiveHint=false, so the safety profile is covered elsewhere. The description adds no behavioral context of its own — not what happens on a missing/invalid id, nor what a payment record contains — so it contributes nothing beyond the structured fields.

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

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

It is a single short sentence, so nothing is bloated, but the sentence does not earn its place — it duplicates the title without adding information. Brevity here comes from under-specification, not from disciplined editing.

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 and full schema coverage, little is strictly required, and no output schema means return values need not be explained. Still, the absence of any hint about locating an id or relating this to list_payments leaves an agent with no routing context.

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

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

Only one parameter, id, and schema description coverage is 100%, so the baseline is 3. The description does not clarify whether the id is a payment id versus a customer/invoice id, but the schema already 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?

"Retrieve a payment" restates the tool name and title verbatim, adding nothing. It does name a resource but gives no differentiation from list_payments or the many sibling retrieve_* tools, so it reads as a tautology rather than a purpose 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?

There is no guidance on when to use this versus list_payments (to discover an id) or retrieve_invoice/retrieve_receipt for adjacent objects. No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered structurally. The description adds nothing beyond that – no note on not-found behavior, error handling, or what a receipt 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?

A single short sentence with no waste, but this is under-specification rather than conciseness. There is no front-loaded scope or qualifier to make the brevity useful.

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 tool with full annotation coverage and a fully described schema, less is required, but there is still no mention of what is returned, whether receipts are grouped under invoices/payments, or what happens on a missing id. With no output schema, the description leaves an agent guessing.

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?

Only one parameter (id) exists, and the schema describes it at 100% coverage, so the schema carries the documentation burden entirely. The description neither clarifies the id format (receipt id vs. related object id) nor adds anything, but baseline 3 applies given full schema coverage.

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

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

The description is "Retrieve a receipt" – a verbatim restatement of the tool name and title, with no elaboration. It conveys a verb and resource but nothing that distinguishes it from siblings like list_receipts or retrieve_payment.

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 indication of when to use this versus list_receipts (for listing) or retrieve_payment/retrieve_invoice (for related lookups). The only implied usage comes from the name itself, not from any guidance in the description.

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 and destructiveHint=false, so the safety profile is fully covered; the description contributes nothing beyond that. It does not mention error behavior for unknown ids, nor any auth or rate-limit context that would add value.

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

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

It is a single short sentence with no filler, but that brevity comes from under-specification rather than tight editing; nothing is front-loaded because there is nothing to 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 lookup-by-id tool with no output schema, the description should say what is returned or what happens on a missing id. Annotations cover the safety profile and the schema covers the parameter, but the agent still learns nothing about the response or failure modes.

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?

Only one parameter exists and schema description coverage is 100% ('The object's id.'), so the schema carries the burden and the baseline is 3. The description adds no syntax hint (e.g. a 'sub_...' prefix) or detail about what the id identifies.

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 'Retrieve a subscription' merely restates the tool name and title verbatim, adding no scope, no resource qualifiers, and no differentiation from siblings like list_subscriptions or retrieve_invoice.

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 tool versus list_subscriptions for browsing, nor any stated prerequisites such as required permissions or the id format. The agent must infer everything 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 only tell the agent this is a non-readonly, open-world, non-idempotent, non-destructive write; the description adds the substantive behavior: the invoice becomes paid and fulfilled, entitlements and license keys are issued, a receipt is generated, and webhook events fire. It also discloses the hard access constraint — test keys only, refused with a live key — which is nowhere in the annotations and materially changes whether the call is attempted.

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?

Purpose and test-mode restriction are front-loaded, and every sentence carries information. It is dense and somewhat run-on, packing defaults, side effects, and preconditions into long em-dash clauses that take a second read to parse.

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

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

For a mutation tool with no output schema and 60% param coverage, the description covers what's created, what the outcome modes do, how chain/asset resolve, and the auth constraint. The only unchecked box is the exact response payload, which retrieve_payment can supply.

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

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

Schema coverage is 60%, and the description compensates for the gaps: `chain` and `asset` have no schema descriptions at all, yet the description explains their default resolution and the refund-terms-accepted side effect. It also clarifies the mutual exclusivity of `id` and `payment_link` and the default of `outcome` to `full`, plus the underpaid/overpaid semantics the enum names do not convey.

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 names a specific verb and resource (simulate a payment) and immediately scopes it to test mode, which separates it from every live-money sibling in the list (create_refund, pay_links, create_checkout_session). The follow-on sentences spell out exactly what the outcome variants mean, so the agent knows what the tool will actually do before 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 concrete preconditions: `short` and `over` need the buyer's chain and asset chosen first, and `full` will auto-select the first stablecoin when no chain exists. It also explains the id-vs-payment_link entry path. It stops short of naming alternatives (e.g. when to use pay_links or create_checkout_session instead), so no exclusions are 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?

The annotations already declare the mutation profile: readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds a useful behavioral constraint that a live key will be refused, but it does not explain which updates are destructive, how partial updates behave, or any rate limits or permissions beyond the test-key restriction.

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

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

The description is two sentences with no filler and places the purpose first, followed by the test-key constraint. It is structurally efficient, though its brevity leaves important gaps that are reflected in other dimensions rather than in wasted language.

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 8-parameter update tool with only 25% schema description coverage, no output schema, and nested metadata semantics, this description is far too sparse. It does not describe update behavior, field-level effects, return shape, or how omitted versus provided fields are handled.

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 25% across 8 parameters, and the description provides no parameter semantics at all. Six parameters are undocumented in the schema and entirely absent from the description, so an agent gets no help understanding fields like quantity, success_url, or collect_name.

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 first sentence, "Update a payment link," restates the tool name and title without adding any distinguishing detail. It does not clarify what kinds of updates are possible or how this differs from create_payment_link, list_payment_links, or pay_links.

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 only guidance is the operational note "Test keys only: refused with a live key." It does not explain when to use this update tool versus alternatives such as creating a new payment link or using pay_links.

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

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

Goes well beyond the annotations by disclosing field-level update semantics: `refunds` is replaced wholesale with omitted subfields reverting to defaults, `metadata` is merged (empty value deletes a key), and amount/model are immutable. It also flags the environment gate (test keys only), which is exactly the kind of operational constraint an agent cannot infer from structured data.

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 editable field list before the constraints. The middle sentence is a telegraphic fragment ("Nickname, active, refund terms ... and metadata.") that reads as terse rather than wasteful.

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

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

Covers the mutation semantics, immutable fields, and key restriction for a 5-parameter tool with a nested object and no output schema. It does not describe the response shape, but nothing critical for invoking 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?

At 60% schema coverage the description adds real value by explaining the differential semantics of the updatable fields (whole-replacement vs. merge) that the schema only partially documents for `metadata` and not at all for `refunds`. The phrase "what you leave out takes its default" is slightly ambiguous about whether it applies to the refunds object or its subfields, but the intent is recoverable.

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?

Specific verb + resource ("Update a price") that is unambiguous against siblings like create_price, list_prices, or update_product. It does not explicitly name an alternative, but the resource noun does the differentiating work.

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 exclusion boundaries: amount and pricing model cannot be changed here, and all calls must use a test key (live keys are refused). It stops short of naming an alternative tool for changing amounts, but the eligibility constraint is clear enough to route 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?

With destructiveHint=true and openWorldHint=true already declared, the description adds real context the annotations cannot: the no-delete invariant, the reason (invoices reference products), and a test-key-only restriction that will hard-fail on live keys. It doesn't say whether unspecified fields are preserved or whether the call replaces state, which matters for an update tool flagged destructive.

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 short, front-loaded lines with no filler; the deactivation guidance and the key restriction both land immediately. The opening "Update a product." largely restates the title and is the one sentence not earning its place.

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

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

The critical operational constraint (test keys only) and the deletion invariant are covered, which is more than most update tools offer. But for an 8-parameter mutation with a nested metadata object and no output schema, the agent still doesn't know whether omitted fields are cleared, what a successful response returns, or how conflicts/validation failures surface.

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 38% across 8 parameters, so the description is expected to compensate, and it only does so for `active` (false = stop selling), the one parameter whose schema entry is bare. `name`, `image_url`, and `description` have no description in the schema or here, and the license-related parameters (issues_license, license_activation_limit) get no explanation of when they apply.

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 first sentence names a specific verb and resource ("Update a product"), so an agent knows exactly which object family it acts on. However, it does not distinguish itself from the nearby siblings create_product, list_products, update_price or update_payment_link beyond the verb, so the sibling boundary 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?

"Set `active: false` to stop selling it; products are never deleted" gives explicit guidance for the common alternative the agent might otherwise reach for (deletion). "Test keys only: refused with a live key" is a hard precondition stated up front. It lacks an explicit "use update_product when X, use create_product when Y" routing sentence, which keeps 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?

Goes well past the annotations by disclosing the algorithm, the five-minute freshness window, and that 'nothing is sent anywhere', which confirms the openWorldHint=false annotation in plain language. It stops short of saying what a failure result looks like (boolean vs. error), which matters for a verification tool with no output 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 purpose and the local/no-network guarantee are front-loaded in the first sentence; the second paragraph carries the raw-body warning. Efficient overall, with only slight redundancy in restating the `secret` default that the schema already documents.

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 four-parameter, read-only tool with no output schema, the description covers the mechanism, the network-free guarantee, and the one non-obvious input pitfall. The remaining gap is the return value: it never says what a success or stale-signature result looks like, which an agent must infer.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns extra credit by adding the operationally critical detail that the body must be raw text captured 'before JSON parsing' — a classic source of false negatives that the schema wording alone would not convey. It otherwise restates the documented default for `secret`.

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 (verifies) plus the exact resource and mechanism: an HMAC-SHA256 check of the Perly-Signature header against the raw body and signing secret. That is clearly distinct from the neighbouring webhook tools (list_webhook_endpoints, create_webhook_endpoint, delete_webhook_endpoint), which all manage endpoint configuration rather than validate a delivery.

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 an explicit use case — 'debug a webhook handler that rejects real events' — and an implicit exclusion by framing it as a local debugging aid, while every sibling tool is a CRUD/configuration action. An agent can decide whether to call it without opening the schema.

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