Smartrr MCP by usefulapi

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

Annotations already declare destructiveHint and idempotentHint, but the description adds real value beyond them: the concrete effect (stops all future orders and charges), a conditional side effect (the reason may trigger configured cancellation emails or actions), and the only undo path. It does not say what happens if the subscription is already cancelled or what the response contains, which keeps 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?

The mutating/destructive signal is front-loaded in the first two words, followed by scope, side effects, recovery, dependency, and endpoint in that order. Every clause carries distinct information with no 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 3-parameter destructive write with no output schema, the description covers scope, side effects, prerequisite lookup, reversibility, and the underlying endpoint — everything an agent needs to invoke it correctly and warn appropriately.

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 in the schema, including the reason_id source. The description only repeats the reason_id provenance and embeds the other two ids in the endpoint path; it adds no format or constraint 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 precise verb and resource ('cancel a customer's subscription in the merchant's store') and explicitly disambiguates the object of the operation from the agent's own plan. An agent can distinguish it from smartrr_pause_subscription or smartrr_resume_subscription 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 the prerequisite chain explicitly — 'Get reason_id from smartrr_list_cancellation_reasons' — and names the recovery path (smartrr_resume_subscription). It does not state when to prefer pause_subscription over cancel, which is the most likely sibling confusion, so it misses the top end.

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 needs no restating. The description adds the daily-granularity behavior and the underlying endpoint path, but says nothing about date format expectations, timezone handling, whether future dates are permitted, or whether the aggregation is over the vendor's whole dataset.

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

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

Two short sentences, front-loaded with what is returned. The raw 'GET /vendor/analytics-simple' path is minor low-value filler for an agent, but it is confined 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?

There is no output schema, so the description is the only place return shape could be conveyed, and it names the two metrics but not the container (array of per-day records vs. map) or key names. Date format ambiguity for the two required parameters is also left unresolved, so it is adequate but not complete.

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

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

Schema coverage is 100% with both start_date and end_date documented, so the schema carries the parameter burden. The description only reinforces that the two dates bound an inclusive daily range; it adds no format or boundary semantics beyond that.

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: returns active subscription count and active subscriber count per day over a date range. It is clearly distinguishable in function from the entity getters/lists in the sibling set, though it does not call out that distinction itself.

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

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

Usage is only implied by the 'for each day in a date range' phrasing. There is no explicit statement of when to reach for this versus smartrr_list_subscriptions or smartrr_get_subscription, and no note about date-range limits or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the return content (status changes, retries, errors) and REST verb, which is useful, but says nothing about ordering, pagination or volume of history entries for a long-lived bill.

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, purpose front-loaded, no filler. The trailing GET path is mildly redundant but is the source of the 'audit trail' framing rather than pure noise.

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?

One required parameter, fully documented, and no output schema, so the description carries the burden of describing the return shape, which it does at the level of record categories. Missing only ordering/pagination detail, which is minor for an audit-trail read.

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

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

Schema coverage is 100% and the schema itself explains that bill_id is the numeric id from smartrr_list_bills. The description only restates the path parameter as {billId}, adding no new semantics. Baseline 3 is appropriate 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 and resource: it returns the audit trail of a single bill, enumerated as status changes, retries and errors. That is clearly distinct from smartrr_list_bills (enumeration) and smartrr_get_subscription_events (subscription-level), though the description never names those siblings explicitly.

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

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

"Of one bill" implies the use case is drilling into a single known bill id, which is adequate implied guidance. There is no explicit when-to-use, no statement that it requires a bill id already obtained from smartrr_list_bills, and no mention of alternatives for cross-bill auditing.

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 the underlying endpoint (GET /vendor/orders/{shopifyId}), confirming it is a direct remote read keyed on the Shopify id. It says nothing about not-found handling or what the payload contains, which matters more given openWorldHint.

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 plus an endpoint reference; nothing is padded. The elliptical opening ("One order by its Shopify order id") is slightly clipped, but the key constraint leads and the route follows.

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

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

There is no output schema, so the description is the only place an agent could learn what a successful response looks like, and it does not say. For a single-param, fully documented, read-only getter this is adequate but incomplete.

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 already described in the schema as the `shopifyId` from `smartrr_list_orders`. The description restates that mapping without adding format, coercion, or example details, so the baseline 3 applies.

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

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

States a specific verb+resource+cardinality: fetch exactly one order, keyed by Shopify order id. It also names the sibling (`smartrr_list_orders`) that supplies the id, so an agent can immediately distinguish this from the list variant.

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 retrieval workflow — get `shopifyId` from `smartrr_list_orders`, then call this — which is clear usage context. It does not state exclusions (e.g., use `smartrr_get_subscription_orders` when you want orders tied to a subscription rather than a bare order lookup), 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by scoping the payment method to brand, last digits and expiry only, indicating sensitive data is truncated, and it names the underlying endpoint. It says nothing about not-found behavior or error responses for a lookup that can easily miss.

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 sentence that front-loads the identifier and its source before listing returned fields, with the endpoint appended as a trailing aside. The endpoint reference is arguably redundant given the annotations, but nothing else is wasted.

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

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

There is no output schema, so enumerating the returned fields is necessary and done here; combined with the id provenance and endpoint it covers what an agent needs to call this single-parameter lookup. Only the failure mode for an invalid or stale id is left unstated.

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

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

Schema coverage is 100% and the schema already maps the parameter to `shopifyId` in smartrr_list_subscriptions. The description adds a small but real constraint, 'passed exactly as shown', warning against reformatting or extracting the id, so it does more than restate 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?

Names a specific verb (get) and resource (one subscription) plus the exact identifier that selects it, then enumerates the payload (status, schedule, next billing date, line items, discounts, address, customer, payment method). This clearly separates it from smartrr_list_subscriptions and from the get_subscription_bills/orders/events siblings.

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

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

Explicitly tells the agent where to get the argument (the `shopifyId` field from smartrr_list_subscriptions) and that it must be passed verbatim, which is the main usage decision here. It doesn't state exclusions versus siblings like get_subscription_bills, though the field list implies the distinction.

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 useful content context (status lifecycle pending/processing/succeeded/failed/canceled, retry count, error field) and the underlying endpoint, but says nothing about pagination behavior or ordering beyond what the schema states.

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, then the field list, then the identifier and endpoint. Every clause carries information, though the parenthetical field enumeration is slightly list-heavy.

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 sketching the returned record shape and status values. Combined with a fully documented param schema, an agent has enough to call it correctly; only pagination semantics and sibling disambiguation are left unstated.

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

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

Schema description coverage is 100%, so page, page_size, sort and shopify_subscription_id are fully documented in structured fields. The description reinforces the id's meaning but adds no 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?

Names a specific resource (billing attempts of one subscription), the keying identifier (Shopify subscription id), and enumerates the returned fields. The scoping phrase 'of one subscription' implicitly separates it from smartrr_list_bills, but no sibling is named 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?

Usage is implied by the required subscription id, but there is no explicit statement of when to pick this over smartrr_list_bills or smartrr_get_bill_history, nor any note that the id must come from smartrr_list_subscriptions (that hint only lives in the schema).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real value beyond them: a hard cap of the 250 most recent events (with the implication that older events are unreachable and no pagination exists) and the fact that each event records the actor ("who did it").

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 dense sentences with zero filler; the scope (250 most recent events) and the event taxonomy are front-loaded, and the endpoint tail is a compact locator. Nothing could be removed without losing 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 carries the burden of describing returns, and it does reasonably well by enumerating event types and noting the actor field. It stops short of stating the response shape, ordering, or confirming there is no pagination cursor beyond the 250 cap.

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 input schema already documents it fully (100% coverage) including the cross-reference to `shopifyId` from smartrr_list_subscriptions. The description adds no further semantics about the id, so the schema does all 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+resource (events on a subscription), enumerates the concrete event types covered (pause, skip, cancel, activate, billing attempts/failures, line-item and address changes, discounts), and anchors it to an endpoint. This clearly separates it from siblings like smartrr_get_subscription_bills or smartrr_get_subscription, which return state rather than history.

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 event list implies when the tool is useful (auditing history, tracing who changed what), but there is no explicit when-to-use or when-not-to-use guidance and no named alternative such as smartrr_get_bill_history for billing-specific detail. Usage must be inferred from the enumerated event categories.

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 externally. The description adds only the underlying endpoint path; it says nothing about pagination behavior, empty results, or ordering of returns beyond what the schema's sort/page fields imply.

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

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

Two sentences, zero filler, with the scoping qualifier front-loaded before the endpoint path. Nothing in it is redundant with 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 simple read-only list tool with a fully documented schema and no output schema, the description is nearly sufficient: 'orders generated by one subscription' conveys the return shape at a coarse level. It falls short only in not hinting at the order fields returned or pagination continuation beyond the schema's next_page reference.

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

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

Schema description coverage is 100%: page, page_size, sort, and shopify_subscription_id are each documented in the schema, including the default and max values and the cross-reference to smartrr_list_subscriptions. The description's mention of the Shopify subscription id adds no meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (orders) with a clear scope: orders belonging to one subscription, keyed by Shopify subscription id. That scope implicitly separates it from smartrr_list_orders (all orders) and smartrr_get_order (a single order), though neither sibling is named.

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 scope phrase 'Orders generated by one subscription' implies when the tool is appropriate, but there is no explicit when-to-use vs. use-smartrr_list_orders guidance and no stated prerequisites (e.g., whether the subscription must be active). Usage must be inferred rather than read.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description goes further by disclosing that `status` is applied to the fetched page rather than server-side and how to compensate via page_size/next_page – a genuine behavioral gotcha. It also notes the underlying endpoint (GET /vendor/bill) and that bill ids are numeric.

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 resource and returned fields, then the pagination caveat, then the endpoint. The inline enum repetition (pending, processing, succeeded, failed, canceled) and the 'Bill ids are numbers' detail are minor redundancy since the schema covers both, but nothing is padded.

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

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

With no output schema, the description carries the burden of describing returns and does so by enumerating the bill fields plus pagination mechanics. It does not explain the response envelope (whether total/next_page are always present) or default sort behavior, which leaves a small gap for a no-required-parameter list tool.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema; baseline 3 applies. The description adds only marginal value – it restates the status enum and implies billing-date filtering, but never mentions `sort` or the after/before boundary semantics.

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

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

States a specific verb and resource ('List billing attempts across all subscriptions') and enumerates the returned fields (amount, status, billing date, retry count, error, subscription, customer). The phrase 'across all subscriptions' implicitly distinguishes it from smartrr_get_subscription_bills, so an agent can route without opening schemas.

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: 'Filter by billing date; `status` filters the returned page only (use page_size 100 and next_page to cover more)' – this tells the agent exactly how to work around the client-side filter. It stops short of explicitly naming smartrr_get_subscription_bills as the alternative for a single subscription, so the when-not is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: the returned field set and the underlying GET /vendor/cancellation-reasons endpoint, confirming it is a plain vendor-config read with no side effects.

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 waste. The resource definition comes first, the actionable follow-up (how to use the returned id) second.

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 returned fields, and it closes the loop on how the result feeds into the cancel-subscription sibling. Nothing an agent needs in order to call this 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 and the schema baseline of 4 applies. The description adds no parameter guidance because none is needed.

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 cancellation reasons configured in Smartrr) and enumerates the returned fields (id, type, text, action, retention discount), so the agent knows exactly what it gets. It is clearly distinguishable from sibling subscription-mutation tools.

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

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

'Use an `id` as reason_id when cancelling a subscription' explicitly ties this lookup to the sibling smartrr_cancel_customer_subscription workflow. No explicit exclusions are given, but the trigger condition is unambiguous.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond them by naming the exact payload fields (email, name, phone, order count, total spent, custom attributes) and the underlying endpoint, though it says nothing about rate limits or pagination 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?

Three short sentences, front-loaded with the resource and its returned fields, with no filler. The trailing 'GET /vendor/customer-relationship' is marginal but small and occasionally useful for debugging.

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 field enumeration compensates well by telling the agent what comes back, and pagination/sorting are fully covered by the schema. Only cross-tool routing guidance is missing, which is minor for a straightforward list endpoint.

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

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

Schema description coverage is 100% and every parameter (page, sort, email, page_size, shopify_customer_id) is documented inline with defaults and bounds. The description only restates the email-fragment and Shopify-id filters, so it adds no semantics the schema lacks; 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 Smartrr customers (subscribers)') and enumerates the fields returned, which is concrete and unambiguous. It does not explicitly contrast with siblings like smartrr_list_customer_subscriptions or smartrr_list_orders, so an agent must still infer which list tool fits.

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

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

The description says how to search ('email fragment or filter by Shopify customer id'), which implies the calling context, but it never states when to prefer this tool over the sibling list/subscription tools or what it does not cover. Usage is implied rather than prescribed.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds the underlying REST path and nothing else — no pagination behavior, no note about result ordering or volume — so it adds modest context 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 key cross-tool id provenance front-loaded, followed by the endpoint. No filler; the endpoint is slightly noisy but serves as a grounding reference.

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

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

For a read-only paginated list with no output schema, the description covers purpose and id sourcing but says nothing about what a subscription record contains or how result sets behave (e.g., default status filtering). Adequate but leaves gaps an agent may need to discover at call time.

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, but the description earns extra credit by explaining exactly where customer_id comes from across two sibling tools (`custRel.id` vs `id`), a cross-tool detail the schema cannot express. It does not elaborate on status or paging, which the schema already documents.

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 scoped to a single customer, which implicitly separates it from the sibling smartrr_list_subscriptions (all subscriptions). The endpoint path reinforces the per-customer scope, though it never explicitly names the alternative 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?

Gives the provenance of customer_id (from smartrr_list_subscriptions `custRel.id` or smartrr_list_customers `id`), which implies when this tool is applicable. However, it never states when to prefer this over smartrr_list_subscriptions or what to do if the customer id is unknown, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by disclosing data provenance ('synced from Shopify') and the returned field set, but says nothing about pagination behavior, result caps, or the GET /vendor/order endpoint's practical constraints beyond naming it.

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

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

Two sentences, front-loaded with the resource and its returned fields, then the filter options. The '(e.g. #1001)' duplicates the schema's example and the trailing 'GET /vendor/order' is of marginal use to an agent, but the text is dense with little waste.

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 no output schema, the description compensates well by enumerating the returned fields, so an agent can predict the response shape without an output schema. Pagination and sorting are handled in the schema, leaving no major gap.

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

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

Schema description coverage is 100%, so page, page_size, sort, order_label, processed_after and processed_before are all fully documented in the schema. The description only restates the two filter parameters without adding syntax or format 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 ('List orders Smartrr has synced from Shopify') and enumerates what each order carries (totals, status, fulfillment status, tracking, items, customer), so an agent knows exactly what comes back. It distinguishes list-scope from the single-record sibling smartrr_get_order only implicitly via the 'filter by order label' hint, rather than naming 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?

Usage is implied — 'List orders ... Filter by processed date or order label' tells the agent this is the browse/filter entry point. It never states when to prefer smartrr_get_order for a single order, or when to use the more targeted smartrr_get_subscription_orders, so the routing decision is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description contributes the underlying endpoint (GET /vendor/selling-plan-group) and the shape of returned attributes, but says nothing about pagination, ordering, or whether plans are nested inside groups.

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 naming the resource and its fields, followed by the endpoint reference. Every clause carries information an agent needs.

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 input parameters and no output schema, the description's field enumeration is what tells the agent what comes back, and it is reasonably complete. A note on pagination or the group/plan nesting 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?

The tool takes zero parameters, so the baseline is 4. Nothing in the description is needed to explain inputs and it correctly spends no words on them.

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

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

States a specific resource (the store's subscription programs / selling plan groups) and what the result contains: name, options, delivery and billing frequency, discounts. The parenthetical translates the vendor terminology, which separates it from sibling tools like smartrr_list_subscriptions that deal with customer subscriptions. It is clear, but it never explicitly contrasts itself with those siblings.

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

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

There is no statement of when to use this tool versus the many subscription-oriented siblings (list_subscriptions, get_subscription, list_customer_subscriptions). The only implicit cue is that this returns the catalog of programs rather than customer data, which the agent must infer from the field list.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: the underlying endpoint (GET /vendor/purchase-state) and the shape of what comes back, which matters for a tool with no output schema. Pagination and rate-limit behavior are left to the schema.

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

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

Three tight sentences, no filler, with the core purpose and returned fields front-loaded. Every sentence earns its place, including the id-extraction sentence, which is not repeated in 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 field enumeration is the main compensation and it is reasonably thorough. The main remaining gap is that the description does not mention pagination or how to traverse the result pages, though the schema's `page`/`page_size` descriptions cover that. Nothing else an agent needs in order to call 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%, including enum values and pagination hints, so the schema does the heavy lifting. The description's filter sentence largely restates the schema's status/created_*/next_billing_* parameters and adds no format or syntax detail beyond it. 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?

Specific verb + resource ('List customer subscriptions') plus an enumeration of the returned fields (status, next billing date, selling plan, line items, address, discounts, customer). It also names the Smartrr internal concept 'purchase states'. It does not explicitly distinguish itself from the sibling smartrr_list_customer_subscriptions, so the reader must infer the difference from the name alone.

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 implies usage by describing the available filters (status, next billing date, creation date) and by telling the agent which ids (`id`, `custRel.id`, `shopifyId`) to harvest for the other tools. However, it never says when to use this instead of smartrr_list_customer_subscriptions or smartrr_get_subscription, and gives no exclusions.

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, idempotent, non-destructive write; the description adds real behavior beyond that: no orders or charges are generated while paused and the subscription auto-resumes on the given date. It also names the undo path, which is key for a mutation. It doesn't cover failure modes (invalid date, already-paused) but that is a small gap given the annotation coverage.

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

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

Three sentences, front-loaded with the WRITE marker and the core effect, then undo path, then parameter provenance and endpoint. 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 no-output-schema mutation with full schema coverage, the definition covers effect, reversibility, and id provenance. The only omission is the expected date format/validation for unpause_date and whether re-pausing an already-paused subscription errors.

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 would be 3; the description adds provenance by saying customer_id and subscription_id come from smartrr_list_subscriptions, which tells the agent how to obtain them. The unpause_date format is still left to the schema's terse one-liner.

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 (pause a subscription) plus the temporal scope (until a date), and immediately distinguishes it from the reversible counterpart smartrr_resume_subscription. An agent can tell it apart from cancel/skip siblings without reading further.

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 names smartrr_resume_subscription as the reversing action and directs the agent to smartrr_list_subscriptions as the source of the required ids. Missing an explicit 'when not to use' contrast against cancel or skip, but the operating context is clear.

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

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

Goes beyond the annotations by disclosing the financial consequence: the customer is charged on next_billing_date and every cycle after, and it is customer-facing against the card. This is the critical behavior for a mutation tool and is stated plainly, though it leaves open the error path for already-active subscriptions.

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 clauses plus an endpoint, with the WRITE classification and the consequence front-loaded. Every element earns its place and nothing is padded.

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

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

For a 3-parameter, fully documented mutation with annotations already covering safety and idempotency, the description supplies the missing piece — billing impact. Only the failure mode for non-resumable states is absent, which is a minor gap for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: next_billing_date is not a cosmetic field update — it is the date the customer's card is charged, which tells the agent it must be a future, intentional value. It does not add format details beyond the schema.

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

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

States a specific verb and resource ("reactivate a paused or cancelled subscription") and marks the operation class as WRITE up front. An agent can distinguish it from smartrr_pause_subscription and smartrr_cancel_customer_subscription purely from the description.

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 the precondition for use (the subscription is paused or cancelled) and implies the inverse of the pause/cancel siblings. It does not state explicitly what happens if the subscription is already active, so it falls short of a full when/when-not/alternatives statement.

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 and non-idempotency, but the description adds the actual consequence — the saved payment method is charged and an order is created — plus a repeat-call warning and the confirm requirement. That is exactly the supplemental context annotations cannot convey.

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

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

Four short, front-loaded clauses: nature of the operation, outcome, guardrails, and the underlying endpoint. No filler, and the highest-risk information (money movement) comes first.

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

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

For a two-parameter mutation with no output schema, the description covers the trigger conditions, the side effects, the idempotency risk, and the success outcome. Nothing an agent needs before calling 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 already documents both fields, so the baseline applies; however the description adds value by reinforcing that confirm must be true and by pointing to smartrr_list_bills as the source of bill_id. Minor added meaning beyond the schema.

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

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

Opens with a specific verb and resource ('retry a billing attempt') and immediately flags the write/charge nature. It is clearly distinguishable from read-only siblings like smartrr_list_bills and smartrr_get_bill_history.

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 prerequisite ('Check the bill with smartrr_list_bills first'), an exclusion ('do not retry a succeeded bill'), and the confirm=true gate. This is textbook when-to-use/when-not-to-use guidance with the alternative named.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, and the description adds real consequence context: changing the date means the customer is actually charged on that new date. It also names the underlying PUT path. It stops short of noting date-format or past-date 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?

Three short, front-loaded sentences with the mutation flag first and the consequence second. The trailing endpoint path is of marginal use to an agent but does no harm.

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 three-parameter mutation with no output schema, the description covers purpose and consequence but omits date format, timezone, and whether backdating or constraints on the new date exist — details an agent would need to avoid a bad 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 description coverage is 100%, so all three parameters are already documented. The description adds no meaning beyond the schema, such as expected date format or whether past dates are accepted, 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: changes the date a subscription is next billed and its order created. This clearly separates it from siblings like smartrr_skip_order (which skips one cycle) and smartrr_retry_bill.

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:' prefix signals a mutation and 'Customer-facing' implies caution, but there is no explicit guidance on when to use this versus skip_order, pause_subscription, or resume_subscription when the intent is to move a billing date.

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

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

Adds real context beyond the annotations: it states the outcome (no order, no charge, schedule advances) and the reversal path. The non-idempotency declared by idempotentHint=false is not spelled out (e.g. that repeated calls skip successive cycles), which is the one behavior an agent could 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 dense sentences with the WRITE marker and effect front-loaded, followed by the parameter hint, reversal and endpoint. No filler and nothing repeated from structured fields.

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

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

For a mutation tool with no output schema, it covers effect, default behavior, and reversal, which is what an agent needs to act correctly. Only the multi-call/idempotency semantics and any permission requirement are left implicit.

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

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

Schema coverage is 100%, so all three parameters are already documented, and the description's date note ('omit it to skip the next one') largely restates the schema's own 'default: the next order'. Baseline 3 applies since 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?

Opens with an explicit verb+resource+scope: 'skip one scheduled order of a subscription', distinguishing it from pause/resume/cancel siblings. The consequence clause ('no order and no charge for that cycle') further pins down what 'skip' means 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?

Gives a concrete when-condition for the optional parameter ('omit it to skip the next one') and names the inverse tool smartrr_unskip_order. It does not contrast against smartrr_pause_subscription or smartrr_set_next_billing_date, which are the plausible near-alternatives for the same intent.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the write nature is covered; the description adds real value by disclosing the downstream consequence — the order gets billed and shipped again — plus the underlying endpoint. It stops short of stating permission requirements, failure modes (e.g., no skipped order exists), or that a repeat call restores the next-earliest skip.

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, both earning their place: the 'WRITE:' prefix front-loads the mutation risk, the consequence follows, and the parameter note and endpoint are packed into the tail without 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 3-parameter mutation with no output schema, the description covers intent, effect, parameter default, and endpoint — enough to call it correctly. Missing only error/precondition behavior (what happens if no skip exists) to be fully self-sufficient.

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. The description's note about `date` restates the schema default rather than adding format examples or behavior for a date that isn't skipped, 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 (restore) on a specific resource (a previously skipped order of a subscription) and immediately names the business effect: it will be billed and shipped again. The inverse relationship to the sibling smartrr_skip_order is obvious, so an agent can route correctly without opening the schema.

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

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

The description makes the effect clear (restores billing/shipping) and notes the default when `date` is omitted, which implies the selection rule. However it never explicitly says when to use this versus siblings (skip_order, set_next_billing_date, resume_subscription) or what precondition must hold (an order must actually be skipped).

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