Seal Subscriptions MCP by usefulapi

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

Annotations already declare destructiveHint, non-idempotent and open-world, so the safety profile is covered; the description adds genuine value beyond that by explaining the billing consequence (next charge amount changes) and the one_time lifecycle (item removed after the next renewal). It does not mention auth scope or whether added items can be reverted, which would have been the fifth point.

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 WRITE marker, then the billing consequence, then the one_time caveat, then the endpoint. No filler and no repetition of the title.

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 write with a fairly demanding nested items payload and a close sibling (edit_items), the description covers the effect and endpoint but omits item-count limits, per-item required fields, and the add-vs-edit distinction. There is no output schema to worry about, but an agent could still construct a failing call from this description alone.

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

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

With only 50% schema coverage, the description partially compensates by explaining that `price` is in the subscription currency and what `one_time` does. However, `items` is a required nested array of up to 50 objects with five required subfields (product_id, variant_id, quantity, title, price), and the description says nothing about that structure or the array limits, leaving the most error-prone parameter underspecified.

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?

"Add products to a subscription" gives a specific verb and resource, and the WRITE: prefix signals the operation class immediately. It is distinguishable from remove_items, but it never explicitly contrasts with the very similar sealsubscriptions_edit_items sibling, leaving an agent to infer the boundary.

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 use case (adding line items that change the next charge) but never states when to choose this over edit_items or remove_items, nor any preconditions such as the subscription needing to be active. Usage is inferable but not guided.

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 WRITE semantics (readOnlyHint=false), openWorldHint, idempotentHint and destructiveHint, so the 'WRITE:' prefix is largely redundant. The description does add genuine behavior: the operation is additive and preserves existing links. It does not explain why an append would be flagged destructive, nor what happens on duplicates or the 500-item cap.

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 lean sentence with the operation type front-loaded, zero padding. The trailing HTTP endpoint is mildly redundant with the tool name and schema but not harmful.

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

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

With only two required params, 100% schema coverage and rich annotations, the description covers the essentials. Remaining gaps are duplicate-handling and the 1-500 array bound, which the schema partially covers via minItems/maxItems.

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

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

Schema description coverage is 100%, with rule_id, product_id and variant_id each documented in-schema (including 'null for all variants'). The description adds no meaning beyond restating 'products or variants', 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 ('Add products or variants to a subscription rule') and adds scope: appending without touching already-linked items. That implicitly separates it from replace-style edits, though it never names the sibling (e.g. sealsubscriptions_edit_subscription_rule) it contrasts with.

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

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

The phrase 'without touching the ones already linked' implies when to choose this over a full edit, but no alternative is named and no preconditions (rule must exist, products must belong to the shop) are given. Usage must be inferred.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true; the description reinforces 'WRITE' and adds useful effect information ('lowers what the customer pays on the next charges'). However, it never explains the destructiveHint — e.g. whether applying a code replaces an existing discount code — nor how to undo it, which is the main behavioral unknown for an agent.

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 compact sentences with the operation type ('WRITE:') and the key scope constraint front-loaded. The trailing 'PUT /subscription-discount-code action=apply' is mildly redundant implementation detail but costs little.

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

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

For a 2-parameter write tool with full schema coverage and rich annotations, the description covers purpose, scope, and customer-facing effect. The remaining gap is behavior under conflict (existing discount code) given destructiveHint=true, which would be worth one more sentence.

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

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

Schema description coverage is 100%, so both parameters (discount_code, subscription_id, including the id-vs-internal_id distinction) are already fully documented in the schema. The description adds no syntax, format, or validation 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?

States a specific verb+resource ('Apply a Shopify discount code to an auto-charging subscription') and scopes it with an explicit exclusion ('not to recurring-invoice subscriptions'). It doesn't explicitly contrast with the sibling sealsubscriptions_remove_discount_code, though the apply/remove pairing is clear from the 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?

Gives a clear applicability condition (auto-charging subscriptions) and a clear non-applicability condition (recurring-invoice subscriptions). It does not name the counterpart remove_discount_code tool for the reverse operation, so the alternative-selection guidance is incomplete rather than absent.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is known. The description adds real value beyond that: what actually stops (future charges and shipments), the customer-facing side effect (Seal's cancellation email), and that the action is reversible. It does not address permissions, active-state prerequisites, or effect on pending billing attempts, so it falls short of 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?

Four short clauses, front-loaded with the WRITE marker and the core effect, then alternatives, then endpoint. Every sentence carries information an agent needs; 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 one-parameter mutation with rich annotations and no output schema, the description covers effects, side effects, and alternatives well. Minor gap: no indication of what is returned or how the cancellation interacts with in-flight billing attempts, though neither is essential to invoke it correctly.

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

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

The single parameter is fully documented in the schema (100% coverage), including the useful distinction between `id` and `internal_id`, so the schema does the heavy lifting. The description adds no parameter-level guidance, which is the expected baseline-3 outcome at full coverage.

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

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

States a specific verb+resource ("Cancel a subscription") and immediately scopes it with "now", which distinguishes it from the sibling sealsubscriptions_schedule_cancellation. The "WRITE:" prefix and endpoint (PUT /subscription action=cancel) make the operation unambiguous.

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

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

Explicitly routes to alternatives: "It can be brought back with sealsubscriptions_reactivate_subscription" and "For a later cancellation use sealsubscriptions_schedule_cancellation." Both the undo path and the timing-based alternative are named, leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description complements them rather than repeating them: the money movement is immediate, an order is created, the schedule is otherwise untouched, and reset_schedule rebuilds subsequent attempts from today. Remaining gaps are failure/retry behavior when the charge is declined and whether this is the same path as process_charge.

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 consequence and the WRITE marker are front-loaded, and each following sentence adds a distinct fact (immediacy, call guard, reset_schedule effect). The all-caps emphasis and the trailing 'PUT /subscription-create-charge-now' are mildly noisy but do not bury the key 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, no-output-schema mutation tool, the description covers trigger condition, immediate effect, side effect (order creation), and the schedule consequence. An agent has enough to decide to call it and to set reset_schedule correctly; return-value detail is not required here.

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

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

Schema coverage is 100%, so a 3 is the baseline; the description earns a bump by making reset_schedule's effect concrete ('later attempts are rebuilt from today') rather than the schema's vaguer 'rebuild the rest of the schedule'. subscription_id is left entirely to the schema, which is fine given its 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?

Specific verb and effect: immediately charges the customer's payment method for the next billing attempt and creates a Shopify order. It also states the negative scope ('does not wait for the scheduled date'), which separates it from scheduled-billing behavior. What keeps it from a 5 is that it never names the closest sibling (sealsubscriptions_process_charge) that an agent would otherwise confuse it with.

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

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

'Only call it when the user clearly asked for an immediate charge' is an explicit and unusually strong gate on a destructive tool. It also explains how reset_schedule changes the outcome. There is no guidance on what to do instead when the user did not ask for an immediate charge (e.g., reschedule_billing_attempt, skip_billing_attempt).

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior: the 65-day scheduling horizon and that deletion is effectively temporary because the attempt gets regenerated. It stops short of saying what happens if the attempt was already processed (error type).

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 packed sentences, with the WRITE marker and the core action front-loaded before the durability caveat and the sibling pointer. No sentence is 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 a rich annotation set and no output schema, the description covers action, precondition, side effect and alternative. Minor remaining gap is failure behavior for an already-processed 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 coverage is 100% and both parameters carry precise descriptions, including that subscription_id is the `id` and not `internal_id` and where billing_attempt_id comes from. The description adds no parameter-level detail, 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 ('Delete a billing attempt') plus a scope precondition ('that has not been processed') and even names the endpoint. It is clearly distinct from reschedule_billing_attempt, which it references, though the difference from skip_billing_attempt is left implicit.

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

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

Gives an explicit when-not path: deleting is not durable because Seal recreates the attempt within hours, so the schedule must be moved first via sealsubscriptions_reschedule_billing_attempt. The agent is routed to the correct alternative with the condition that selects it.

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

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

Annotations already declare destructive and idempotent, but the description adds genuinely new behavioral context: it explains the business consequence ('Changes what the customer pays on the next charge') and pins the transport (PUT /subscription action=edit_items). It stops short of stating whether omitted fields are preserved or reset.

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 WRITE marker, then effect and fields in a single dense sentence, with the endpoint trailing. Telegraphic ('one-time flag' vs the schema's `one_time`) but nothing wasteful.

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

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

For a mutation tool with no output schema, the description covers what changes, the immediate cost impact, and the endpoint. Partial-update semantics (merge vs replace of items[]) remain unstated, which is the main residual gap for an agent calling it 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?

The description restates the editable fields (variant, quantity, price, SKU, one-time flag, properties) and the bounds already present in the schema (> 0, >= 0). With 50% schema description coverage it adds little beyond the schema, and it omits the required item `id`, which is the one parameter an agent most needs to source correctly.

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

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

States a specific verb and resource: 'Change existing items of a subscription', and enumerates the fields that can change. The word 'existing' implicitly separates it from add_items/remove_items, though it never names those siblings outright.

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 'WRITE' marker and 'Change existing items' imply when to use it versus adding or removing items, but there is no explicit when-to-use statement, no prerequisite (e.g. fetch the item id first via get_subscription), and no mention of the sibling edit_subscription tool that also mutates a subscription.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds genuinely useful context the annotations do not carry: the prepaid billing-interval behavior and the fact that an empty note_attributes list erases existing attributes. It does not address permissions, validation failure modes, or what happens to items when intervals change (other than the automatically_update_product_prices parameter's own schema text).

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 'WRITE:' marker and a single dense sentence that scopes the resource, followed by two short qualifier sentences. Nearly every clause carries information, though the parenthetical prepaid explanation slightly duplicates the billing_interval schema description.

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

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

For a 23-parameter mutation with no output schema and low schema coverage, the definition gives an agent enough to pick the right fields and understand partial-update and deletion semantics. Missing details are secondary: response shape, behavior on invalid interval strings, and whether address changes affect future versus already-scheduled orders.

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

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

With 23 parameters and only 30% schema description coverage, the description has to compensate, and it does by grouping the parameters into named domains (intervals, min/max payments, note attributes, delivery method and price, shipping address) and flagging the empty-list deletion semantics. The remaining gap is that the individual address fields, delivery_method_* variants, and interval string formatting are left to the schema.

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

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

States a specific verb and resource ('Edit a subscription's schedule and details') and enumerates the editable field groups: intervals, payment cycles, note attributes, delivery method/price, and shipping address. It also explicitly excludes item changes by pointing to the item tools, which separates it from sealsubscriptions_edit_items and add_items.

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?

'Only the fields you pass change' establishes partial-update semantics clearly, and 'To change items use the item tools' routes the most likely confusion to a sibling. It stops short of naming which sibling to use for adjacent operations like pausing, rescheduling, or cancellation scheduling, so the exclusions are not complete.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true, but the description adds the crucial detail that product_variants is a full replacement of all linked products and variants — the exact destructive behavior an agent must know before calling. It does not address whether omitted top-level fields are cleared by the PUT or what permissions are required.

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

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

Three sentences, mutation flag front-loaded, the destructive replacement caveat immediately followed by the safer sibling alternative. No filler and nothing 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 destructive edit with no output schema, the description covers the main hazard (list replacement) and the alternative path. Remaining gaps — partial-vs-full update semantics for omitted fields and the response shape — are secondary but non-trivial for a PUT.

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

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

With 75% schema coverage the bar is modest, but the description still adds value: it explains product_variants as a complete replacement set, gives an example of the options label ("Deliver every"), and names the endpoint semantics (PUT). rule_id and name are left to the schema.

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

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

"WRITE: Edit a subscription rule" gives a specific verb, mutation direction, and resource, then enumerates exactly which fields are editable (name, options label, product list). An agent can separate this from read siblings like get_subscription_rule or list_subscription_rules without inspecting the schema.

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

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

It explicitly routes the agent away from this tool for additive changes: "to add some without removing the others use sealsubscriptions_append_rule_product_variants." That is a concrete when-not plus named alternative, but no guidance is given on when to edit a rule at all versus creating or deleting one.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds value beyond them by disclosing the breadth of returned data (billing attempts with status and error messages, activity log) and a data-hygiene rule: 'Private customer links are removed.' It stops short of stating not-found/error behavior.

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

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

A single dense sentence front-loads the resource and then enumerates payload contents, with no filler. The trailing 'GET /subscription?id=.' fragment is slightly awkward and redundant given the schema, but costs little.

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

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

With no output schema, the description carries the return-value burden and does so well by enumerating nearly every returned section and noting that private customer links are stripped. Missing only error/not-found semantics, which is a minor gap for a single-record getter.

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 parameter already documents the crucial distinction between `id` and `internal_id`. The description's 'GET /subscription?id=' only echoes the schema, adding no new semantic detail. Baseline 3 applies when the schema carries the parameter burden.

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 ('One subscription with everything Seal knows') and enumerates the exact payload contents (addresses, items, billing attempts, fulfillment orders, invoices, tags, activity log). The singular 'One subscription' implicitly separates it from sealsubscriptions_list_subscriptions, 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 only implied: the framing of 'one subscription' with full detail suggests a single-record lookup versus the list tools, and the trailing 'GET /subscription?id=' hints at the access pattern. There is no explicit when-to-use statement, no prerequisites, and no named alternative such as list_subscriptions for bulk retrieval.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds meaningful response context beyond annotations by saying the rule comes with its products, variants, and selling plans, which matters because no output schema exists.

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 compact sentences, front-loaded with the resource and scope, with no filler. The included-data detail is useful and efficiently stated.

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

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

For a simple one-parameter read tool with annotations and no output schema, the description is complete enough: it says what is fetched and what related objects are included. It could mention missing-id/not-found behavior, but that is a minor gap.

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

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

Schema description coverage is 100%, and the schema already explains that rule_id is a positive integer from sealsubscriptions_list_subscription_rules. The description adds only the endpoint shape 'GET /subscription-rule?id=', not further parameter semantics; 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: retrieve one subscription rule by id, and enumerates included related data (products, variants, selling plans). This clearly distinguishes it from the sibling list_subscription_rules, though it does not explicitly name that sibling.

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' and the schema note pointing to sealsubscriptions_list_subscription_rules as the source of ids. There is no explicit when-to-use/when-not guidance or direct comparison to alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine value by naming the fields returned (name, payment type, products/variants, selling plans), though it says nothing about pagination behavior or result volume.

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 compact sentence with the payload description front-loaded; the trailing 'GET /subscription-rules' is mildly redundant but cheap and orienting. No wasted clauses.

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

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

For a simple read-only list tool with no output schema, enumerating the response fields is the key missing piece and it is supplied. The remaining gap is the absence of any routing hint toward get_subscription_rule versus this list call.

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

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

Schema coverage is 100% and the single 'page' parameter is fully documented in the schema, including the 50-per-page limit and the next_page chaining hint. The description adds no parameter meaning beyond that, so baseline 3 applies.

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

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

States a specific verb+resource ('List the subscription rules (plans) of the shop') and even enumerates the returned fields, so the agent knows exactly what comes back. It does not differentiate from the sibling sealsubscriptions_get_subscription_rule, leaving the list-vs-single ambiguity to inference.

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 use this versus get_subscription_rule, or of prerequisites (shop/auth context). The read is implied but there is no explicit usage framing.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds pagination behavior (50 per page) and notes that items and billing attempts can be included, which affects response size, but says nothing about auth requirements, rate limits, or ordering of results.

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

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

One dense but well-ordered sentence: purpose first, returned fields second, then search, filter and expansion options, with the endpoint last. Every clause carries information; the field enumeration is slightly long but justified since no output schema exists.

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 valuable and the description does it. For a read-only, zero-required-parameter list tool this is nearly complete; only result ordering and pagination navigation beyond the schema's own note are unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including defaults and the next_page hint. The description mirrors the searchable fields and filters but adds no extra syntax or format detail beyond the schema, 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?

Clear verb (list/search) plus resource (shop's subscriptions) and it enumerates the fields returned, so an agent knows exactly what comes back. It does not name the near-twin sibling sealsubscriptions_list_subscriptions_by_billing_date, which is the main confusion risk among 25 siblings, so it falls short of the top score.

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 explains how to use the tool (search by email/first/last name, filter by status, opt into items and billing attempts), which implies the intended use cases. But there is no explicit when-not guidance or pointer to alternatives such as get_subscription for a single record or list_subscriptions_by_billing_date for date-ordered listing.

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 read-only, non-destructive, open-world behavior, so the description does not need to repeat safety details. It adds useful context about billing-date filtering and pagination via cursor, though it does not discuss permissions or response shape.

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

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

The description is compact and front-loaded: it states the filtered resource first, then explains pagination, then gives the endpoint. Every sentence adds value without unnecessary repetition.

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

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

For a read-only list tool with full parameter documentation and annotations, the description covers the key behavior: billing-date filtering and cursor pagination. It does not describe response fields, but no output schema is provided and the core invocation needs are satisfied.

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 all three parameters are already documented in detail. The description reinforces the date-range semantics and cursor workflow, but adds little beyond what the schema already explains about formats and pagination.

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

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

The description clearly defines the resource and filter: subscriptions with at least one billing attempt scheduled between two UTC date-times. It distinguishes this from a generic subscription list by focusing on billing dates, though it does not explicitly name the sibling `list_subscriptions` as an alternative.

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

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

It states a concrete use case: seeing what will be charged tomorrow or this week. That gives clear context for when to use the tool, but it does not specify when not to use it or name an alternative for listing all subscriptions.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds shop scoping and the HTTP endpoint but says nothing about result limits, ordering, or what an empty response means — modest added value beyond structured fields.

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

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

A single sentence with the resource and scope front-loaded, plus returned fields and endpoint appended compactly. 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 zero-param, read-only, non-destructive listing tool with no output schema, the description covers what it returns (topic, address), what it is scoped to (this shop), and the endpoint. Nothing an agent needs in order to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is high. Calling convention is fully determined by the schema.

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

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

States a specific verb and resource ('List the webhooks registered for this shop') and even enumerates the returned fields (topic and address), plus the underlying endpoint GET /webhooks. Sibling tools are all subscription operations with no other webhook tool, so no sibling differentiation is required here.

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

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

Usage is implied by the resource name — an agent would call this to inspect webhook registrations — but there is no explicit statement of when to prefer it, what prerequisite state exists (e.g. no webhooks configured returns empty), or any caveat. For a zero-parameter read tool this is workable but not instructive.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's job is to explain consequences — which it does by spelling out that charges and shipments stop until resume. It does not explain why the operation is flagged destructive (e.g., any state or schedule effects that are not restored by resume), which is the one thing an agent would want before pausing a live subscription.

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 compact line with the operation type front-loaded, then effect, then the undo route, then the endpoint. No sentence is redundant.

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

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

For a one-parameter mutation with no output schema, the description covers effect, reversibility, and endpoint, which is sufficient to invoke it correctly. The remaining gap is intra-family routing versus cancel/reactivate siblings.

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

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

There is a single parameter with 100% schema description coverage, and the schema already warns to use `id` rather than `internal_id`. The description adds nothing beyond that, which is the expected baseline when the schema does the work.

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

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

States a specific verb (Pause) and resource (an active subscription), and immediately quantifies the effect: "no further charges or shipments until it is resumed." The WRITE prefix and the endpoint hint make it unmistakable versus the read siblings like get_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?

Specifies the precondition (an active subscription) and points to the inverse operation, sealsubscriptions_resume_subscription, as the undo path. It does not, however, distinguish pausing from neighboring lifecycle tools such as cancel_customer_subscription, schedule_cancellation, or reactivate_subscription, so an agent facing a "stop billing" request still has to infer the right choice.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description adds the material fact that real money is captured immediately and that a Shopify order is created as a side effect — behaviorally richer than the annotation flags. It stops short of describing failure handling (e.g., what happens if the charge is declined) or whether retries are safe.

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 "WRITE: CHARGES ... NOW" so the riskiest fact appears first, then the guard condition, then the endpoint. No filler sentences.

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

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

For a destructive money-moving tool with full schema coverage and no output schema, the description covers intent gating and side effects adequately. Minor gaps remain around post-call semantics (what the resulting order/charge looks like, decline handling) but nothing an agent needs before invoking it.

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

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

Schema coverage is 100%; both subscription_id and billing_attempt_id are documented in-schema, including the pointer to billing_attempts[].id from sealsubscriptions_get_subscription. The description adds only the framing that the attempt may be a failed or upcoming one, 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 precise verb and effect: charges the customer's payment method now for one specific billing attempt and creates a Shopify order, with the concrete example of a failed or upcoming attempt. It does not, however, distinguish itself from the sibling sealsubscriptions_create_charge_now, which an agent could easily confuse with this tool.

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

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

"Only call it when the user clearly asked for that charge" is an explicit gating condition that tells the agent to require clear user intent before an irreversible charge. It stops short of naming the alternative to use when creating a charge outside a billing attempt, so the sibling routing 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?

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavior: billing resumes on the existing schedule and the customer may be charged, which is the key side-effect an agent needs before calling a money-affecting mutation.

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 the write-nature and operation front-loaded, followed by the sibling disambiguation and the billing consequence. Nothing is redundant.

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

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

For a one-parameter mutation with rich annotations and no output schema, the description covers purpose, alternative, and the customer-visible consequence. Only the reversion path (how to cancel again) is left unstated, which is minor.

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

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

Schema coverage is 100% and the single parameter is documented in the schema as the subscription `id` rather than `internal_id`. The description adds no further parameter meaning, which is acceptable at this coverage level, 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 ('Reactivate a cancelled subscription') and immediately disambiguates it from the near-duplicate sibling resume_subscription ('the effect is the same as resume; use this for cancelled ones'). An agent can pick between the two without opening either schema.

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

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

Gives a clear selection rule: this tool is for cancelled subscriptions, resume is effectively equivalent. It stops short of an explicit negative case (e.g. 'do not use on paused subscriptions – use resume_subscription'), so the routing is strong but inferential on the exclusion side.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds the HTTP verb (DELETE), the WRITE classification, and the precise source of the id, which helps the agent avoid passing code text. Adds real context beyond annotations without contradicting them.

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, mutation type and action front-loaded, then the id-sourcing caveat, then the endpoint. Nothing wasteful.

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

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

For a two-param destructive delete with full schema coverage and annotations carrying the safety profile, the description covers everything an agent needs to invoke it correctly. No output schema exists, but none is needed for a delete.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the critical gotcha (uuid id, not code text) for discount_code_id and points to the exact path, adding meaning beyond the schema's own description.

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

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

States a specific verb and resource: 'Remove a discount code from a subscription.' Clearly distinguishable from sibling apply_discount_code, and the 'WRITE:' prefix signals mutation immediately.

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

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

Explicitly instructs to use the discount code id from items[].discount_codes[].id, not the code text, and names the DELETE endpoint. It gives clear invocation context but doesn't explicitly contrast when to remove vs. apply beyond the obvious inverse.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally; the description adds genuine business context by explaining that the customer stops both receiving and paying for the items. It omits billing-side behavior such as proration, refunds, or whether a recalculation/invoice is triggered — material for a destructive billing mutation.

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 compact clauses with the 'WRITE:' marker and the endpoint front-loaded. Every sentence carries distinct information: action, selector, consequence, transport.

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

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

For a two-parameter destructive billing write with no output schema, the definition covers the core action but not the outcome shape or edge behavior (partial failures, proration, effect on the next invoice). Adequate, not sufficient for a billing mutation.

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

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

Schema coverage is 50%: the item id format and the 'not internal_id' distinction live in the schema, not the description. The description only echoes 'by item id'. It does not mention the 1-50 item bounds or that subscription_id is the numeric id, leaving the compensating burden largely unmet.

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 ('Remove items from a subscription') plus the selector ('by item id'), which clearly separates it from add_items and edit_items. The business consequence ('customer stops receiving and paying') reinforces intent. It stops short of naming the sibling it is most easily confused with (edit_items) 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 by the verb and the stated consequence, but there is no explicit when-to-use/when-not guidance, no prerequisite (e.g. subscription must be active), and no routing to alternatives such as reducing quantity via edit_items instead of removing the item.

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

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

Annotations already declare readOnly=false, destructive=true, idempotent=true, so the safety profile is known. The description adds the important cascading effect that reset_schedule rebuilds later attempts, which justifies the destructive hint, but it does not say what happens when reset_schedule is false or what failures/permissions to expect. The 'WRITE:' prefix merely restates annotations.

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

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

Two sentences, mutation marker and core action front-loaded, conditional side effect second, and the HTTP endpoint appended compactly. No wasted words.

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

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

For a mutation tool with full annotations and a fully documented schema, the description covers the action, the precondition, and the schedule-rebuild side effect. Only edge behavior when reset_schedule=false is left implicit.

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

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

Schema coverage is 100%, so all six parameters are already documented, including date/time/timezone formats and the subscription_id vs internal_id distinction. The description adds nothing about parameter interaction beyond echoing reset_schedule's rebuild behavior, which the schema already states.

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

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

States a specific verb and resource ('Move a billing attempt ... to another date and time') plus a scope restriction ('that has not been processed yet'), which separates it from delete/skip/process siblings without naming them. It stops short of explicit sibling differentiation, but the operation is unambiguous.

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

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

The precondition 'has not been processed yet' implies when the tool applies, and reset_schedule's effect is noted. However, it never states the alternatives (skip_billing_attempt, delete_billing_attempt, process_charge) or what an agent should do when the attempt is already processed.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true, so 'WRITE:' merely restates what the structured data says. The description never explains why the operation is destructive — what happens to the existing fulfillment order, whether the change notifies the customer, or whether it can be undone. For a destructive mutation, that is a real 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?

Two short sentences with the mutation type front-loaded and no filler. It is efficient, though the terseness leaves gaps that a slightly longer description would close.

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 five-required-parameter destructive write with no output schema, the description omits consequences, error/precondition conditions, and any indication of what the caller gets back. Annotations plus schema cover formats and safety flags but not the operational context an agent needs to invoke this confidently.

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

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

Schema description coverage is 100% and all five parameters carry their own descriptions, including format patterns and a pointer to the sibling that supplies fulfillment_order_id. The description adds nothing 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 precise verb+resource: 'Move a fulfillment order of a prepaid subscription to another date and time.' That is clear and specific. It does not, however, distinguish itself from the similarly named sibling sealsubscriptions_reschedule_billing_attempt, which an agent could easily confuse with it.

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

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

There is no guidance on when to use this versus reschedule_billing_attempt, skip_billing_attempt, or edit_subscription, and no prerequisites (e.g. that the order must not already be processed). The only implicit cue is the 'WRITE:' prefix signalling a mutation.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds the operational consequence (billing and fulfillment resume) and the underlying endpoint, but does not explain why the call is flagged destructive or what happens when the subscription is not paused.

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 with zero filler, front-loaded with the WRITE marker so an agent immediately sees mutation semantics before the effect statement.

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 with rich annotations and a fully documented schema, the description supplies purpose, effect, and transport detail. The only meaningful gap is the undefined boundary with reactivate_subscription, which matters because both siblings could plausibly apply to a non-active subscription.

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

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

Only one parameter, and the schema already documents it at 100% coverage, including the useful id-versus-internal_id distinction. The description adds nothing about the identifier beyond restating the action, 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 (resume a paused subscription) plus the concrete effect: charges and shipments continue on the schedule. That clearly separates it from pause_subscription, though it never explicitly distinguishes itself from the adjacent reactivate_subscription sibling.

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?

"Resume a paused subscription" implies the trigger condition (the subscription is currently paused) but gives no explicit when-not guidance and does not name pause_subscription or reactivate_subscription as the alternatives for adjacent states such as cancelled or scheduled-for-cancellation.

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, idempotentHint=true, and openWorldHint=true, so the safety profile is covered elsewhere. The description still contributes real value by disclosing that the subscription remains active until the scheduled date — a behavioral fact absent from the annotations. It stops short of saying whether an existing schedule can be changed or removed.

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 front-loads the WRITE nature and the core effect before the endpoint reference. Nothing is redundant and the most decision-relevant clause ('it stays active until then') is placed inside the same sentence.

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

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

With a fully documented schema and annotations that cover destructiveness and idempotency, the description needs only modest support, and the active-until-date note is the important piece. It is still thin for a destructive mutation: it does not say whether an existing scheduled cancellation is overwritten, whether the schedule can be reversed, or what a successful call returns.

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

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

Schema description coverage is 100%, with formats, patterns, and the 'id not internal_id' clarification all documented in the schema itself. The description adds no parameter-level meaning beyond confirming the date/time are future-oriented, 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 ('Schedule the cancellation of a subscription') plus a scope qualifier ('for a future date and time'), which implicitly separates it from the immediate-cancel path. It never names the immediate-cancel sibling, so the differentiation is inferred rather than explicit.

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

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

The future-dated framing tells an agent this is the right tool when cancellation should take effect later rather than immediately, which is useful implied routing. However, no sibling is named as the alternative for immediate cancellation, and no prerequisites or exclusions are given.

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

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

Annotations already declare destructive=true, openWorldHint=true, idempotent=false, so the safety profile is covered; the description still adds real value by labeling it WRITE, naming the external recipient and the payload (a payment-update link), and imposing a consent gate. It does not say the email cannot be recalled or whether the call is logged/rate-limited, so not a full 5.

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

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

Two compact sentences with the WRITE marker front-loaded, followed by effect, gate, and endpoint. Every clause carries information an agent needs; no 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, no-output-schema tool with rich annotations, this covers effect, recipient, and caution adequately. A small gap remains around outcome reporting (what the agent sees on success/failure) and whether the customer's contact address is assumed from the subscription.

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% for the single parameter, and the schema already clarifies 'the subscription's id (not its internal_id)'. The description contributes nothing further about the parameter, 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 ('SENDS AN EMAIL TO THE CUSTOMER of the subscription') plus the effect ('link to update their payment method'), and even pins the underlying call ('PUT /subscription action=send_payment_method_update_email'). No sibling tool in the list sends emails, so the agent can route here unambiguously.

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

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

Gives an explicit gating condition ('Only call it when the user clearly asked to contact the customer') and a motivating scenario ('for example after failed charges'). It lacks a named alternative (e.g., what to do instead when the user has not asked), which keeps it 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 carry destructiveHint=true and idempotentHint=true; the description adds the meaningful behavioral facts that exactly one attempt is skipped, that the customer escapes that cycle's charge, and that it is reversible via unskip. The 'WRITE:' prefix merely restates readOnlyHint=false, and it doesn't spell out whether skipping is limited to the next scheduled attempt.

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: effect first, undo second, endpoint third. No wasted clauses, and the most important information (what is skipped and why) leads.

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 only two required, fully documented params and annotations covering the safety profile, the definition gives enough to invoke it correctly, including reversibility. A note on the limits of skipping (e.g. only the next attempt in sequence) would close the remaining gap.

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

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

Schema description coverage is 100% and both parameters document their identity conventions (subscription id vs internal_id, billing_attempts[].id source), so the schema does the work. The description adds only the endpoint note 'PUT /subscription-billing-attempt action=skip', not param-level meaning.

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

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

States a specific verb (skip) and resource (one upcoming billing attempt) plus the concrete consequence ('customer is not charged for that cycle'), which removes ambiguity. It also names the inverse sibling sealsubscriptions_unskip_billing_attempt, so an agent can distinguish it from reschedule/delete variants.

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 'so the customer is not charged for that cycle' clause gives clear situational context and the description points to the undo path. It does not, however, distinguish this from the adjacent siblings delete_billing_attempt or reschedule_billing_attempt, which are the likely confusions for an agent.

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 a non-read-only, destructive, idempotent write, so the bar is lower. The description nonetheless adds the meaningful consequence — the attempt will be charged on its date again — which tells the agent this re-enables a real charge, and labels the operation WRITE with the endpoint. It stops short of noting permissions or behavior when the attempt isn't skipped, but adds genuine 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 compact sentences with zero waste: the WRITE marker and the resulting behavior are front-loaded, followed by the endpoint. 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?

With only two fully described params, rich annotations, and no output schema, the description is nearly sufficient — it explains the operation and its effect. Minor gaps remain around preconditions and error behavior, but nothing essential for invoking it correctly is missing.

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

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

Schema description coverage is 100%, and both parameters are documented in-schema, including that billing_attempt_id comes from get_subscription. The description adds no further parameter 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?

States a specific verb and resource ('Bring back a skipped billing attempt') plus the outcome ('charged on its date again'). This clearly distinguishes it from siblings like skip_billing_attempt, delete_billing_attempt, and reschedule_billing_attempt.

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 effect of use is clear (restores charging on the original date), implying this is the inverse of skipping. However, it never states when to choose this over reschedule_billing_attempt or delete_billing_attempt, nor any precondition such as the attempt actually being skipped.

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