Cratejoy MCP by usefulapi

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description still adds real value: what the cancellation achieves operationally (stops boxes and renewals) and that it is reversible via reactivate. It does not mention permission requirements or any rate/limit behavior, which keeps 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?

A single front-loaded paragraph that opens with 'WRITE:' so the mutation type is the first thing read, then layers disambiguation, prerequisite, and recovery in descending priority. Every sentence 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 annotations covering the safety profile and a full-coverage schema, the description fills the remaining gaps an agent needs: what the write does to the customer, how it differs from the similarly named tool, the confirm gate, and reversibility. No output schema is needed since the description does not promise a return shape.

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 confirm=true constraint and the log_note log purpose. The description restates the confirm requirement without adding format, bounds, or semantics beyond what the schema provides, 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 ('cancel a subscriber's subscription in Cratejoy') and immediately scopes it against a confusingly similar sibling ('NOT this server's Pro plan'). The agent can distinguish this from cratejoy_reactivate_subscription and the Pro-plan cancel tool without opening a schema.

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

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

Explicitly names the alternative tool for the Pro-plan case and the condition that selects it, plus states the prerequisite ('Requires confirm=true') and the recovery path (cratejoy_reactivate_subscription). Nothing about when to use or not use this tool 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 fully covered. The description adds the concrete endpoint (GET /v1/customers/{customer_id}/) and notes that relationships are optional embeds, which is modest extra context but no auth, pagination, or failure-mode detail.

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 fragments with the core purpose front-loaded and no filler. The trailing raw endpoint is slightly redundant but cheap and aids API mapping.

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 tool with full schema coverage and no output schema, the description covers what is fetched and what can be embedded. Return-shape detail is the only meaningful omission, and the annotations carry the rest.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema, including the 'with' pattern and the vendor-default fallback. The description only restates the existence of relationship embedding, adding no syntax or default detail beyond the schema.

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

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

The description names a specific verb (get), resource (customer), and scope (by id), and the phrase 'One customer by id' implicitly distinguishes it from cratejoy_list_customers. It stops short of explicitly naming that sibling, so an agent must infer the single-vs-list split.

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

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

Usage is implied by 'by id' and the optional relationship embedding, but there is no explicit statement of when to prefer this over cratejoy_list_customers or the other get_* siblings. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety and reach profile is covered. The description only adds the REST endpoint path and a restatement of embeddable relationships, not behavioral traits like auth requirements, rate limits, or 404 behavior when the id is unknown.

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 telegraphic sentence that front-loads the core purpose and tacks on the optional parameter and endpoint. No wasted words, though the trailing REST path is low-value 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?

For a simple read-by-id tool with annotations covering the safety profile and no output schema, the description is minimally sufficient. It omits what a missing or unauthorized order returns and does not state pagination-free single-resource semantics explicitly.

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

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

Schema description coverage is 100%, so both order_id and with are fully documented in the schema, and the baseline is 3. The description enumerates specific relationship names (customer, products, coupons, addresses, fulfillments, transactions), which adds mild value over the schema's generic pattern but also diverges from the schema's own example.

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 scope ('One order by id'), which implicitly separates it from the sibling cratejoy_list_orders. It does not explicitly name the list alternative, so sibling differentiation is inferred 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?

The phrase 'optionally with relationships' hints at when the embed parameter matters, but there is no explicit guidance on when to call this versus cratejoy_list_orders or when to use 'with=all' versus a specific subset. Usage 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 externally. The description adds the underlying REST endpoint (GET /v1/products/{prod_id}/), which is mild corroborating context, but says nothing about auth requirements, rate limits, or what happens when the id does not exist.

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 core behavior and scope before the endpoint detail. No filler; every clause earns its place.

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 must carry the burden of explaining what is returned beyond 'one product'. It confirms singular retrieval but not the response shape or error behavior, leaving a modest gap for a read tool with two parameters.

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

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

Schema description coverage is 100%, so both product_id and the with relationship parameter are fully documented in the schema, including the comma-separated and 'all' formats. The description only restates 'by id' and 'optionally with relationships', adding no syntax or default detail beyond the schema.

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

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

The description states a specific verb and resource — 'One product by id' — which is unambiguous and implicitly contrasts with the sibling cratejoy_list_products. It stops short of explicitly naming the list alternative, but an agent can distinguish retrieval-by-id from listing 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?

There is no explicit when-to-use guidance, no exclusions, and no named alternative among the many get_* and list_* siblings. 'Optionally with relationships' hints at the embed option but does not tell the agent when that is appropriate or when to prefer cratejoy_list_products.

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 elsewhere. The description adds only that relationships can be embedded and echoes the endpoint path; it says nothing about 404 behavior, whether missing relationships are silently omitted, or any rate limit.

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 fragments with zero filler; the scope statement leads and the endpoint reference trails. Nothing can be cut 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 some burden for describing the returned shipment object's shape, and it offers none — an agent learns which relationships can be attached but not what the payload contains or how embedded relationships are keyed. Adequate but with a real 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 genuinely adds value: it enumerates the valid relationship names (customer, fulfillments, labels, ship_address, subscriptions), which is more useful than the schema's generic example 'customer,orders' that does not obviously apply to shipments.

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 verb and resource — retrieving one shipment by id — and even pins the REST endpoint, so an agent can immediately tell it apart from cratejoy_list_shipments. It stops short of explicitly contrasting itself with the list sibling, which is all that separates it from a 5.

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

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

Usage is implied by the 'by id' framing and the required shipment_id, so the agent knows this is a single-record fetch rather than a listing. However, there is no explicit when-to-use guidance, no mention of what to do when the id is unknown or when relationships should be omitted, and no named alternative.

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 concrete endpoint (GET /v1/metadata/) and the fact that 'data' is free-form JSON, which is genuinely useful beyond the annotations, but it says nothing about auth, rate limits, or error behavior.

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

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

A single compact sentence that front-loads the resource and then the field list; nothing is padded. It is arguably terse to the point of omitting usage guidance, but every listed element earns its place.

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 effectively serves as the return-shape documentation by listing id, store_id, timestamps and data. Only the nature of the 'data' blob is left vague, which is a minor gap for an otherwise simple read 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?

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. The schema is an empty object with 100% coverage, so no compensation is required.

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 ('store-level metadata record') and enumerates its fields, so an agent knows exactly what comes back. It is framed as a noun phrase rather than a verb+resource clause, but no sibling tool covers store metadata, so differentiation is implicit and unambiguous.

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

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

There is no statement of when to call this versus the many sibling get_* tools, nor any prerequisites or exclusions. The GET endpoint hint implies a read-only fetch, but usage context is left entirely 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 state readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that relationships can optionally be embedded, which is useful response-shaping context, but it does not describe auth needs, error behavior, or rate limits. With annotations covering the core traits, a 3 is appropriate.

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 a single front-loaded sentence followed by the endpoint, with no wasted words. It immediately conveys the core purpose and optional relationship embedding. Both elements earn their place.

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 get-by-id tool with full schema coverage and annotations covering safety, the description is nearly complete. It states the resource and optional embed behavior. It could mention return shape or not-found behavior since there is no output schema, but the missing detail is minor.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by enumerating usable relationship names for the 'with' parameter (customer, billing, term, product, address, orders, shipments, logs), beyond the generic pattern in the schema. This meaningfully improves parameter interpretation.

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

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

The description states a specific resource and scope: 'One subscription by id,' distinguishing it from list_subscriptions and other resource getters. The endpoint 'GET /v1/subscriptions/{sub_id}/' reinforces the retrieval purpose. An agent can identify this as a single-subscription fetch without ambiguity.

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

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

The description implies usage when a specific subscription id is known and relationships may be embedded, but it does not explicitly say when to use this tool versus list_subscriptions or other alternatives. No exclusions or preconditions are stated. This is minimum-viable implied 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 safety is covered. The description adds nothing behavioral beyond that – it simply restates the HTTP route, giving no information on error/not-found handling, scope of the returned transaction, or rate 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?

Two short sentences, front-loaded with the essential fact (single transaction by id). The trailing endpoint path is mildly redundant wikitext rather than useful guidance, but it costs little.

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

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

For a simple annotated read with two fully documented parameters, the description is adequate to invoke it correctly. However, with no output schema present, it says nothing about what fields a transaction record contains or how embeds affect the response, leaving that to discovery.

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 'transaction_id' and 'with' fully documented including the embed pattern, so the description need not explain parameters. It adds no meaning beyond the schema, which is the expected baseline 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?

The description states a specific retrieval action and resource: one payment transaction, keyed by id. The phrase 'by id' implicitly distinguishes it from cratejoy_list_transactions, though no sibling is named. It is clear what the tool returns at a high level.

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 infers it should call this when it already holds a transaction id and wants the single record rather than a list. There is no explicit when-to-use, no prerequisite (e.g. needing a valid id from list_transactions), and no stated alternatives.

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

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

Annotations already establish readOnly, non-destructive, and openWorld, so the safety profile is covered. The description adds the embeddable relationships (addresses, logs, carts, notes, orders, shipments, subscriptions) and the endpoint, but says nothing about result caps, rate limits, or what the vendor default for `with` is.

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 that front-loads the resource and returned fields before filtering and relationships. It is run-on but every clause carries information and there is 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, the description helpfully enumerates the returned fields and available relationships, which is the key missing context for a list tool. It leaves the page/next_page loop to the schema, which documents it adequately, so nearly everything needed to call it correctly is present.

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

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

Schema description coverage is 100%, so every parameter is already documented; baseline is 3. The description restates the email/name filtering and adds a nested `addresses.city` filter example, which is mildly useful beyond the schema's own `customer.email__like` example, but otherwise adds no syntax or default 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?

States a specific verb ('List') and resource ('customers'), enumerates the returned fields, and discloses the backing endpoint (GET /v1/customers/). It doesn't explicitly contrast itself with siblings like cratejoy_get_customer, but 'list' vs 'get' plus the enumeration makes the scope inferable.

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

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

Explains what can be filtered (email, name, or `filters`) and gives a filter example, which implies when to reach for it. However, there is no explicit guidance on when to prefer cratejoy_get_customer for a single record, nor any note about pagination workflow beyond what the schema's `page` description already says.

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 goes further by flagging that all amounts are in cents and that the underlying call is GET /v1/orders/. It still does not describe pagination semantics beyond what the schema's page/limit fields imply, so it is strong but not exhaustive.

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 front-loaded sentences: identity plus field list, then units and filtering, then relationships and endpoint. The parenthetical field list is long but earns its place given there is no output schema. 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, the enumerated field list is the right compensating detail, and filtering, relationship embedding, units and endpoint are all covered. Pagination behavior across pages is only implied by the schema's page field, leaving a small gap for a tool with 7 parameters and nested `filter` objects.

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 formal baseline is 3, but the description adds genuinely useful meaning: the concrete list of embeddable relationships (customer, products, coupons, bill_address, ship_address, fulfillments, transactions, subscriptions) expands on the bare 'customer,orders' example in `with`, and the cents note contextualizes the monetary fields. It does not clarify the filters comparison operators 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 ("List orders") and enumerates the fields each order carries, which cleanly separates it from cratejoy_get_order and the other cratejoy_list_* siblings. An agent knows exactly what it receives 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?

It gives filtering context ("Filter by payment status and placed-at range, or with `filters`") but never states when to prefer the dedicated placed_after/placed_before/financial_status params over the generic `filters` object, nor when to use this list tool at all versus lookups like cratejoy_get_order. Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds value beyond that by listing the returned fields, supported relationships, and the underlying endpoint, though it says nothing about result ordering or rate 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?

A single dense sentence-block with the resource name and returned fields front-loaded. It is appropriately sized, though the parenthetical field list and relationship list make it slightly cluttered.

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

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

With no output schema, the description usefully enumerates returned fields and relationships, and the schema fully documents pagination and filters. It is nearly complete for a read-only list tool, missing only expected result ordering/defaults.

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 baseline is 3. The description restates that filtering works by type or a `filters` object and names the embeddable relationships, but adds no syntax or semantics beyond the already-detailed 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 (List) and resource (products) and enumerates the fields returned, so an agent knows exactly what the call yields. It is clearly distinguishable from siblings like cratejoy_get_product (single fetch) and cratejoy_list_orders.

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

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

Usage is implied by the verb 'List' and the mention of filtering, but the description never states when to prefer this over cratejoy_get_product or how it relates to the other list_* tools. No explicit exclusions or 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by listing the exact returned fields, the embeddable relationships, and the underlying endpoint. Pagination behavior is left entirely 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 compact, front-loaded sentences packed with concrete detail (field list, filter mechanism, relationships, endpoint) and no filler. Dense but readable.

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, so the enumerated field list and relationship names in the description usefully fill that gap, and annotations cover the read-only safety profile. For a read-only list tool this is nearly complete, though it could note default pagination behavior.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including status, created_after/created_before, filters, with, page, and limit. The description merely echoes filter capability, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('List shipments') and enumerates the returned fields, so an agent knows exactly what this retrieves. It does not explicitly contrast itself with the singular sibling cratejoy_get_shipment, but list-vs-get is self-evident.

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?

Says 'Filter by status and creation range, or with `filters`', which implies how to narrow results, but gives no when-to-use guidance or exclusions relative to siblings like cratejoy_get_shipment or cratejoy_list_orders. Usage is inferable but not 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the underlying endpoint (GET /v1/subscriptions/{sub_id}/coupons/) and the shape of the payload, but says nothing about pagination behavior (beyond what the schema states) or permission requirements.

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

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

Two compact lines: the resource/scope statement first, then the field list and endpoint. No padding or redundancy, though the telegraphic style omits a clear verb, making it read more like a spec fragment than an instruction.

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 partially compensates by listing the main return fields, and pagination parameters are documented in the schema. However it omits any note on how pagination results should be consumed or what happens for subscriptions with no coupons, leaving a modest gap for a 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%, so page, limit, and subscription_id are fully documented in the schema itself. The description's parenthetical field list refers to response fields, not input parameters, so it 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?

The description names the exact resource and scope: coupons applied to a subscription's next renewal, and enumerates the returned fields (coupon_id, code_used, enabled, num_renewals). It is clear what the tool fetches, though the verb (list/retrieve) is only implied from the title rather than stated, and there is no coupon-related sibling to differentiate against.

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 versus alternatives, no prerequisites, and no exclusions. The reader can infer it inspects a subscription's coupons, but nothing in the text guides invocation timing or distinguishes it from sibling tools like cratejoy_get_subscription.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open-world), so the bar is lower. The description adds real value beyond them: the exact fields returned, the embeddable relationships, and the filter-expression grammar. It does not restate the read-only nature, so there is no contradiction.

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 block that states the resource, the returned fields, the filtering options, the relationships, and the endpoint with no filler. Every clause carries information an agent would otherwise have to infer.

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

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

With no output schema, the description correctly compensates by listing returned fields and relationships. For a 7-param list tool with full schema coverage, this is nearly complete; it omits only pagination behavior, which the schema handles via the next_page hint on page.

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 fully documents page, with, limit, status, filters, ends_after, and ends_before. The description's example filters object and field list add marginal color but no syntax beyond what the schema already specifies; 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 ('List subscriptions') and enumerates the fields returned, making the tool's job unambiguous. It contrasts implicitly with cratejoy_get_subscription via the list/get naming convention, but never names a sibling or states the single-vs-collection distinction 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?

It describes how to filter ('Filter by status and end-date range, or with filters') but never says when to reach for this tool over get_subscription or the other list_* siblings, and offers no when-not conditions. Usage is only implied by the tool's purpose.

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 endpoint path and the shape of returned records, but says nothing about pagination behavior or result volume beyond what the schema's page/limit 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 tight sentences with zero filler; the core listing purpose and its return fields come first, followed by filtering options and the endpoint. Every clause carries information.

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

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

With no output schema, the description usefully enumerates the returned fields (id, created_at, result, total in cents, is_test, order), which is real added value. Pagination mechanics are left to the schema, which is acceptable, though it stops short of noting anything about result ordering or total counts.

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

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

Schema description coverage is 100%, so every parameter (page, limit, with, result, filters, created_after/before) is already documented in the schema. The description only restates the result/date-range/filters options at a high level without adding syntax or defaults, 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 payment transactions'), enumerates the returned fields, and names the exact filtering dimensions plus the underlying endpoint GET /v1/transactions/. It is clearly distinguishable from the singular cratejoy_get_transaction sibling.

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

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

The description says how to filter (by result, creation range, or `filters`) but never states when to choose this tool over cratejoy_get_transaction for a single record or cratejoy_list_orders for order data. Usage is implied by the plural 'list' framing 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 destructiveHint=true and idempotentHint=true, and the description goes further by disclosing the financial consequence (the customer is charged again), the no-op behavior against active subscriptions, and the required confirmation. That is meaningful context beyond the structured hints, including a partial safety reassurance about idempotency on active subs.

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

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

Three tight sentences front-load the operation type and effect, then the confirm requirement, then the edge case, ending with the endpoint. Every sentence carries information and nothing 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, and the description adequately covers the action, prerequisite, and active-subscription edge case. It does not say what happens if the subscription is in a non-cancelled state other than active, nor what success returns, which keeps it short of 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%, so the schema already documents confirm, subscription_id and log_note. The description restates the confirm=true requirement but adds no format, range, or note-usage detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb (reactivate) and resource (cancelled subscription), plus the concrete downstream effect: it will renew and charge the customer again. That billing outcome distinguishes it immediately from the sibling cratejoy_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?

It states the applicable case (a cancelled subscription) and a partial when-not condition: reactivating an already-active subscription is a no-op. It also flags the confirm=true prerequisite. It stops short of naming the cancel/retry/skip siblings as alternatives, so it is strong but not exhaustive.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds the crucial behavioral fact that this charges the customer's saved payment method and requires confirm=true, plus the underlying endpoint. It stops short of stating the double-charge risk implied by non-idempotency or what happens on a declined retry.

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 front-loaded sentences with a leading WRITE marker, the scope constraint, the side effect, and the prerequisite — no filler, and the most dangerous fact is surfaced early.

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 non-idempotent destructive write with no output schema, the description covers status precondition, time limit, payment side effect, and the confirm gate. Minor gaps remain (behavior on decline, whether the 30-day window is enforced or merely advisory), but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so subscription_id, confirm, and log_note are already documented in the schema. The description only reiterates the confirm=true requirement, adding no syntax or 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?

The description gives a specific verb (retry the renewal), the exact resource (a PAST-DUE subscription whose renewal failed), and a temporal scope (within the last 30 days). This scope constraint cleanly separates it from siblings like cratejoy_reactivate_subscription and cratejoy_skip_subscription_renewal.

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 precise condition that selects this tool (past-due status, failure within 30 days) and the confirm=true prerequisite. It does not name the alternative siblings (reactivate, skip) or when to prefer them, so it stops short of explicit routing.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the bar is lower; the description still adds value by stating that repeating the same action is a no-op, that confirm=true is mandatory, and that the mutation targets a merchant customer's subscription rather than server billing. It does not explain error behavior when confirm is omitted or what state the subscription is left in beyond implying unskip reverses it, and the implied reversibility sits slightly awkwardly against destructiveHint=true (though it is not a contradiction).

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 mutation nature with 'WRITE:' and packs scope, prerequisites, and idempotency into three short sentences with no filler. The trailing 'PUT /v1/subscriptions/{sub_id}/skip/' line is mildly technical overhead but still informative for endpoint mapping.

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 write tool with annotations but no output schema, the description covers prerequisites, reversibility via unskip, idempotency, and the target-of-mutation scope. What is missing is guidance on failure cases and how a skip affects the renewal schedule's downstream state, which matters for a destructiveHint write.

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%: action's enum values, confirm's const true, and subscription_id are all documented in the schema itself. The description restates the action semantics and the confirm requirement without adding format, range, or edge-case 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?

The description names a specific verb and resource (skip a subscriber's next renewal / undo the skip) and immediately clarifies scope ('not this server's own billing'). It does not name any sibling such as cratejoy_cancel_customer_subscription or cratejoy_retry_subscription_renewal to draw the boundary explicitly, so an agent must infer the difference between skipping and cancelling.

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

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

It gives a clear condition for use ('skip' the next renewal, 'unskip' to undo it) plus the prerequisite that confirm=true is required, which is real invocation guidance. It stops short of naming an alternative tool or stating when NOT to use it (e.g., when the customer wants to cancel outright rather than pause one renewal).

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