Recurpay MCP by usefulapi

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the bar is lower; the description still adds real value by spelling out the downstream effects (billing and deliveries stop) and that only the merchant can re-activate. It does not say what happens if the tool is invoked on an already-cancelled subscription, leaving the non-idempotent behavior unexplained.

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 operation and its effects, then scope disambiguation, then the confirmation instruction. Every clause carries information an agent would otherwise have to guess.

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 two-parameter mutation with no output schema, the description covers effects, reversibility, and the confirmation requirement. What the call returns and how errors (invalid or already-cancelled id) surface is unstated.

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 schema itself points subscription_id at recurpay_list_subscriptions and gives an example reason format. The description adds no parameter-level detail 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?

Specific verb+resource ('cancel one subscriber's subscription in Recurpay') plus the state transition ('status becomes cancelled; billing and deliveries stop'). It also pre-empts a plausible misread by stating this is the merchant's action on a customer subscription, not cancellation of the MCP server's own plan, which separates it from the read/list siblings.

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

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

Gives a concrete precondition ('Ask the user to confirm the subscription first') and a caution about re-activation. It never names a sibling alternative such as recurpay_skip_next_billing for a temporary pause, so the when-not path is left implicit.

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

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

The readOnlyHint annotation already establishes this as a safe read, so the description does not need to justify safety. It adds useful behavioral context by explaining that it reads scopes from the currently connected token and by naming the scope categories that will be reported.

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 with no waste. The purpose is front-loaded, followed immediately by the operational trigger for using it.

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

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

For a no-parameter, read-only diagnostic tool, the description covers what the tool returns at a category level and when to invoke it. It could optionally describe the exact response shape, but the essential context 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?

The tool has zero parameters, so there is no parameter semantics burden; baseline is 4. The description correctly implies that no arguments are needed because it operates on the connected token.

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: showing the API scopes of the connected custom app token. The parenthetical list clarifies the scope categories involved, and the resource is distinct from all sibling CRUD/list 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?

It gives an explicit trigger: use it when a tool answers 403. It does not state when not to use it or name a specific alternative, but the usage context is clear and directly actionable.

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 cover the safety behavior (readOnlyHint), while the description adds transparency about the content of the returned object by specifying that it includes the 'subscriber and line items.' This adds valuable context beyond what the metadata provides.

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

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

The definition is a single, focused sentence that is front-loaded and contains zero unnecessary fluff, making it highly concise.

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

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

Given the low complexity (1 parameter) and high-quality structural metadata (schema and annotations), the description is very complete. It successfully communicates what the agent will receive without needing to explain parameters or safety behaviors.

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?

Given that schema description coverage is 100%, the description provides no additional meaning or semantic value regarding the 'order_id' parameter beyond what is already provided in the input schema and annotations. Baseline score 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 is highly specific, using a clear verb ('Get') and defining the exact resource and its internal structure by listing included data points ('one order with its subscriber and line items'). This clearly defines the tool's scope.

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

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

The description implies the usage context (when one needs a complete order object) but provides no explicit guidance on when to prefer this tool over other subscription or subscriber retrieval tools 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?

readOnlyHint=true already covers the safety profile, so the description's contribution is payload shape: it discloses that a plan comes bundled with its selling plans including delivery policy, billing policy, anchors and discounts. That is meaningful context about what actually comes back, though it says nothing about not-found behavior or expansion options.

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

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

One sentence, front-loaded with the verb and resource, and the parenthetical enumerates return contents without padding. Nothing extraneous.

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 with full schema coverage, readOnly annotations and no output schema, the description gives enough to call it correctly and sets expectations about the nested selling-plan payload. Only minor gaps remain (error/empty 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 coverage is 100% and the single plan_id parameter is documented with its accepted integer/string forms and a provenance hint (from recurpay_list_plans). The description adds no format or constraint 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?

Specific verb+resource ("Get one plan") with a scoping qualifier ("one") that implicitly separates it from recurpay_list_plans, plus the nested selling-plan contents are enumerated. It stops short of naming the sibling explicitly, so an agent must infer the list/get split.

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: retrieving a single known plan. There is no explicit "use this when..." statement, no exclusion (e.g. "for browsing all plans use recurpay_list_plans"), and the pointer to recurpay_list_plans lives in the schema param text rather than 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?

The readOnlyHint annotation already establishes this as a safe read, so the description's added value is the disclosure of what the payload contains (contact data, addresses, total spent) — genuinely useful since there is no output schema. It stops short of noting behavior on a missing id or any auth/permission requirements.

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 returned-field list is packed into the same clause rather than a separate 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 one-parameter read-only fetch with no output schema, the description covers purpose and return content adequately. Only minor gaps remain (behavior on not-found, whether 'total spent' is scoped by currency or period).

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

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

Schema description coverage is 100% and the single parameter already documents its type, positive-integer constraint and provenance ('from recurpay_list_subscribers'). The description adds no parameter-level meaning 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 and resource ('Get one subscriber'), disambiguates the domain term with '(customer)', and enumerates the returned data. The singular 'one' implicitly separates it from recurpay_list_subscribers, but no sibling is named 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?

Usage is only implied: fetching a single subscriber by id. There is no explicit statement of when to prefer this over recurpay_list_subscribers or recurpay_update_subscriber, and no prerequisites or failure conditions are mentioned.

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, so safety is covered. The description adds real value by disclosing the returned payload composition (subscriber, addresses, line items, discount codes, policies, payment method, billing dates), which matters because there is no output schema. It says nothing about not-found behavior, permissions, or id format, which is why this sits at 3 rather than higher.

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. Slightly list-heavy, but every enumerated item (line items, discount codes, billing dates) carries information about what the caller receives.

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

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

With no output schema, the description usefully stands in for the return shape. However, it leaves out failure modes (invalid or missing subscription id) and any note on data freshness or scopes, which are meaningful gaps for a single-record fetch in a billing 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?

Schema coverage is 100% and the schema description already explains that the id comes from recurpay_list_subscriptions. The tool description adds no parameter-level meaning 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 ('Get one subscription') and enumerates the composed sub-resources returned, which distinguishes it from the list variant by name ('one'). It does not explicitly contrast with recurpay_list_subscriptions or recurpay_get_subscriber, but the singular/plural distinction is legible from the sibling names.

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: fetch a single subscription when you have an id. No explicit when-to-use or when-not-to-use statement, and no pointer to alternatives such as recurpay_list_subscriptions (to find ids) or recurpay_get_subscriber (for subscriber-centric reads).

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 readOnlyHint annotation already establishes that this is a safe read operation, so the bar is lower. The description adds that results are paginated via next_page and lists the return fields, but it doesn't disclose default page size, sort defaults, or result caps beyond what the schema says.

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 tightly written sentences with the core purpose first, followed by filters and pagination. No wasted words and everything 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?

With 100% schema coverage and a readOnly annotation, the description supplies what the structured fields don't: the shape of returned records and the paging mechanism. Only minor gaps remain, such as sort defaults and the relationship to related order tools.

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 all 11 parameters including defaults, patterns, and enums. The description only echoes the filter categories and the next_page paging convention, adding no syntax or behavioral detail beyond the schema; baseline 3 applies.

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

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

The description opens with a specific verb and resource ('List the orders generated by subscriptions') and enumerates the returned fields (name, subscriber, status, totals), which clearly separates it from the singular recurpay_get_order. It is clear without explicitly naming the sibling, so it lands 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?

The filter list ('by order name, subscriber email, subscription and dates') implies usage contexts, but the description never says when to prefer this over recurpay_get_order or how results relate to recurpay_list_order_subscriptions. Guidance 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?

Annotations already declare readOnlyHint=true and the title restates the operation, so the safety profile is covered. The description adds that results are scoped to a single order, but says nothing about whether an empty list is returned for an order with no subscriptions or about pagination behavior (though the schema documents page/limit/next_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?

A single front-loaded sentence with zero filler. It is arguably too terse for a 9-parameter filtered-list tool, but as a matter of conciseness and structure it is well-formed.

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?

Adequate minimum for a read-only list tool whose schema fully documents all nine parameters. However it leaves the sibling relationship to recurpay_list_subscriptions unstated and gives no hint about the shape or typical contents of the returned subscription list, which has no output schema.

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

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

Schema description coverage is 100%, including the order_id provenance note ('from recurpay_list_orders') and all filter/sort/pagination params, so the schema carries the full parameter burden. The description adds only the implicit confirmation that order_id is the scoping key — baseline 3.

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

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

States a specific verb (list) and resource (subscriptions) plus a clear scope: subscriptions belonging to one order. This implicitly distinguishes it from recurpay_list_subscriptions, but the description never names or contrasts that sibling, so an agent must infer the difference.

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

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

Usage is only implied by the word 'order' — an agent can infer you call this when you have an order_id and want its subscriptions. There is no explicit when-to-use, when-not-to-use, or pointer to recurpay_list_subscriptions for tenant-wide listings.

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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description gestures at result composition ('variants excluded') but does so ambiguously and says nothing about pagination defaults, ordering, or what an empty result means.

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. It is arguably too terse rather than too long — the ambiguous second clause would have been better replaced with two precise ones.

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?

Three parameters with full schema coverage and no output schema, so the essentials for invocation are present. However, with no output schema the description should describe the shape of the returned product entries and clarify the 'variants excluded' semantics, which it does not.

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%: page, limit, and plan_id all carry their own inline documentation including the pointer to recurpay_list_plans for plan_id. The description adds no semantics beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (list) and resource (products attached to one plan), which clearly separates it from get_plan and list_plans in the sibling set. The trailing clause 'with the variants excluded from it' is ambiguous enough that a reader cannot tell whether variants are omitted from the result or listed separately as exclusions.

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 statement of when to call this versus recurpay_get_plan (which presumably also carries product info) or recurpay_list_plans. The only implicit signal is the plan_id requirement, leaving the agent to infer the use case 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, so the safe-read profile is covered. The description adds the useful detail that results include policies and discounts, and hints at a next_page continuation token that is otherwise only mentioned in the page parameter's schema text. It does not disclose pagination envelope shape, total counts, or limits.

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 returned contents, followed by filtering and pagination. Nothing is wasted, though the pagination clause is terse to the point of ambiguity.

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?

Eleven all-optional parameters are fully documented in the schema, and the description summarizes the result contents. Missing: no output schema, and the description's 'next_page' reference is not reconciled with the numeric 'page' parameter, leaving the continuation workflow slightly unclear.

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 every filter, sort, and pagination parameter is documented in the schema, so baseline is 3. The description only restates the filter categories already documented and adds no format or behavior details beyond them.

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 (list subscription plans, clarified as selling plan groups) and names the payload contents (delivery/billing policies and discounts). It distinguishes itself from recurpay_get_plan by being a listing operation, though it does not explicitly contrast with the similarly named recurpay_list_plan_products.

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

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

Filter and pagination usage are implied by 'Filter by plan title, product title/handle and dates' and 'Page with next_page.' There is no explicit guidance on when to choose this over recurpay_get_plan or recurpay_list_plan_products, so usage must be inferred from the sibling names.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds value by naming the returned fields (name, email, phone, addresses, total spent) and disclosing that pagination continues via next_page. It does not mention rate limits or permissions, but for a read-only list tool that is a minor 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?

Three short sentences, front-loaded with the resource definition and return fields, with no filler. Minor imprecision in "dates" (which of the four date parameters) is the only rough edge, not verbosity.

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

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

For an 11-parameter, non-destructive read tool with full schema coverage and no output schema, the description covers purpose, population, returned fields and pagination adequately. The remaining gap is guidance on choosing among the many sibling list/get tools rather than factual coverage.

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

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

Schema description coverage is 100%, so all 11 parameters are documented in structured form and the baseline is 3. The description adds only a coarse summary — "filter by name, email and dates" — and omits any mention of sort_by, sort_key, limit, or the fact that four distinct date ranges (created/updated min/max) exist, so it does not meaningfully enrich the schema.

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

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

States a specific verb and resource ("List the store's subscribers") and even defines the population — customers with at least one subscription — which an agent can use to distinguish this from a generic customer list. It does not, however, contrast itself with siblings like recurpay_list_subscriptions or recurpay_get_subscriber, so the differentiation is implicit 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?

"Filter by name, email and dates. Page with next_page" gives implied usage of the filter and pagination mechanics, and the parenthetical scope definition hints at what is excluded. There is no explicit statement about when to prefer this over recurpay_list_subscriptions or when to switch to recurpay_get_subscriber for a single record.

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 readOnlyHint=true already declaring the safe-read profile, the description still contributes useful behavior: the returned field set, the meaning of the halted status, and that paging is driven by next_page from the prior reply. No rate limits or ordering guarantees are given, 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?

Three tight sentences: what it returns, how to filter, the halted tip, pagination. Zero filler and the resource scope 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?

Eleven optional parameters with no output schema, so describing the returned fields and pagination behavior carries real weight and is done well. Minor gap: sort_by/sort_key and the created_at/updated_at bounds are only in the schema, though coverage there is complete.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond by explaining the operational intent of status=halted and by tying pagination to next_page, rather than merely restating parameter names.

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 the store's subscriptions") and enumerates the payload contents (status values, subscriber, plan policies, line items, next_billing_at). An agent can distinguish it from recurpay_get_subscription (single) and recurpay_list_order_subscriptions (order-scoped) 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?

"Use status=halted to find subscriptions whose renewal payment failed" gives a concrete diagnostic recipe, and the filter sentence names the primary narrowing axes. It stops short of naming alternatives or when-not-to-use guidance, so it stays 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main addition is the required read-webhooks auth scope, which annotations do not cover. It does not describe pagination behavior or ordering, so the added behavioral context 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?

A single sentence with the resource front-loaded and zero wasted words. The scope requirement is appended compactly without burying the main purpose.

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 full schema coverage and readOnlyHint, the description covers purpose, returned fields, and auth requirement. Only a note on pagination/result ordering would make it fully self-contained.

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 all four parameters (page, limit, created_at_min/max) are fully documented in the schema, including the next_page hint. The description adds nothing about parameters, which is acceptable given 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?

States a specific verb and resource ('List the webhook subscriptions of the store') and even names the fields returned (topic, address, status). No sibling tool is webhook-related, so differentiation is implicit rather than stated, 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?

The description says the read-webhooks scope is required, which is a real usage precondition, but it gives no guidance on when to call this versus other listing tools or on pagination workflow. Usage is implied by the tool's name rather than spelled out.

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

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

Annotations already flag destructive=true, idempotentHint=false, openWorldHint=true, but the description goes further by naming the real-world effect: an immediate billing cycle that can charge the saved payment method and create an order. It also discloses the repeat-call hazard ("repeated calls may repeat the charge or notification"), which is the practical consequence of non-idempotency.

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 risk banner before the mechanics. Every clause earns its place: action, effect, use case, consent gate, and repeat-call warning.

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, non-idempotent mutation with no output schema, the description covers action, side effects, consent requirement, and duplicate-call risk. Nothing an agent needs to decide or invoke correctly is missing.

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

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

Schema coverage is 100% and both parameters carry their own descriptions, including the consent semantics of confirm. The description reinforces confirm=true but adds no syntax or format detail beyond what the schema already states, 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 ("renew the subscription now") and immediately frames the scope with "WRITE, MAY CHARGE THE CUSTOMER." This clearly separates it from read siblings (get_subscription, list_subscriptions) and from adjacent mutations like skip_next_billing or cancel_customer_subscription.

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 positive use case ("retry a halted subscription"), an explicit gate ("only call it when the user explicitly asks"), and a required precondition (confirm=true). An agent knows both when to call it and what consent must exist first.

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

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

The description goes well beyond the annotations by disclosing that the customer is contacted and notified, that the call creates a payment link, and that repeated calls may repeat a charge or notification. These are exactly the side effects an agent needs to know for a destructive, non-idempotent, open-world write action.

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

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

The key warning is front-loaded as WRITE, CONTACTS THE CUSTOMER, and the rest packs usage and risk information efficiently. It is a single semicolon-heavy sentence, but nearly every clause carries necessary operational 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?

For a destructive, non-idempotent, open-world write tool with no output schema, the description covers the important prerequisites, side effects, and repeat-call risk. It makes clear that Recurpay itself notifies the subscriber, so the lack of a separate recipient parameter is not a 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%, so the schema already documents subscription_id and confirm, including the fact that confirm must be true only after explicit approval. The description reinforces the confirmation requirement but adds no extra parameter syntax or meaning beyond the schema.

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

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

The description states a specific verb and resource: generate a payment link for a Recurpay subscription, both for renewal payment and payment-method update. It also scopes usage to halted subscriptions. It does not explicitly name sibling tools as alternatives, so sibling differentiation is implied 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?

It clearly says to use this for halted subscriptions and only when the user explicitly asks, and it requires confirm=true. The guidance is strong, though it does not explicitly name which sibling tool to use instead for other renewal or update cases.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the bar is lower; the description still adds value by naming the concrete consequence (the next order is not generated) and the human-confirmation requirement. It does not address reversibility (whether a skip can be undone) or whether the subscription must be active.

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

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

Two short sentences, with the 'WRITE:' marker front-loaded so the agent immediately knows the operation class, followed by the effect and the confirmation rule. No filler.

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

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

For a single-parameter mutation whose safety profile is carried by annotations, the description covers what happens, what is affected, and the confirmation gate. Gaps remain around reversibility and error/edge behavior (already-skipped subscriptions), but nothing critical to a 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?

Only one parameter with 100% schema coverage, and the schema already documents it including a pointer to recurpay_list_subscriptions. The description adds no syntax, format, or sourcing detail beyond what the schema provides, 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 ('skip the subscription's next billing/delivery cycle') and disambiguates the effect by explaining that the next order is not generated. This is clearly distinct from sibling mutations such as recurpay_renew_subscription or recurpay_cancel_customer_subscription.

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?

Provides a prerequisite ('Ask the user to confirm the subscription first') but no when-to-use versus alternatives guidance — it never says how this differs from cancelling or renewing, or what to do if the subscription is already skipped. Usage is implied rather than routed.

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

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

The description adds crucial behavioral details beyond the annotations and schema: 'Only the fields you pass are sent,' which is essential for partial updates (PATCH behavior). It also includes a workflow hint: 'Ask the user to confirm the new values.' This is valuable process context.

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

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

The description is front-loaded and very concise. It uses a clear structure (WRITE tag, main purpose, scope constraint, workflow advice) to provide maximum value in minimum space.

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

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

The description provides a complete picture of the operation, including its partial update nature and the recommended user interaction flow, even without an output schema.

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

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

Schema coverage is 100%, so the description doesn't need to redefine parameters. However, the description adds semantic meaning by specifying the required ID format: 'Only the fields you pass are sent,' implying optionality for the other fields.

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?

Uses the explicit command 'WRITE' to define its function. It clearly states the target resource ('subscriber's contact data') and the specific actions being performed (changing email, name, phone).

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

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

The description implies when to use it—only for updating contact data, suggesting other tools like `recurpay_get_subscriber` would be used first to find the ID. However, it doesn't explicitly state 'do not use for' or compare it to siblings like a general 'update_subscriber' call.

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 this as a destructive, non-idempotent, open-world write. The description goes beyond them by disclosing the downstream effect ('changes what the subscriber pays on the next billings') and imposing an explicit user-confirmation step, which an agent would not infer from the hints alone. It stops short of saying whether removal is reversible or how proration is handled.

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 front-loaded sentence carrying the verb, resource, and blast radius, followed by a short imperative precondition. No filler, no repetition of schema fields.

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

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

For a 3-required-param mutation with full schema coverage and a complete annotation set, the description covers what it must add: it is a write, it affects future billing, and confirmation is required. Only minor gaps remain (behavior when removing a code that is not applied, whether a response body is returned).

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%: the 'action' enum, the 'code' example (TEST20) and the 'subscription_id' provenance (from recurpay_list_subscriptions) are all documented in the schema. The description only restates the general subject matter and adds no syntax, format or edge-case meaning beyond it.

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 pair ('add or remove') plus a concrete resource ('a discount code (coupon) on one subscription') and the effect on future billings. The 'WRITE:' prefix immediately separates it from the read-oriented siblings like recurpay_get_subscription or recurpay_list_subscriptions, and no sibling covers coupons at all.

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

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

The description scopes usage to a single subscription and adds a precondition ('Ask the user to confirm'), which is useful operating guidance. However it never states when to choose add vs remove in context, nor does it mention any exclusion or alternative tool for coupon-related workflows.

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