Awtomic MCP by usefulapi

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

Annotations already flag destructive/idempotent/openWorld, but the description adds substantive consequences: billing and shipping stop, prepaid cancellations are irreversible, Awtomic applies the cancel even if Shopify rejects it, and customer emails/SMS/webhooks may fire from the shop's automations. That is exactly the side-effect detail an agent needs before a destructive write.

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

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

Front-loads the 'WRITE' signal and the core action, then layers usage gates, side effects, and the endpoint. Every sentence carries distinct information; nothing is padding.

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

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

For a destructive mutation with no output schema, the description covers safety gating, irreversible cases, external side effects, divergence from Shopify state, and the sibling reactivation path. An agent can invoke it correctly and know the blast radius without further context.

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

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

Schema coverage is 100%, so reason, details, customer_id, and subscription_id are already fully documented with formats and examples. The description only restates the confirm_cancel=true requirement and adds nothing about the optional reason/details fields, so it does not exceed the schema baseline.

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 ('WRITE: cancel one shopper's subscription contract in Awtomic') and immediately scopes it as the shop's customer subscription, not the API plan. It is clearly separable from siblings like awtomic_pause_subscription and awtomic_reactivate_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?

Explicit gate: 'Only use it when the user explicitly asks to cancel this subscription, and confirm_cancel must be true.' It also names the reversal path (awtomic_reactivate_subscription) and its precondition (non-prepaid), which routes the agent between related tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds useful context by mirroring the REST endpoint GET /customers/{customerId}, signalling a straight API passthrough, and by listing payload contents in lieu of an output schema. It says nothing about error behavior for unknown ids or rate limiting.

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 no filler, and the return-field inventory is front-loaded before the endpoint reference. The opening 'A customer:' is a slightly awkward fragment, but 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 single-parameter read tool with no output schema, the description usefully enumerates the fields returned, which is the main thing the agent would otherwise lack. Only the routing guidance to related sibling tools is missing.

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

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

Schema description coverage is 100% and the single parameter is fully documented with id format and gid acceptance, so the schema carries the burden. The description only implies that customerId is a path segment via the REST path template, adding little 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 (get) and resource (customer) and enumerates the fields returned, which separates it from siblings like awtomic_get_customer_addresses and awtomic_get_customer_payment_methods that target sub-resources. It does not explicitly name those siblings, so differentiation is inferential rather than stated.

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

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

No statement of when to use this versus awtomic_list_customer_subscriptions or awtomic_get_subscription, and no prerequisites. The only implicit hint is that it returns subscription contract ids, which the agent must infer as a routing step.

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 that a default-address flag is included in the result, but says nothing about behavior when the customer has no addresses or about pagination/limits.

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

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

Two terse clauses with the return content front-loaded and the endpoint appended for orientation. 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 one-parameter read with annotations covering safety, the description gives enough — what is returned and that a default is marked. With no output schema, slightly more on the response shape (e.g. empty-result behavior) would be the only missing piece.

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 customer_id parameter is documented thoroughly in the schema (Shopify numeric id or gid form). The description adds nothing 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+resource (retrieve a customer's saved addresses) and adds the meaningful detail that the default address is identified. The resource is clearly distinguishable from sibling readers like awtomic_get_customer_payment_methods and awtomic_get_customer, though no 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?

No explicit when-to-use or when-not guidance, and no note on whether awtomic_get_customer already returns addresses. Usage is only implied by the resource path, which for a simple read sub-resource is a reasonable inference but leaves the sibling overlap unresolved.

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 non-obvious behavioral facts beyond that: the response never includes the full card number (a PCI-relevant constraint that shapes what the agent can do with the result), plus the underlying endpoint GET /customers/{customerId}/payment-methods. It does not state behavior for a customer with no methods on file (empty list vs. error), 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?

Three short sentences, front-loaded with the resource and its contents, then the security caveat, then the use case, then the endpoint. No filler and nothing repeated from 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?

No output schema exists, and the description compensates by enumerating the returned fields, which is the main thing an agent needs to plan around. With a single fully documented parameter and annotations carrying safety, the only real omission — empty-list behavior — is marginal for a read-only lookup.

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

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

One parameter with 100% schema description coverage, and that schema description is thorough (Shopify numeric id versus gid:// format, with an example). The tool description adds nothing about the id beyond restating it in the endpoint path, so the schema is doing all the work — baseline 3.

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

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

Names a specific verb and resource ('A customer's payment methods on file') and then enumerates exactly which fields come back (type, brand, last digits, expiry, revoked). An agent can distinguish it from awtomic_get_customer and awtomic_get_customer_addresses 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 a concrete triggering scenario: 'Use it to spot expired cards before a renewal.' That anchors the call in a real workflow. It stops short of explicit exclusions or naming an alternative tool for the other payment-related cases (e.g. awtomic_send_payment_update_email), so it is clear context without full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that this is a single-resource GET scoped to a customer/subscription pair and lists the returned attributes, but says nothing about auth requirements, rate limits, or error behavior for a missing origin order.

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 the resource definition followed by the endpoint. No filler and nothing an agent must wade through.

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 two-parameter lookup with no output schema, the description gives enough: what the resource is and the three fields returned. Only the absence of failure-mode context (what happens if no origin order exists) keeps it from a 5.

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

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

Schema coverage is 100%, so both parameters are already documented in detail (including the gid:// acceptance). The description only adds the REST path template showing where each id plugs in, which is minor value 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 the specific resource (the Shopify order that started a subscription) and enumerates what comes back (id, name, creation date), which meaningfully separates it from the sibling awtomic_get_origin_order_fulfillments. It doesn't explicitly name that sibling or otherwise tell the agent how it differs from awtomic_get_subscription, so it falls short of full sibling differentiation.

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: an agent can infer this is the call to make when it needs the original order behind a subscription contract. There is no statement of when to prefer this over awtomic_get_origin_order_fulfillments or awtomic_get_subscription, and no prerequisites 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful return-shape context (fulfillment status, fulfillment order status, fulfill-at date) but says nothing about pagination, limits, or behavior when the origin order has no fulfillments.

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 the tool returns; nothing is padded. The raw GET path is of marginal value but is 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?

There is no output schema, so the description's enumeration of returned fields (fulfillment status, fulfillment order status, fulfill-at date) contributes real information. For a read-only two-parameter lookup with guaranteed schema docs, this is close to sufficient, with only sibling routing guidance 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%, with both IDs fully documented including gid:// formats, so the schema does the heavy lifting. The description adds no parameter meaning, and its path template uses camelCase ({customerId}/{subscriptionId}) while the schema uses snake_case, a minor inconsistency an agent must map mentally.

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

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

The description uses a specific resource ("fulfillment status and the fulfillment orders ... of a subscription's origin order") rather than restating the name. It is distinguishable from awtomic_get_origin_order by scope (fulfillments only), though it never names that sibling explicitly.

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

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

Usage is only implied: the description says what data it returns, so an agent can infer it should call this when fulfillment information is needed. There is no explicit when-to-use/when-not guidance and no mention of the closely related awtomic_get_origin_order sibling.

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 shape of the returned record (selling plans and the products they apply to), which is genuinely useful. It says nothing about error behaviour for an unknown id or about permissions/caching.

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 terse fragments with the return payload front-loaded and no filler. The trailing REST endpoint path is mildly redundant but does communicate that this is a direct read of one record.

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 one required, fully documented parameter, no output schema and read-only annotations, the description supplies enough: it names the returned sub-resources so the agent knows what payload to expect. Not-found/error semantics are the only notable 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 coverage is 100% and the schema itself explains that the id may be a gId or numeric id and where to get it, so the description does not need to repeat that. The description adds no further parameter meaning, 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 the resource precisely and enumerates what comes back (selling plans with name, prepaid orders, gift support, plus applied products), which goes beyond the title. The singular 'One selling plan group' implicitly contrasts with awtomic_list_selling_plan_groups, but the contrast is never made explicit and there is no verb such as 'retrieve' or 'fetch'.

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: it returns a single group, so the agent infers it should call this when it already has an id rather than enumerating. The routing hint to awtomic_list_selling_plan_groups appears in the schema's parameter text, not the description, and there is no explicit 'use when' or 'not for' 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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value the annotations don't, by summarizing the returned payload (lines with products, quantities, prices) and giving the underlying endpoint, which matters because there is no output schema.

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

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

Three short sentences, front-loaded with the return shape before the identifiers and the endpoint. The endpoint restatement is mildly redundant but useful for orientation; otherwise there is no 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 two-parameter read with no output schema, the description supplies what an agent needs: the identifiers required and a sketch of the returned contract and its lines. A brief note on error behavior for an unknown subscription id would make it fully 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 description coverage is 100%, with both ids fully documented including accepted gid:// formats, so the schema carries the semantics. The description only repeats that both ids are required, adding no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

The description names a specific resource, one subscription contract, and adds what it contains (lines with products, quantities, prices), which clearly separates it from the list_* siblings. What's missing is an explicit contrast with awtomic_list_customer_subscriptions or awtomic_get_origin_order, but the singular scope is obvious.

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

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

It states the prerequisite (customer id plus subscription id), which implies this is a direct-lookup call, but it never says when to use this instead of awtomic_list_subscriptions or awtomic_list_customer_subscriptions. The agent has to infer that those are for discovery and this is for fetching a known contract.

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

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

Annotations already establish read-only, non-destructive, open-world behavior, so the description only needs to add semantics — and it does, by disclosing that attempts made before a migration from another subscription app are included, which is non-obvious counting behavior. No return shape or failure behavior is described.

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

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

One front-loaded sentence carrying the definition and its key edge case, followed by the endpoint path. Nothing is redundant or 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 single-param, read-only count with fully documented schema and annotations covering safety, the description is nearly sufficient. The main residual gap is that with no output schema it never confirms the return shape (a bare integer vs. an object), though the tool name implies a count.

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 subscription_id is fully documented (Shopify contract id, gid accepted), so the description adds no parameter meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb (count) and resource (successful billing attempts of a subscription), plus a scope qualifier that pre-migration attempts are included. An agent can distinguish it from the sibling list_billing_attempts, which enumerates rather than counts.

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

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

Usage is only implied: a count is what you want when you don't need the individual records, versus list_billing_attempts. The description never states when to prefer this tool over that sibling or any prerequisite, leaving the routing 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 without help. The description adds the GET endpoint path (reinforcing that this is a pure read) and what each record contains, but says nothing about result volume, ordering behavior, or how far back attempts are retained.

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: the payload is front-loaded, the use case follows, and the endpoint path closes it out. The REST path is arguably redundant given the annotations already flag a read, but it costs little and confirms semantics.

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 explaining return values, and it does so by naming the fields each attempt carries. Pagination and ordering are fully covered by the schema, so the remaining gap is minor — it never states whether failures include retry history or whether an empty list is the normal healthy case.

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 customer_id, subscription_id, limit, cursor and reverse are all documented in the schema with examples and defaults. The description adds no parameter-level meaning beyond what the schema provides, which is the baseline expectation 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?

Names the resource precisely (a subscription's billing attempts) and enumerates the returned fields (status SUCCESS/FAILURE, error code/message, amount, currency, dates), which tells an agent exactly what this tool surfaces. It does not differentiate from the nearest sibling, awtomic_get_successful_billing_count, which an agent could plausibly 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?

'Use it to see why a renewal failed' gives one concrete diagnostic scenario, which is genuine guidance beyond the name. However, there are no exclusions and no mention of alternatives — notably awtomic_get_successful_billing_count or awtomic_get_subscription — so the boundary with siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the underlying GET path, the shape of the reply, and the performance/size tradeoff of expand_lines — a genuinely useful behavioral note for an agent deciding whether to expand.

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 the scope and resource, followed by the one decision-worthy caveat and the endpoint. Nothing is wasted and nothing important is buried.

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

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

With no output schema, the description helpfully names the returned fields (id, status, next billing date) and the size implication of expand_lines, and pagination is fully covered by the limit/cursor schema descriptions. It is close to complete for a read-only list tool; only the pagination flow isn't echoed in prose.

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 customer_id, limit, and cursor are fully documented already. The description's only parameter note on expand_lines largely restates the schema's own 'Include the subscription lines (larger reply). Default false,' so it adds little beyond structured data — baseline 3.

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

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

States a specific verb and resource with explicit scope ('one customer's subscriptions') and even enumerates returned fields, which lets an agent distinguish it from the plural awtomic_list_subscriptions and from the single-resource awtomic_get_subscription. It stops short of naming those siblings explicitly, so the differentiation is implicit rather than stated.

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

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

Gives conditional guidance for expand_lines (set it to include lines, at the cost of a much larger reply), which is real usage advice. However, there is no when-to-use/when-not framing relative to awtomic_list_subscriptions or awtomic_get_subscription, and pagination behavior is left to 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the shape of what comes back (name, summary, options, position, prepaid flag) and the underlying endpoint GET /shops/selling-plan-groups, which helps the agent reason about scope; it stops short of mentioning pagination or result size limits.

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

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

Two sentences, both front-loaded: the resource and its fields first, the follow-up routing second, and the endpoint path as a trailing anchor. Every clause earns its place with 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?

With no output schema and no parameters, the description carries the burden of describing the result, which it does by enumerating the returned fields. It is nearly complete; the only missing piece is any indication of whether the list is paginated or bounded.

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 — there is nothing for the description to disambiguate. It correctly says nothing about inputs and instead spends its words on scope and return fields.

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

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

States a specific verb+resource ('The shop's selling plan groups (subscription plans)') and immediately enumerates the fields returned. The parenthetical clarifies the domain term, so an agent can distinguish it from awtomic_get_selling_plan_group 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?

Explicitly routes the agent: 'Use the ids with awtomic_get_selling_plan_group', establishing the list→get workflow and naming the sibling alternative. It doesn't state a when-not-to-use condition, but for a no-parameter list tool the flow guidance is the relevant kind.

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 and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context on top: default page size of 100, reverse ordering semantics (newest first), and the required cursor echo from next_cursor. It omits rate limits and whether the call fails on an expired cursor.

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 resource and shape front-loaded, then paging behavior. No wasted clauses, though '(id, status, next billing date and more)' hedges rather than specifying, and the trailing 'GET /subscriptions' adds little for an agent.

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 for return shape and does so (fields plus page size), and pagination is fully explained for a list tool. Given three optional parameters and annotations covering safety, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds meaning the schema lacks: 'reverse' is clarified as reading the newest first (schema only says 'Read in reverse order'), and it explains the cursor chaining convention (pass next_cursor back as cursor) rather than just 'the next_cursor of the previous reply'.

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 shop's subscription contracts') plus the returned fields and page size. It implicitly distinguishes itself from awtomic_get_subscription and awtomic_list_customer_subscriptions by scoping to the whole shop, though it 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?

The sentence 'Use reverse to read the newest first' and the cursor round-trip instruction give operational guidance, but both are parameter-level instructions rather than when-to-use/when-not guidance. Nothing tells the agent to prefer awtomic_list_customer_subscriptions for a per-customer view or awtomic_get_subscription for a single contract.

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/non-idempotent, but the description adds real context beyond them: the customer's card is actually charged, the server-side 409 ORDER_RECENTLY_PLACED guard, and that the shop's automations may send email/SMS and fire webhooks. That is the side-effect disclosure an agent needs before committing a 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?

Front-loaded with 'WRITE' and a capitalized charge warning, then constraints, then usage guidance, then side effects, then the endpoint. Dense but every sentence carries decision-relevant information; 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 destructive, no-output-schema action the description covers risk, preconditions, error behavior, and side effects. It stops short of saying what a successful response returns (e.g., the created order id), which would help an agent chain follow-up calls.

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 operative meaning beyond the schema by scoping manual_retry ('only to retry a failed billing attempt') and reinforcing that confirm_charge must be true as a consent gate. It does not add anything about id formats, which the schema already covers well.

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: bill the saved payment method and create the subscription's next order immediately rather than waiting for the billing date. This clearly distinguishes it from siblings such as awtomic_set_next_billing_date and awtomic_skip_next_order.

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?

Explicit when-to-use ('Only use it when the user explicitly asks to place this order now'), the guard condition (confirm_charge must be true), and a narrow conditional path for manual_retry ('only to retry a failed billing attempt'). The refusal condition (409 ORDER_RECENTLY_PLACED under 10 minutes) further bounds when the call is appropriate.

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 well beyond the annotations by disclosing side effects an agent cannot predict: the shop's own automations run, customer email/SMS may be sent, webhooks may fire, dunning is exited, and Awtomic pauses on its side even if Shopify rejects the request. That last point is a critical partial-success warning not available from destructiveHint/idempotentHint.

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 sentences, front-loaded with the write operation and its effect, followed by state transition, side effects, and failure semantics — no filler. The endpoint is placed last as a reference rather than a preamble.

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 state change, the inverse operation, external side effects, webhook/notification behavior, and the Shopify-rejection edge case. An agent has everything needed to call it and to warn the user about consequences.

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 already document accepted Shopify numeric and gid forms, so the description need only anchor them via the POST path template. It adds no format or validation detail beyond the schema, making baseline 3 correct.

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

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

Opens with an explicit verb+resource ('pause a subscription') and immediately states the operational effect ('not billed or shipped until reactivated'). It names the sibling that reverses it (awtomic_reactivate_subscription) and even the HTTP route, so it is unmistakable against cancel/skip/update_frequency siblings.

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

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

Gives clear context for use (stop billing/shipping; move a dunning subscription out of dunning) and points to awtomic_reactivate_subscription as the inverse. It does not explicitly exclude alternatives such as awtomic_cancel_customer_subscription or skip_next_order, so the when-not case 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?

Adds substantial behavior beyond the annotations: billing resumes, the customer is charged on the next billing date, the date is derived from the subscription interval when omitted, and shop automations may trigger email/SMS and webhooks. The prepaid-subscription failure mode is especially valuable for a destructive, open-world write.

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:' action label, then the business rule, then the parameter behavior and side effects. Every sentence carries information, though the trailing endpoint path is largely redundant with the schema parameters.

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

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

Covers the operation's effect, failure mode, default parameter behavior, and side effects, which is sufficient for a 3-parameter write with no output schema. It stops short of saying what the call returns or how to confirm success, which would be the only 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 coverage is 100%, so the baseline is 3, but the description adds real meaning for next_billing_date: it explains the default derivation from the subscription interval and that the customer is charged on that date. customer_id and subscription_id are left to the schema, which is acceptable given 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 ('reactivate') and resource ('a paused or cancelled subscription') plus the effect ('billing resumes'), and labels it 'WRITE'. This is readily distinguishable from siblings like awtomic_pause_subscription or awtomic_cancel_customer_subscription.

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

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

Gives a clear use condition (paused or cancelled subscription) and one explicit exclusion (a cancelled prepaid subscription cannot be reactivated). It does not name sibling tools as alternatives, but the applicability rule 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 destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds real value beyond them by emphasizing 'This SENDS AN EMAIL TO THE CUSTOMER each time it is called,' which concretely explains the non-idempotent, externally-visible side effect and warns against repeated invocation. It does not cover rate limits or whether the link expires, 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 'WRITE:' prefix front-loads the mutation nature, the irreversible/outbound warning follows immediately, and the guardrail conditions come next. Three tight sentences plus the endpoint path, with 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 3-parameter mutation with no output schema, the description covers action, side effect, trigger conditions, and the confirmation requirement — everything an agent needs to decide and call correctly.

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

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

Schema coverage is 100% and each parameter already has a clear description, including the const-true confirm_send gate. The description's 'confirm_send must be true' largely restates schema content rather than adding format or source-of-value guidance, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'make Shopify email the customer a link to update their payment method for this subscription.' It distinguishes itself from all read-side siblings (get_customer_payment_methods, get_subscription) by making clear it sends an outbound email rather than retrieving data.

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 explicit trigger conditions ('failed payments or expired cards') and a hard guardrail ('only when the user asks, and confirm_send must be true'). It does not name an alternative sibling for the common adjacent use case (e.g. checking payment methods first via awtomic_get_customer_payment_methods), so it stops short of full routing guidance.

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

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

Annotations already mark this as a destructive write, but the description adds important side effects beyond them: a paused subscription is reactivated, one in dunning is taken out of dunning, and the customer is charged on the new date. It does not repeat idempotency or mention authorization requirements, but the key behavioral consequences are disclosed.

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 short, front-loaded with "WRITE:", and every sentence earns its place by covering purpose, constraints, side effects, and the endpoint. There is no filler or redundant restatement.

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 no output schema, the description supplies the essential context: the write nature, date constraint, reactivation/dunning effects, charge consequence, and endpoint. It omits explicit guidance on when to prefer sibling tools, but otherwise gives enough to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already explains customer_id, subscription_id, and next_billing_date in detail. The description restates the date constraint but adds no parameter-level meaning beyond the schema, making the baseline 3 appropriate.

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

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

The description opens with a specific verb and resource: "WRITE: change when a subscription is next billed." This clearly distinguishes the tool from read-oriented siblings such as awtomic_get_subscription and awtomic_list_subscriptions, and the included endpoint confirms the operation.

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

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

The description gives clear operational context: the date must be later than today, and paused or dunning subscriptions are affected. It does not explicitly compare this action to alternatives like awtomic_skip_next_order, awtomic_order_now, or awtomic_pause_subscription, so the when-not-to-use guidance is incomplete.

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 well beyond the annotations by disclosing downstream side effects: the shop's own automations run, so the customer may receive email or SMS and webhooks may fire. It also explains the compounding behavior of repeated calls and that the reply carries a skipEventId needed for reversal — exactly the operational context a destructive, non-idempotent write needs.

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

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

Four tight sentences: intent first, precondition second, hazards and undo third, endpoint last. Nothing is padded and the leading 'WRITE:' flags the mutation before an agent reads further.

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 mutation with no output schema, the description covers precondition, irreversibility/undo mechanism, reply field, and external side effects. An agent has everything needed to decide and to call it responsibly.

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 with formats and gid:// alternatives, so the schema carries the weight. The description adds only the endpoint template, which implicitly maps customer_id and subscription_id to path segments but supplies no new format or validation detail.

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

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

Opens with a specific verb+resource phrase ('skip a subscription's next order') prefixed by a WRITE marker, and closes with the underlying endpoint. It is unmistakably distinct from sibling reads like awtomic_get_subscription and from mutators like awtomic_set_next_billing_date or awtomic_cancel_customer_subscription.

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

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

Gives a clear precondition ('The subscription must be active'), an explicit warning against repeat invocation ('each call skips one more order, so do not repeat it'), and names the undo path via awtomic_undo_skip. It stops short of contrasting with the nearest sibling, awtomic_set_next_billing_date, which an agent could reasonably confuse with this when the goal is a precise 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?

Annotations already flag this as a destructive, idempotent write, and the description adds value on top: it labels the operation WRITE, explains what the mutation actually restores (the pre-skip billing date), and discloses the 409 refusal path. It doesn't say what the success response contains or whether the restored date is visible before/after, but the annotation coverage keeps the bar low.

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?

It is a single dense paragraph that front-loads the WRITE label and the effect, then the prerequisite, then the failure mode. The trailing endpoint/eventType detail is slightly implementation-verbose but still earns its place as disambiguation for the underlying API call.

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

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

For a 3-required-parameter mutation with no output schema, the description covers the operation's effect, its input dependency, and its failure mode, which is enough for an agent to decide and invoke. Only the return value on success 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 description coverage is 100%, so all three parameters are already documented in the schema, including the note that skipEventId comes from awtomic_skip_next_order. The description repeats that dependency rather than adding format or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

The description uses a precise verb ('undo a skipped order') and states the concrete effect ('restoring the billing date from before the skip'). It also ties itself to the sibling awtomic_skip_next_order, so an agent can distinguish it from skip/pause/set_next_billing_date operations 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?

It clearly states the prerequisite (the skipEventId returned by awtomic_skip_next_order) and a real failure condition (Awtomic refuses with 409 when the skip can no longer be undone). It stops short of explicitly naming alternatives for other billing-date changes, but the context for when to reach for it 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 readOnly=false, destructive=true, and idempotent=true; the description adds meaningful context by disclosing the blast radius ('Changes every future order of that subscription'), which is exactly what matters for a destructive write. It does not mention reversibility or auth requirements, keeping it 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?

Three tight clauses led by 'WRITE:', then the concretized example, effect scope, and endpoint. Zero filler and front-loaded with the important signal.

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

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

For a 4-param, all-required write tool with annotations covering safety and no output schema, the description gives purpose, scope, and endpoint adequately. Minor gap: no note on whether/how the change can be reverted.

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

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

Schema coverage is 100%, so the schema documents each parameter. The description adds value by showing the combined semantics ('every 2 WEEK' pairs interval_count with interval), reinforcing how the two fields interact beyond the per-field schema text.

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 (change) plus resource (subscription frequency/billing and delivery), with concrete examples like 'every 2 WEEK or every 1 MONTH'. This clearly distinguishes it from siblings such as set_next_billing_date or pause_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?

The description explains the effect scope ('Changes every future order of that subscription'), which implies when to use it, but it names no alternative or exclusion (e.g. vs. changing just the next date). Usage is inferred rather than explicitly guided.

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