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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false). The description adds genuine value beyond them by decoding each mode: LIVE means real funds and an ak_live_ key, SANDBOX means testnets only and an ak_test_ key, otherwise public tools only — this key-prefix detail materially affects how the agent interprets results and behaves downstream.

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

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

Two sentences, no waste: the first defines the return states, the second defines the call-to-action. The mode semantics are front-loaded and the usage directive follows, which is the right ordering for a zero-arg diagnostic.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: three mutually exclusive states plus the key-prefix signal that distinguishes them. Nothing an agent needs to call and interpret this tool is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify field-by-field, and it rightly spends no words on 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?

States a specific verb and resource ('returns whether this server is connected to...') and enumerates the three possible states with their operational meaning. An agent can distinguish this diagnostic tool from every sibling mutation/read tool 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?

'Check this before creating, confirming, completing or cancelling anything' gives clear, actionable context for when to invoke it, and the mutation verbs map directly onto sibling tools like payment_intents.create/confirm/cancel. It does not name those siblings explicitly, but the routing intent 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 declare readOnlyHint=false and destructiveHint=true, and the description is consistent with that. It adds genuinely valuable context beyond the annotations: the call requires no API credentials and anyone holding the slug can invoke it, which is a meaningful security/auth disclosure. It does not say whether the cancellation is reversible or what state the pay page is left in afterwards.

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, each carrying distinct information: what it destroys, the credential-free access model, and the credentialed alternative. No filler or repetition.

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

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

For a single-parameter destructive tool with no output schema, the description covers identity, authorization model, and the sibling alternative, which is nearly everything an agent needs. The one omission is post-cancellation state or reversibility, though destructiveHint partially signals this.

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 describes the slug parameter, so the baseline is 3. The description adds locating context — the slug comes from the payment link URL — which slightly sharpens the one parameter beyond the schema wording.

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 (cancel) and resource (payment intent behind a hosted pay page) and pins the identifier to the slug in the payment link URL. It is immediately distinguishable from pay.get_by_slug and from payment_intents.cancel by naming the latter 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?

Explicitly routes the agent: use this slug-based path when no credentials are available, and use payment_intents.cancel when cancelling by Payment Intent ID with credentials. Both the when and the alternative 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 specify readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that retrieval is keyed by hosted pay slug; it does not describe auth needs, rate limits, return behavior, or pagination, which is acceptable but not rich given the annotation coverage.

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

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

The description is a single, front-loaded sentence with no filler. Every phrase contributes to stating the action, resource, and lookup key.

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

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

For a simple read-only lookup with one fully documented parameter and annotations covering safety, the description is nearly complete. It could better distinguish itself from payment_intents.retrieve, but no critical information is missing for invoking the tool correctly.

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

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

Schema description coverage is 100%, and the sole parameter is fully documented in the input schema. The description restates the parameter's purpose ('by hosted pay slug') without adding syntax, format, or source details beyond what the schema already provides.

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

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

The description uses a specific verb ('Get') and resource ('pay / payment intent details') scoped by 'hosted pay slug.' It clearly states what the tool does, though it does not explicitly distinguish itself from siblings like payment_intents.retrieve or pay.cancel_by_slug.

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 no explicit guidance on when to use this tool versus alternatives such as payment_intents.retrieve or pay.cancel_by_slug. The only implied usage comes from 'by hosted pay slug,' which indicates the required identifier but not the scenario.

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

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

Annotations mark this destructive and non-read-only, so safety is covered structurally; the description adds real value by disclosing the state precondition and the return value. It stops short of saying whether a cancellation is reversible, what happens on an already-cancelled/already-paid intent, or if the call is idempotent.

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 action and result, followed by the precondition and the sibling alternative. No filler or repetition.

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

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

No output schema exists, so the description correctly compensates by stating the return value ('Returns the cancelled intent'). For a single-param destructive tool the essential context is present; only edge-case behavior (reversibility, error states) 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?

Only one parameter, and the schema documents it at 100% coverage ('Payment Intent ID'). The description's phrase 'by ID' adds no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Cancel a Payment Intent by ID') plus the return value ('Returns the cancelled intent'). It is clearly distinguishable from siblings like subscriptions.cancel and pay.cancel_by_slug, which is explicitly reinforced.

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 precondition ('Check its status with payment_intents.retrieve first when the customer may already have paid') and routes to the correct alternative for a different context ('To cancel from a hosted pay slug without credentials, use pay.cancel_by_slug'). When-to-use and when-to-use-something-else are both covered.

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 and destructiveHint=true, so safety profile is documented. The description adds the resulting state change ('as processing') and the triggering context, but does not explain why the operation is destructive, whether it is irreversible, or what side effects or authorization needs exist.

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

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

The description is a single focused sentence with no wasted words. The action and trigger are front-loaded, and every part earns its place.

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

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

For a one-parameter mutation tool with no output schema and existing annotations covering safety, the description adequately explains what the tool does and when to use it. It could say more about what happens after marking as processing or whether the call is idempotent, but it is largely complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the single 'id' parameter is fully documented in the schema. The description adds no parameter-specific detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: 'Mark a Payment Intent as processing.' It also gives a distinctive trigger condition ('after the customer returns to your success URL'), which helps separate it from siblings like confirm or update, though it does not explicitly name alternatives.

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

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

The description clearly states when the tool should be used: after the customer returns to the success URL. It gives no when-not guidance or alternatives, but the usage context is explicit and unambiguous for this state transition.

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

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

Annotations declare destructiveHint=true, implying an irreversible state change, but the description never explains what confirmation does to the intent's state, whether it can be repeated, or what happens on failure. It only adds the return value (redirect URL), which is a small amount of context beyond the annotations.

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

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

A single front-loaded sentence stating the action and its result with no filler words. Nothing could be trimmed without losing meaning.

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

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

The description covers the action and the returned redirect URL, adequate for a three-param tool with a fully documented schema. But for a destructive mutation with no output schema, the absence of state requirements and idempotency/retry behavior leaves a real gap.

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

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

All three parameters are documented in the schema at 100% coverage, so the schema already carries parameter meaning. The description adds nothing about the id/client_secret/return_url semantics beyond what the schema states, matching the baseline for full 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?

States a specific verb (Confirm) and resource (Payment Intent) plus the outcome (hosted pay redirect URL), so the agent knows what the call yields. It does not, however, differentiate itself from the sibling payment_intents.complete, which an agent would plausibly confuse with confirm.

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 call this versus create, update, complete, or cancel, nor any stated prerequisite such as a specific Payment Intent status. The agent must infer the call sequence entirely from the sibling list.

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

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

Annotations establish this is a non-destructive write. The description adds genuinely useful context beyond them: it discloses what is returned (the intent, client_secret required by payment_intents.confirm, and the hosted payment link) and flags the UUID-sourcing obstacle. This is meaningful for a mutation 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?

Three sentences, zero filler, with the required-parameter choice stated first and the return-value note last. Every sentence carries information an agent needs before invoking.

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

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

For a 12-parameter write tool with no output schema, the description covers the critical path: what to supply, how the two input modes relate, and what comes back. Minor gaps remain around optional params (cancel_url, expires_at, payment_method_types, withdrawal_addresses) and error/validation behavior.

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

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

Schema description coverage is only 50%, but the description compensates by explaining the mutually exclusive parameter requirement (price_id vs amount+currency+tokenId+networkId), a constraint not encoded as a oneOf in the schema. It also clarifies that tokenId/networkId are UUIDs from an external reference rather than free-form values. Several secondary params (metadata, expires_at, payment_method_types, withdrawal_addresses) remain implied by schema only.

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?

Opens with a specific verb+resource ('Create a Payment Intent'), which clearly distinguishes it from the read/update/cancel siblings. It stops short of explicitly contrasting with related creation tools like subscriptions.create or prices.create.

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 selection rules: use price_id OR the full amount+currency+tokenId+networkId set, and 'prefer price_id when the user has a catalog price'. It also warns that no tool in the server lists the UUIDs, which steers the agent away from a dead end. It does not, however, say when a different payment tool or subscriptions.create would be the better choice.

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 and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on what is returned, error behavior for a missing ID, or any other behavioral context.

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

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

A single front-loaded sentence with zero filler; the resource and the lookup key come first. It is efficient, though its brevity reflects minimal content rather than tight editing of rich content.

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 retrieve-by-ID operation with readOnly annotations, the description is minimally sufficient. With no output schema, it could have said something about the returned Payment Intent object, leaving a modest gap.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the schema carries full burden. The description's 'by ID' merely echoes what the schema already documents, adding no syntax, format, or constraint detail.

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 (Retrieve) and resource (Payment Intent) plus the access pattern (by ID), so an agent can immediately distinguish it from create/update/confirm/cancel siblings. It stops short of explicitly naming a sibling, which keeps 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?

There is no when-to-use or when-not-to-use guidance, and no mention of alternatives among the many sibling operations. The verb implies a read, but no condition selecting this tool over, say, listing or confirming is provided.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so safety is covered; the description adds the meaningful constraint that updates are only valid pre-confirmation. However, it says nothing about what happens to unspecified fields, whether updates require specific permissions, or reversibility.

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 four-word sentence with no waste and the resource named up front. It is arguably under-specified rather than over-long, but structurally clean.

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 tool with nested objects, 8% schema coverage, and no output schema, the description is far too thin. It omits parameter semantics, field-mutation behavior, and any return/pagination expectations.

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 13 parameters and only 8% schema description coverage (only 'id' documented), the description carries a heavy burden but mentions no parameters at all. The patch semantics of updating amount, currency, price_id, etc. are entirely undocumented.

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

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

States a specific verb+resource ('Update a Payment Intent') and adds a scoping constraint ('before confirmation') that distinguishes it from sibling confirm/cancel/create tools. It is not a tautology, though it doesn't fully differentiate from the parallel subscriptions.update family.

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

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

The phrase 'before confirmation' implies the lifecycle timing for use, which is useful context, but no alternatives or exclusions are named explicitly. The agent must infer that updating is not possible after confirm.

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 and destructiveHint=false, so the write-but-not-destructive profile is covered. The description adds nothing further: no idempotency behavior, no note on what the two creation paths (product vs product_data) do, no side effects on existing products, and no response shape. Little beyond what annotations and the verb imply.

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

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

A single front-loaded sentence with no filler or redundancy. It is appropriately terse, though the terseness is achieved partly by omission rather than by careful compression of necessary detail.

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

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

For a 13-parameter creation tool with nested objects (recurring, product_data) and no output schema, the description is markedly under-specified. An agent gets no help on required-field relationships, the product vs product_data tradeoff, or what a successful creation returns.

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

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

Schema description coverage is only 23% across 13 parameters, so the schema leaves most fields (active, nickname, lookup_key, transfer_lookup_key, product_data, recurring sub-fields) undocumented. The description mentions only the one-time/recurring distinction, which partially clarifies the recurring enum but leaves the remaining twelve parameters 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?

States a specific verb (Create) and resource (catalog price) with a useful scope qualifier ('one-time or recurring') that maps to the recurring parameter. It does not explicitly differentiate itself from siblings like prices.update or prices.deactivate, but the create semantics are unmistakable.

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

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

There is no guidance on when to use this tool versus prices.update, products.create, or subscriptions.create, and no mention of prerequisites (e.g., that a product or product_data is typically needed). The parenthetical hints at a use-case branch but is not actionable 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 declare destructiveHint=true and readOnlyHint=false; the description usefully qualifies that this is a soft, reversible state change rather than a deletion and gives the exact undo call. That is genuine context beyond the annotations, though it omits permission requirements and side effects on dependent records.

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 tight sentences, zero filler, with the nature of the operation and its reversal both front-loaded. 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?

For a two-parameter mutation tool with annotations covering the safety profile and no output schema, the description supplies what matters most: what the operation actually does and how to undo it. Minor gaps (auth scope, effect on related subscriptions/prices usage) keep it short of a 5.

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

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

With 100% schema description coverage, the schema already documents price_id and organization_id (including the --organization-id fallback). The description adds no parameter-level detail, 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?

Specific verb+resource ('Deactivate a catalog price') with an immediate scope clarification ('marked inactive, not deleted') that separates it from the sibling prices.delete. An agent can distinguish it from prices.update/delete without opening any 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?

Names the reversal path ('Reverse with prices.update active: true'), which tells the agent how to undo the operation. It doesn't explicitly state when to choose deactivation over prices.delete or other sibling mutations, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the organizational scoping context and does not describe pagination, filtering behavior, or return characteristics. With annotations carrying the safety burden, this is adequate 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?

The description is a single front-loaded sentence with no wasted words. However, for a four-parameter list tool it is arguably too terse, which prevents a perfect score.

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

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

Given four parameters, 25% schema description coverage, and no output schema, the description leaves important gaps. An agent cannot tell what active, recurring, or limit do, nor what the listing returns. The definition is not complete enough for reliable invocation.

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

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

Schema description coverage is only 25%, so the description should compensate but does not. It gives no meaning for the limit, active, or recurring parameters, and the organization scoping it implies is already partly covered by the one schema-described parameter.

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 ('List') and resource ('catalog prices') scoped to an organization. It is clear enough to distinguish from write operations like prices.create/update/deactivate, but it does not explicitly name or contrast with any sibling tool.

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

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

There is no guidance on when to use this tool versus alternatives such as prices.create, prices.update, or other list tools. The description does not state prerequisites, exclusions, or supported filtering scenarios.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the mutation nature is partly covered. The description adds no behavioral context: it doesn't say whether this is a partial or full update, what happens to omitted fields, required permissions, or that additional properties are disallowed by the schema.

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

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

The description is a single front-loaded phrase with no wasted words, but its extreme brevity reflects under-specification rather than effective conciseness.

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

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

For a 13-parameter mutation with no output schema and only basic annotations, the description is far from complete. It omits parameter semantics, usage context, and behavioral details necessary for correct invocation.

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

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

Schema description coverage is only 15% (just price_id). With 13 parameters, the description provides no additional meaning about any of them—fields like recurring, currency, unit_amount_decimal, and transfer_lookup_key remain undocumented.

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

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

States the verb 'update' and resource 'catalog price', so the basic purpose is clear. However, it does not distinguish this tool from siblings like prices.create or prices.deactivate, nor does it specify what can be updated.

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, prerequisites, or alternatives are provided. The description does not help an agent decide between updating a price versus creating, deactivating, or listing prices.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the agent learns it is a non-destructive write but nothing about authentication, side effects, whether related objects are created (e.g., a default price), or what the response contains. For a mutation tool with 12 parameters, the description adds no behavioral context at all.

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 sentence is front-loaded and free of waste, but at four words it is under-specified rather than concise; nothing beyond the action is communicated. It is structurally clean but content-poor.

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 12 parameters, 8% schema coverage, a nested object, no output schema, and only minimal annotations, the description is far too thin to let an agent call this correctly. It neither explains required-field effects nor the fields whose omission changes downstream behavior.

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

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

Schema description coverage is 8% across 12 parameters, and the single nested object (marketing_features) has no explanatory text. The description contributes zero parameter meaning, leaving the agent to guess at url, default_price, shippable, unit_label, organization_id fallback behavior, and metadata semantics.

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

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

The phrase names a specific verb and resource ("Create a catalog product"), which is enough for an agent to recognize it as the product-creation action among siblings like products.update and products.delete. It stops short of differentiating itself from those siblings by scope or behavior, so it does not reach 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 indication of when to use this tool versus products.update, prices.create, or the payment-intent siblings, nor any stated prerequisites (e.g., that a default_price is needed before a price-based flow). The description offers no context beyond the bare action.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds genuinely new behavioral context: the deletion is permanent and it is blocked when dependent prices are in use. It stops short of stating whether auth/permission requirements or dependent-object cascade behavior apply, but it goes well past the annotation baseline.

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

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

Three sentences, each earning its place: the action, the precondition, and the alternative. The destructive nature is front-loaded in the first sentence.

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

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

For a two-parameter destructive tool with no output schema and full annotation coverage, the description supplies the one missing piece an agent needs — irreversibility, the blocking dependency, and the safer alternative. Nothing material is absent.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents product_id and organization_id, including the --organization-id fallback. The description adds no parameter-level syntax or format detail, 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+resource+scope: 'Permanently delete a catalog product from an organization.' The permanence qualifier and the sibling reference to products.update make it distinguishable from the other products.* tools.

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

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

Names both the failure precondition ('Fails while any of its prices is in use by subscriptions or payment links') and the explicit alternative ('use products.update with active: false instead'), including the condition that selects it. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the organizational scoping context, but says nothing about pagination, result caps, or ordering — useful traits for a list endpoint.

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. Nothing to trim and the scope qualifier is placed where it matters.

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

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

For a simple read-only list tool with annotations covering safety and a fully described single parameter, the description is adequate but leaves obvious gaps: no pagination or result-size behavior, and no indication of what a product record contains.

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

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

Schema coverage is 100% and there is a single optional parameter whose description already explains the fallback to --organization-id. The description adds no syntax or format meaning beyond that, so 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 catalog products') with the scoping qualifier 'for an organization'. It does not distinguish itself from siblings, though products.create/update/delete differ by verb enough to be separable.

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 verb — an agent can infer this is the read path for products — but there is no explicit when-to-use statement, no mention of siblings like prices.list, and no note on when an org-scoped listing is appropriate versus other product tools.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this mutates state safely, but the description adds nothing beyond that: it does not say whether this is a partial or full replacement, what permissions are needed, or how omitted fields are treated. For a 13-parameter mutation tool this is a major transparency gap.

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

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

The single sentence is short but not concise in a useful sense — it is under-specification rather than efficiency. It wastes its one line restating the tool name instead of front-loading contract details.

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

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

With 13 parameters, 15% schema coverage, no output schema, and no annotations covering mutation semantics, the description is completely inadequate. Nothing an agent needs to call this tool correctly beyond the name is present.

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 15%, and the description supplies no parameter meaning at all — no hint that name, active, metadata, unit_label, default_price, image_file_ids, etc. are updatable. The description does nothing to compensate for the near-total absence of schema documentation.

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

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

The description restates the tool name ('products.update' -> 'Update a catalog product') without distinguishing it from siblings like products.create, products.delete, or products.list. It states a verb and resource but adds no scope or differentiating detail.

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 products.create or products.delete, nor any mention of prerequisites or partial-update semantics. The agent must infer everything from the name alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read nature is covered. The description adds no behavioral context beyond the operation itself: no quote validity, expiry, source, or rate-limit information.

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

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

A single front-loaded sentence with no wasted words. It states the operation, direction, amount, and source currency compactly.

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 is simple and read-only, and the annotations plus schema cover safety and inputs. However, with no output schema, the description does not explain what the returned quote contains, such as rate, expiry, or quote identifier, leaving a meaningful gap for a quote-returning tool.

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

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

Schema description coverage is 100%, with both amount and currency documented directly in the schema. The description restates the same parameter roles (amount in a source currency) without adding format, constraint, or example details beyond the schema.

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

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

The description states a specific verb ("Get") and resource ("fiat-to-USDC quote") plus the two defining parameters. It is clearly distinct from siblings such as rates.list_currencies, but it does not explicitly name or contrast against any sibling tool.

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

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

The description says what the tool does but gives no when-to-use, when-not-to-use, or alternative-tool guidance. It does not mention rates.list_currencies or any condition that selects this tool over another.

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 and destructiveHint=false, so the safety profile is covered. The description adds no context beyond them: no note on whether the result is a static catalogue, whether it can change between calls, or what the filter does to the result set.

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

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

A single front-loaded clause with zero waste. Nothing extraneous and the purpose is stated 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?

For a trivial read-only lookup with one optional boolean and no output schema, this is close to sufficient. It would be ideal to note what the list contains (codes, symbols) or that it is a prerequisite for quoting, but nothing essential to 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 description coverage is 100% and the single optional 'active' parameter is already documented as 'Only return active currencies', so the schema carries the weight. The description adds nothing about parameter behavior, but with one fully-documented optional param the baseline is solid.

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

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

States a specific verb and resource ('List supported fiat currencies') that is unambiguous and clearly separable from the sibling rates.get_fiat_quote, which retrieves a quote rather than a catalogue. It stops short of explicitly contrasting the two, so it is clear but not sibling-differentiated to a 5.

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

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

No guidance on when to call this versus alternatives, no mention of caching, no indication of whether this is the discovery step before rates.get_fiat_quote. Usage is only inferable from the name.

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

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

Annotations already flag destructiveHint=true, but the description adds genuinely non-obvious behavior beyond them: the conditional immediate-vs-period-end outcome depending on prior state, and that cancellation_details records a churn reason. It also discloses the return 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?

Three tight sentences: default behavior first, then the alternative path, then the optional detail and return value. No filler, and the most decision-relevant fact (immediate cancellation) is front-loaded.

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

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

For a two-parameter mutation with no output schema, the description covers the outcome branch, the input semantics, the escape hatch to a sibling tool, and the return type. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is only 50% (the nested cancellation_details object has no descriptions), and the description compensates by enumerating what it records — comment and the five feedback values — which is more than the schema conveys for that branch.

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 (cancel) and resource (subscription) and immediately scopes the semantics: immediate cancellation by default, period-end only if cancel_at_period_end was already set. It distinguishes itself from the sibling subscriptions.update by 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?

Explicitly routes the agent: to schedule a period-end cancellation, use subscriptions.update with cancel_at_period_end: true (or cancel_at), instead of this tool. This is a textbook when-to-use/when-not-to-use statement naming the 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 only cover the safety profile (readOnlyHint=false, destructiveHint=false). The description adds real behavioral context the annotations cannot: the two collection_method modes and what each does per cycle, and the significant caveat that token_id/network_id come from an external reference with no lister tool in this server. It still omits auth requirements and partial-failure behavior.

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

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

Four tight sentences, front-loaded with the creation semantics and the required input shape, then the enum meaning and the return value. No filler, no restatement of the tool 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?

For a 22-parameter creation tool with 0% schema coverage and no output schema, the description covers the critical routing decision and the return type, but leaves too many optional fields (trial, billing anchor, cancel behavior, defaults) undefined for fully confident invocation.

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

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

Schema description coverage is 0% across 22 parameters, so the schema supplies only names and types. The description compensates for the most consequential gap by explaining the mutually exclusive pricing paths (a constraint not expressible in the schema as given) and the collection_method enum values, but leaves roughly a dozen scheduling/billing fields (total_cycles, days_until_due, trial_period_days, billing_cycle_anchor, cancel_at_period_end, withdrawal_addresses, metadata) undocumented.

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

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

The opening sentence states a specific verb and resource ('Create a recurring subscription'), which cleanly separates it from subscriptions.update/cancel/resume/retrieve and from payment_intents.create. An agent knows immediately what this tool produces.

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 hard input rule ('Provide either price_id ... or all of amount + currency + token_id + network_id + interval'), which is genuinely useful usage guidance, but it never says when to choose subscriptions over sibling tools like payment_intents.create, nor states any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description contributes the cursor-pagination behavior, which is useful beyond the annotations, but says nothing about default page size, cursor direction (starting_after vs ending_before), or ordering.

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

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

A single front-loaded sentence with no filler; the resource verb leads. It is arguably too terse for an 8-parameter endpoint, but there is no 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 an 8-param collection endpoint with 0% schema description coverage, nested objects, and no output schema, the definition is under-specified. An agent lacks the filter semantics, cursor mechanics, and pagination limits needed to invoke it correctly.

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

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

Schema description coverage is 0% across 8 parameters, including two enums and three nested range objects, so the schema names carry no meaning on their own. The description only gestures at 'optional filters and cursor pagination' without mapping any parameter to a filter concept, leaving the agent unable to know that e.g. created/current_period_start take gt/lt/gte/lte bounds.

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 subscriptions') and adds scope notes about optional filters and cursor pagination. It is distinguishable from subscriptions.retrieve/create/update by the 'List' verb, though it names no sibling 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, when-not-to-use, or alternative is given. The agent must infer that this is the paginated collection endpoint rather than subscriptions.retrieve, and there is no guidance on combining filters or handling empty results.

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 and destructiveHint=false, so the safety profile is covered. The description adds the useful clarification that payment links are 'cycle invoices', but says nothing about pagination behavior, result ordering, or limits, which matters given three cursor-style parameters.

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 the resource and scope front-loaded and no wasted words. Brevity is appropriate, though it is arguably too terse given the undocumented parameters.

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 4-parameter list tool with no output schema and only 25% schema coverage, the description should explain what a payment link is, how results are paged, and what is returned. None of that is present, leaving meaningful gaps.

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

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

Schema description coverage is only 25%: 'id' is documented as Subscription ID, but limit, ending_before, and starting_after carry no schema descriptions. The tool description does not compensate at all, leaving the cursor-pagination parameters undocumented for the agent.

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 (List) and resource (payment links / cycle invoices) scoped to a subscription, which is clear enough to distinguish from generic siblings like subscriptions.list or subscriptions.retrieve. It stops short of naming an alternative or explaining the relationship to those siblings, so it is clear but not fully differentiated.

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

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

There is no guidance on when to use this tool versus subscriptions.list, subscriptions.retrieve, or any other sibling, and no prerequisites or exclusions are given. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds nothing further — no idempotency, no state-transition rules, no error behavior for invalid input, no side effects such as billing resumption.

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

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

A single front-loaded sentence with zero filler, appropriate for a simple one-parameter mutation. Its brevity is efficient, though the shortness reflects under-specification rather than tight 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 trivial single-parameter mutation with annotations covering the safety profile, the description is minimally adequate. It still leaves the pause-state precondition, failure modes, and whether resuming restarts billing unaddressed.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the schema fully documents the input. The description adds no format or lookup semantics beyond what the schema already provides, which is the baseline case.

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 ('Resume') and resource ('a paused subscription'), so the agent knows exactly what action is performed. However, it does not differentiate itself from adjacent siblings like subscriptions.update or subscriptions.cancel, which could also alter subscription state.

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

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

The phrase 'a paused subscription' weakly implies a precondition, but there is no explicit when-to-use guidance, no statement about what happens if the subscription isn't paused, and no routing to alternatives such as subscriptions.update.

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 and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context of its own — nothing about what happens on a missing/invalid ID, whether the returned object is expanded, or any rate/consistency behavior. It repeats no structured data but contributes none either.

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

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

A single front-loaded sentence with zero filler. Nothing can be trimmed and the key discriminator (by ID) is stated 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?

For a one-parameter read tool with full schema coverage and annotations covering safety, the description is minimally sufficient. It omits any note about failure modes or what the returned subscription contains, but with no output schema expected this is an acceptable, if thin, definition.

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

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

Schema coverage is 100% and the single id parameter is fully documented in the schema. The description only restates 'by ID' and adds no format, prefix, or lookup-source detail beyond the schema, 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 ('Retrieve') and resource ('a subscription') scoped by ID, so an agent knows exactly what it does. It does not differentiate itself from siblings like subscriptions.list or payment_intents.retrieve, which is the only missing element for 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 statement of when to use this tool versus alternatives such as subscriptions.list when the caller lacks an ID, nor any prerequisite or error guidance. The agent must infer usage entirely from the tool name and the required id parameter.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that: it doesn't say which fields are mutable, whether changes are partial or full replacement, or what happens to unset fields during a mutation with 17 parameters.

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 single sentence is short but vacuous – it is under-specification rather than earned conciseness. Nothing is front-loaded because there is no substantive content 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 17-parameter mutation tool with nested objects, an enum, 6% schema coverage, and no output schema, the description is completely inadequate. An agent cannot infer field semantics, side effects, or response shape from 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 description coverage is only 6% (only 'id' is documented) across 17 parameters, including nested objects like pause_collection and withdrawal_addresses. The description compensates with zero parameter detail, leaving fields like price_id, token_id, collection_method, and pause_collection.behavior entirely 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 'Update a subscription' restates the tool name (subscriptions.update) verbatim with no additional specificity. It does not distinguish this tool from siblings like subscriptions.cancel, subscriptions.resume, or subscriptions.retrieve, so an agent gains nothing about what 'update' actually covers.

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

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

No indication of when to use this tool versus subscriptions.cancel, subscriptions.resume, or subscriptions.create. There is no mention of prerequisites, permissions, or side effects that would help the agent choose correctly.

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