Recharge MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description goes beyond that by stating it modifies live data, resumes future charges, uses POST /subscriptions/{id}/activate with no body, and returns { subscription }. That is meaningful side-effect and shape disclosure, though it omits permission/auth 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?

Three tight sentences, all front-loaded with the highest-value fact (reactivation and resumed charges) first. Every sentence carries distinct information with zero padding.

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

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

For a one-parameter mutation tool, the description covers the action, the side effect, the transport, and the return shape, so nothing critical is missing despite the absence of 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?

Single id parameter with 100% schema description coverage, so the schema already documents it; the description adds only the '(no body)' note. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (REACTIVATES) and resource (a cancelled subscription) plus the concrete effect (resumes future charges). The 'cancelled' qualifier effectively distinguishes it from the inverse cancel sibling without needing to name it.

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

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

The description implies the precondition (the subscription must already be cancelled) but never states when to choose this over siblings like recharge_cancel_customer_subscription or recharge_get_subscription. Usage is inferable rather than explicit.

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 give destructiveHint=true; the description adds real context beyond that by stating it modifies live data, stops future charges, that cancellation_reason is mandatory, and the exact REST call and body shape it maps to. It does not cover reversibility or what happens to in-flight shipments, keeping it out of 5 territory.

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

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

Front-loaded with the action and impact, then the operational details, all in a compact block. The caps/backtick styling and REST endpoint detail are marginally noisy but each sentence carries information.

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

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

No output schema exists, yet the description discloses the return shape ('Returns { subscription }'), covers all parameters, and the destructive annotation covers the safety profile. Missing only edge-case behavior such as irreversibility or timing of the cancellation, so it is nearly complete rather than fully so.

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 three parameters are already documented including the required flag. The description only restates that cancellation_reason is required, adding no format, allowed values, or guidance beyond the schema – the baseline 3.

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

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

States a specific verb and resource ('CANCELS an active subscription'), plus the concrete effect ('stops all future charges'), which cleanly separates it from sibling recharge_activate_subscription. The scope qualifier 'active' also tells the agent which subscriptions are eligible.

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 'active subscription' qualifier implies a precondition, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g., activate to reverse, skip_charge for deferral). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the description carries a lighter burden. It adds useful value by naming the returned fields and the underlying REST route, but says nothing about failure modes (e.g., unknown id), auth scope, or response shape. Adequate but thin given the coverage it could add.

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

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

Two sentences, zero filler, and the core purpose is front-loaded before the REST endpoint detail. Nothing redundant with the title or annotations.

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 compensates by enumerating the returned content, and one required param plus a readOnly annotation is a simple surface. Only gap is error/not-found behavior, which is minor for a single-id lookup.

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 ('Charge id.'), so the schema already does the work. The description adds only 'by id' in prose, no format, bounds, or lookup hint beyond what the schema states — the correct baseline of 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?

Specific verb + resource ('Get a single charge by id') plus an enumeration of the payload contents (line items, totals, status, scheduled date, customer/address). The word 'single' implicitly separates it from the sibling recharge_list_charges, so an agent can route 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?

Usage is implied by 'by id' — call it when you already hold a charge id — and by 'single' versus the list sibling. However, there is no explicit when-to-use/when-not statement, no mention of what to do if the id is unknown, and no named alternative. Minimum viable 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, so the safety profile is covered. The description adds value beyond that by disclosing what the response contains (contact details, Shopify customer id, subscription/charge counts) and mapping the call to REST GET /customers/{id}, though it omits auth or rate-limit 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?

Two tightly written sentences with the core action front-loaded and the REST endpoint as a trailing reference. No filler or redundancy.

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

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

For a single-resource getter with one required param and no output schema, the description usefully sketches the returned fields, which partially compensates for the missing output schema. Minor gaps remain around permissions and error behavior, but nothing essential for invocation is missing.

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

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

Schema coverage is 100% and the single 'id' parameter is documented as 'Customer id.' The description adds only the phrase 'by id', which is already conveyed by 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 and resource ('Get a single customer by id') and the word 'single' distinguishes it from the sibling recharge_list_customers without needing to inspect the schema. It also enumerates what the resource contains (contact details, Shopify customer id, counts).

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 'by id' implies this is for retrieving one known customer rather than enumerating them, which softly contrasts with recharge_list_customers. However, no explicit when-to-use, when-not-to-use, or named alternative 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 already establish readOnlyHint=true, so the safety profile is covered. The description adds real behavioral value by disclosing the payload contents (line items, totals, status, source charge/subscription) and pinning the underlying REST call, which is not derivable from annotations or the input 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?

One sentence stating scope and return contents, followed by the REST endpoint reference. Front-loaded, no padding, every clause carries information.

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

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

With no output schema, the description's enumeration of returned fields is the agent's only signal about the response shape, and it covers the essentials for a single-entity read tool. Missing only edge-case behavior (nonexistent id, error handling), which is minor here.

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

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

Schema description coverage is 100% and there is only one parameter, whose schema description ('Order id.') is complete. The description's 'by id' adds no syntax or format detail 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 and resource ('Get a single order by id') and enumerates what is returned (line items, totals, status, originating charge/subscription). The word 'single' implicitly contrasts with the sibling recharge_list_orders, though 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 implied: fetch one order when you already have its id. There is no explicit when-to-use/when-not guidance or routing to alternatives such as recharge_list_orders for browsing, so an agent must infer the choice from the name and return description.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds value beyond that by naming the concrete data returned (name, domain, currency, timezone, account settings) and mapping to the underlying endpoint (Recharge REST: GET /store), which tells the agent what it actually receives.

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 plus a short endpoint reference; every clause earns its place by naming the resource and its return contents. No filler or redundancy.

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

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

With no output schema, the description usefully enumerates the returned fields so the agent knows what comes back. For a simple singleton getter this is nearly complete, though it could note that no arguments are required or that it reflects a single account-level store.

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 there is nothing to document; the baseline for a no-arg tool is 4. The schema is trivially complete and the description correctly implies a singleton, unparameterized call.

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 (Get) and resource (store/shop info) and enumerates the returned fields (name, domain, currency, timezone, account settings). This clearly distinguishes it from the charge/customer/order/subscription siblings, which all operate on different resources.

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

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

The description implies usage context (retrieve account-level store configuration) but gives no explicit when-to-use or when-not guidance. Since this is the only store-retrieval tool among the siblings and takes no arguments, there are no alternatives to disambiguate against, so the implied usage is largely sufficient.

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 burden is lower. It adds the set of returned fields and the underlying REST mapping (GET /subscriptions/{id}), but says nothing about behavior on a missing/invalid id or any auth/rate-limit constraints.

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 zero filler; the purpose and returned fields are front-loaded, with the API mapping relegated to a trailing clause.

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, listing the returned fields is a valuable addition and covers the main completeness gap for a read-only single-entity fetch. Minor omissions remain (error behavior for unknown ids), keeping it just short of full 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?

There is one parameter with 100% schema description coverage, so the schema already documents 'Subscription id.' The description's 'by id' adds no syntax, format, or lookup semantics beyond that, making the baseline 3 correct.

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

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

States a specific verb and resource ('Get a single subscription by id') and enumerates the fields returned (product, quantity, price, charge interval, next charge date). The 'single ... by id' framing cleanly separates it from the sibling list tool recharge_list_subscriptions.

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 one subscription when you already have its id. There is no explicit when-to-use vs when-not guidance and no pointer to alternatives such as recharge_list_subscriptions for enumerating subscriptions, so the agent must infer the routing.

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

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

Annotations only supply readOnlyHint=true, so the description carries the rest: it discloses the response wrapper ({ addresses }), cursor-based pagination with default/max limits, and a non-obvious API constraint about cursors. It even cites the underlying REST endpoint, adding real behavioral context beyond the annotation.

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 purpose, then return shape, then pagination rules and the endpoint. Dense and largely waste-free, though the IMPORTANT cursor rule partially repeats the schema description of `cursor`.

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 compensates by naming the return wrapper and explaining pagination cursor fields and limits. An agent has everything needed to call and page this 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%, so the schema already documents default 50 / max 250 and the cursor-alone rule the description restates. The description adds the response field name and pagination mechanics but little parameter meaning the schema lacks – 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+resource ('List customer addresses') and enumerates the filter scope (customer, ids, created/updated date ranges). It is trivially distinguishable from siblings like recharge_get_customer or recharge_list_orders 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?

Explains how to page (pass limit, read next_cursor/previous_cursor) and gives the critical when-condition: on cursor requests only limit may accompany the cursor. No explicit when-not or alternative tool is named, but none exists among siblings, so the operational guidance is strong.

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

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

Annotations only declare readOnlyHint=true, so the description carries real weight and delivers: it discloses the response envelope ({ charges }), pagination mechanics (next_cursor / previous_cursor), default and max page size, and a non-obvious API constraint that would otherwise cause silent failures on cursor requests. That is meaningful behavioral context beyond the annotation.

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 purpose, then return shape, then the pagination constraint, then the REST endpoint for traceability. The parenthetical filter enumeration partially duplicates the schema, but everything else earns its place and the critical warning is not buried.

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 15 parameters, no required fields, and no output schema, the description supplies exactly what is missing elsewhere: the response envelope, paging loop mechanics, and the cursor exclusivity rule. An agent has enough to call this correctly and paginate safely.

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 already documents limit bounds, the cursor caveat, enum values, and every filter. The description restates the filter list and the limit default/max rather than adding format or precedence detail, so this lands at the baseline for high 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 and resource ("List charges") and immediately enumerates the filter dimensions and sorting capability, which cleanly separates it from the single-resource sibling recharge_get_charge. An agent can distinguish it from recharge_list_orders / recharge_list_customers without opening a schema.

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

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

Gives clear operational context: optional filters, cursor-based paging, and the hard constraint that cursor requests accept ONLY `limit`. It does not explicitly say when to prefer this over recharge_get_charge or sibling list tools, but for a list endpoint on a distinct resource that inference is essentially trivial.

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 behavioral value beyond that: cursor-based pagination mechanics, the { customers } response envelope, and the non-obvious API restriction that cursor requests accept only `limit`. It does not cover rate limits or ordering guarantees, keeping it below a 5.

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

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

Front-loads the purpose, then pagination, then the critical cursor constraint flagged with IMPORTANT, then the endpoint. Dense but every sentence is useful, aside from the slightly redundant restatement of filter fields already implied by the schema.

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

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

With no output schema, the description correctly supplies the return shape ({ customers }) and cursor field names an agent needs to page. For a 9-parameter read tool this is nearly complete; error behavior and sort default are the only omissions.

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 every parameter, including the cursor-alone rule and sort enum. The description restates the filterable fields and the limit default/max, which adds marginal reinforcement rather than new semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List customers') plus scope: optional filters and sorting, with the REST endpoint GET /customers named. This is clearly distinguishable from the single-resource sibling recharge_get_customer and from the other list_* tools by resource.

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 when-to-use rules for the parameters (filter by email/ids/date ranges) and a strong operational constraint: on cursor requests, only `limit` may accompany `cursor`, all other filters must be omitted. It never explicitly names an alternative sibling (e.g., use recharge_get_customer for a single customer), so it falls short of a 5.

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

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

Beyond the readOnlyHint annotation, the description discloses the response envelope ({ onetimes }), the pagination model (cursor-based with next_cursor/previous_cursor), page-size bounds (default 50, max 250), and a non-obvious API restriction that other filters are rejected on cursor requests. That last point is exactly the kind of failure-mode context annotations cannot carry.

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

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

Front-loaded with purpose, then the return shape, then the pagination contract, then the unusual constraint highlighted as IMPORTANT, closing with the REST endpoint. Every sentence carries information an agent needs; none is padding.

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

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

With no output schema, the description compensates by naming the response key, and it fully specifies pagination mechanics and the cursor-request restriction. An agent has everything required to call this correctly without further documentation.

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

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

Schema description coverage is 100%, and the description largely restates what the schema already documents (limit default/max, cursor semantics, ISO 8601 date filters). It reinforces the cursor+limit interaction but adds no new per-parameter meaning, 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 one-time (non-recurring) line items') and immediately names the filterable dimensions, which cleanly separates it from siblings like recharge_list_subscriptions, recharge_list_charges, and recharge_list_orders. The parenthetical 'non-recurring' resolves any ambiguity about what a 'one-time' is.

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

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

Gives clear operational context: when to use filters (customer, address, created/updated ranges) and, critically, the rule that cursor-based paging must be done with `limit` alone. It stops short of naming an alternative tool or stating explicit exclusions (e.g., when to prefer a search_* sibling), so it is a strong 4 rather than a 5.

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

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

Annotations only declare readOnlyHint=true, and the description adds substantial traits beyond that: cursor-based pagination, the limit default of 50 and cap of 250, the response keys to read (next_cursor/previous_cursor), and the hard constraint that cursor requests accept ONLY limit. That cross-parameter behavioral rule is exactly the kind of non-obvious detail the description should carry.

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

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

Three tight sentences, front-loaded with purpose and filters, followed by pagination mechanics and the critical cursor caveat. The REST endpoint line is short and informative rather than filler.

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

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

With 14 optional parameters and no output schema, the description compensates by summarizing the return shape ({ orders }), naming the pagination fields, and disclosing the cursor limitation. An agent has everything needed to call it correctly without opening the 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 baseline is 3; the description earns above that by grouping the filter families, restating the limit default/max, and explicitly documenting the cursor-plus-limit cross-parameter interaction. It does not add format or syntax detail beyond the schema for the date and id filters.

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 orders") plus the full scope of what can be filtered, which cleanly separates it from recharge_get_order (single order) and recharge_list_charges (different resource). The endpoint note ("Recharge REST: GET /orders") further pins the identity.

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 operational guidance on how to page correctly and warns to omit all filters when using a cursor, which is the main way to misuse this tool. It does not, however, explicitly say when to choose this over siblings like recharge_list_charges or recharge_get_order, so it stops short of a 5.

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

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 behavioral detail beyond that: the response key `{ products }`, cursor-based pagination semantics, and the non-obvious Recharge constraint that cursor requests reject all filters except `limit` — a disclosure that prevents malformed calls. Auth and rate-limit behavior remain unstated.

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 tightly packed sentences with the core purpose, return shape, pagination rule, and endpoint each front-loaded; nothing is padding. It loses a point only for echoing schema facts (limit range, cursor rule) already available structurally.

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 compensates by naming the `{ products }` return key, and it covers pagination mechanics plus the REST endpoint for a read-only list tool. An agent has everything needed to call it correctly on first attempt.

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 description mostly restates what the schema already says: `limit` default/max, cursor usage, and the id filter. The cursor-plus-limit restriction is repeated rather than extended, so this stays at the baseline of 3.

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

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

States a specific verb and resource ('List Recharge products') and immediately disambiguates the domain term by glossing it as 'subscription rules / discounts per product'. No sibling tool touches products, so the agent can place it 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?

Gives concrete operational guidance for the paging path (pass `limit`, read `next_cursor`/`previous_cursor`, and on cursor requests supply ONLY `limit`). It does not route the agent between this tool and alternatives, but the when-to-use context for each parameter mode is clear.

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

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

Annotations cover the safety profile (readOnlyHint=true), but the description adds real behavioral context beyond them: the response envelope `{ subscriptions }`, cursor-based pagination with defaults, and the non-obvious Recharge constraint that cursor requests accept only `limit`. That last detail is a genuine API quirk an agent would otherwise get wrong.

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: capability summary first, response/pagination behavior second, the critical constraint highlighted with IMPORTANT, endpoint last. No filler and the most failure-prone detail is emphasized rather than buried.

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

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

For a zero-required-parameter read-only list tool with no output schema, the description supplies everything needed: return envelope, pagination mechanics with defaults and caps, and the cursor/filter restriction. Nothing essential to a correct first call 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%, so every parameter (ids, limit, cursor, status, sort_by, date ranges) is already documented in the schema, including the cursor-exclusivity rule. The description's filter list restates that content rather than adding syntax or format detail, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource ('List subscriptions') and immediately scopes it with the available filter dimensions, so an agent can distinguish it from the singular read tools like recharge_get_subscription. The sibling family is not named explicitly, but list-vs-get is unambiguous from the wording.

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

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

It states the conditions under which filtering and sorting apply and gives a concrete when-to-use rule for pagination (pass cursor with limit only, omit filters). It stops short of explicit when-not-to-use guidance or naming sibling alternatives such as recharge_get_subscription for single-record lookups.

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

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

Annotations only declare destructiveHint=true; the description adds valuable context beyond that by stressing 'This MODIFIES live billing data' and including the underlying REST call and return shape. It stops short of disclosing reversibility (whether a skipped charge can be un-skipped) or 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?

Three dense sentences that are front-loaded with the effect and the mutation warning, followed by the API detail. No filler; every sentence carries information.

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

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

For a two-parameter mutation tool with no output schema, the description covers what it does, that it alters live billing data, and the return shape ('Returns { charge }'). Minor gaps remain on reversibility and failure/permission 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%, so both parameters are already documented, and the schema itself notes 'some stores require this' for purchase_item_ids. The description largely restates that and adds only the JSON body shape, 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 ('SKIPS a scheduled charge — prevents it from processing on its scheduled date') and clearly distinguishes itself from read-oriented siblings like recharge_get_charge and recharge_list_charges.

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?

Explains the scenario for use (preventing a scheduled charge from processing) and the condition under which purchase_item_ids is required ('Some stores require the specific line items'). It does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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