Swell MCP by usefulapi

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

Annotations already carry destructiveHint=true, but the description reinforces this with a front-loaded "MUTATES LIVE STORE DATA" warning and explains a non-obvious behavior: arbitrary keys in `fields` are merged into the request body. It still omits auth requirements and any side effects on related resources, 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?

Four tight sentences with the critical mutation warning front-loaded and no filler. The endpoint line is optional developer metadata but still earns its place by anchoring the tool to the REST API.

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 create tool with a free-form nested `fields` object, full schema coverage, and destructiveHint already declared, the description covers the operation, the required field, and the merging escape hatch. Return-value behavior and auth prerequisites are unaddressed, but no output schema exists so that omission is tolerable.

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 genuine meaning beyond the schema: it tells the agent that only `name` is mandatory and that unlisted properties should be funneled through the `fields` object, which the schema does not explain. That merge behavior is the key semantic an agent needs.

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 ("Create a new product in the store") and even names the underlying REST operation (POST /products), so an agent can distinguish it from swell_update_product and swell_get_product. It does not explicitly name those siblings, but the create verb is unambiguous.

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

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

Gives calling guidance ("name is required; anything else goes in `fields`") rather than selection guidance. There is no explicit statement of when to use this versus swell_update_product or how it relates to the list/get siblings, so usage is only implied by the create semantics.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds genuinely useful context by mapping "customer" to the Swell `accounts` model and giving the backend route, but says nothing about error behavior (e.g. missing id) or the shape of what comes back.

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 core action and id requirement, followed by optional-parameter support and the underlying endpoint. 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?

For a single-resource read with full annotation coverage and full schema coverage, the description covers purpose, optional params, and the model/endpoint mapping. Only the return shape and not-found behavior are unstated, and the latter is a minor gap given the absence of an output schema.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema with an example for `expand`. The description only restates that `expand` and `fields` are supported, adding no syntax or semantics 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 ("Fetch a single customer ... by id") and clarifies the underlying model name (`accounts`) plus the REST route. The word "single" implicitly separates it from the sibling `swell_list_customers`, but the sibling is never named, so the 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?

Usage is implied: retrieve one customer when you already have an id. There is no explicit guidance on when to prefer this over `swell_list_customers` or `swell_query`, and no note about what happens for an unknown id.

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

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

readOnlyHint=true already tells the agent this is a safe read, lowering the burden. The description adds the lookup flexibility and mentions expand/fields, but says nothing about not-found/error behavior, auth needs, or rate limits, so the added behavioral context is modest.

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 core action, followed by optional capabilities and the REST endpoint. Nothing is redundant or padded.

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

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

For a simple single-record read with full annotation coverage of safety and 100% schema coverage of params, the description covers what an agent needs. No output schema exists, so return-value detail is not required, though error handling is unaddressed.

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

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

Schema description coverage is 100%, so all three parameters (id, expand, fields) are already documented. The description's restatement of the id lookup and expand/fields adds no syntax or format 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?

States a specific verb (fetch) and resource (a single order) and clarifies the two lookup keys (record id or order number). The word 'single' implicitly separates it from swell_list_orders, but no sibling is named explicitly, so it falls just short of the top mark.

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: fetching one order by id/number. There is no statement of when to prefer this over swell_list_orders or swell_query, no prerequisites, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the backend route (GET /products/{id}) and notes expand/fields support, but says nothing about not-found behavior, permissions, or response shape. With annotations carrying the safety profile, this is acceptable but thin.

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 plus the REST route, front-loaded with the core action. Efficient overall, though the REST endpoint line is marginal value for an agent that already has the tool name and schema.

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

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

For a simple single-record read with full schema coverage and a readOnlyHint annotation, no output schema explanation is needed. The definition is complete enough to invoke correctly; only edge-case behavior (missing record) is unaddressed.

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

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

Schema description coverage is 100%, so all three parameters (id, expand, fields) are already documented in the schema with examples. The description only restates that expand and fields are supported, adding no syntax 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?

States a specific verb (fetch) and resource (a single product) with the two accepted identifiers (record id or slug). The word 'single' cleanly distinguishes it from the sibling swell_list_products without needing to reference it.

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

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

The 'single product' framing implies when this is preferable to the list endpoint, but no explicit when-to-use, prerequisites, or named alternative is given. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the read-only safety profile is covered. The description adds the underlying REST endpoint (GET /subscriptions/{id}), which is mildly useful context, but discloses nothing about what is returned, error behavior, or the effect of expand on payload size.

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 clauses, front-loaded with the action and resource. The trailing REST endpoint is useful for backend-oriented agents, though 'Supports expand' is terse and could say more about what expansion does.

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 the return value, and it does not — an agent cannot tell what a subscription object contains or how expand changes the response. For a simple two-parameter read tool with readOnlyHint this is adequate but has a clear gap.

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

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

Schema description coverage is 100%, so both id and expand are already documented in the schema, including the comma-separated expand format. The description merely echoes 'by id' and 'supports expand' without adding syntax or constraint detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a single subscription by id'), and the word 'single' implicitly contrasts with the sibling swell_list_subscriptions. It does not name that sibling explicitly, so the differentiation is inferable 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 'by id' implies the precondition that a subscription id is required, but the description gives no when-to-use framing, no indication of when to prefer this over swell_list_subscriptions, and no guidance on the failure case of an unknown id.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds real behavioral context beyond that: abandoned carts are returned by default, filtering/sorting/expansion are supported, and it maps to the backend REST call GET /carts. It does not contradict the annotation. It stops short of rate limits or default page size, which the schema already handles.

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 action and scope, followed by the endpoint mapping. Every clause carries information; there is no filler or repetition of the schema.

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

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

There is no output schema, so the description ideally would hint at the return shape (array of carts, pagination envelope), which it omits. Given the annotations cover the safety profile and the schema fully documents all five parameters, the definition is otherwise complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%: page, limit, sort, where, and expand are each documented with format and examples in the schema itself. The description only summarises them as 'filtering, sorting, and expansion', adding no syntax or constraint detail beyond the structured fields, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (shopping carts) and adds a meaningful scope qualifier: it includes abandoned carts, not just active ones. The resource is distinct from every sibling (products, orders, customers, invoices, etc.), so an agent can select it 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 by naming capabilities (filtering, sorting, expansion) and the underlying GET /carts endpoint, so an agent can infer this is a paginated read. However, it gives no explicit when-to-use/when-not-to-use guidance, and does not distinguish itself from a generic sibling like swell_query that could also retrieve carts.

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

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

readOnlyHint=true already declares the safe-read profile, so the description isn't the sole source of behavior. It adds the backend mapping (GET /categories), which is mild context, but says nothing about pagination behavior, result shape, or defaults beyond what the schema already documents.

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 verb and resource, with the endpoint reference last. Nothing is padded, though the REST endpoint note is marginally useful to an agent that already has the tool name.

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?

All parameters are optional and documented in the schema, and there is no output schema to explain, so the description need not describe return values. It covers the tool's capability surface adequately; the only real omission is guidance on default page size and result ordering, which the schema partially supplies.

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

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

Schema description coverage is 100%, so all six parameters (page, sort, limit, where, expand, search) are already fully documented in the schema. The description only names the capability categories at a high level, adding no syntax or format detail. 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 product categories") and enumerates the supported operations, which separates it from siblings like swell_list_products or swell_list_coupons. It does not, however, distinguish itself from the generic swell_query sibling, which plausibly overlaps.

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 when-to-use or when-not-to-use guidance is given. The agent is not told whether to prefer this over swell_query or swell_list_products, nor that it is the only path to category data. Capability keywords hint at usage but provide no routing logic.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the backend mapping (GET /coupons), which is mildly useful context, but says nothing about pagination defaults, result limits, or response shape beyond what the schema states.

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

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

Two short sentences with the core purpose front-loaded and no filler. The REST endpoint sentence is marginal but harmless and does aid backend-oriented agents.

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

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

For a simple read-only list endpoint with fully documented parameters, no output schema, and safety covered by annotations, the description is sufficient to call the tool correctly. Only richer guidance on filtering/sorting usage would improve it.

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

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

Schema description coverage is 100%: page, sort, limit, and where are each documented with defaults, ranges, and examples. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (list discount coupons) plus the supported operations (filtering and sorting), so an agent immediately knows what it does. It does not need to disambiguate against siblings since no other coupon tool exists in the set, but it also names no alternative, keeping it short of 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?

The description mentions that filtering and sorting are supported but gives no guidance on when to choose this tool over alternatives, nor any prerequisites or exclusions. The only usage signal is implicit in the mention of filter/sort capabilities.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context that customers map to the `accounts` model and that this is a GET /accounts request, but it omits rate limits, pagination defaults, and 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 sentences, front-loaded with the action and immediately followed by the model/endpoint mapping. The capabilities list ('filtering, sorting, search, and expansion') lightly repeats what the schema already shows, but overall it is efficient and has no real 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?

Given the rich schema (100% coverage), readOnlyHint annotation, and no output schema, the description is largely complete for a list tool. It identifies the endpoint and model, though it could say more about return shape or 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 the schema already documents all six parameters with examples. The description only broadly references filtering, sorting, search, and expansion without adding syntax or semantics beyond what the schema provides, which matches the baseline 3.

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

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

States a specific verb and resource ('List customers') and clarifies the underlying Swell model and endpoint ('customers are the `accounts` model — this queries GET /accounts'). It does not explicitly differentiate from close siblings like swell_get_customer or swell_query, so it falls short of 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?

No guidance on when to use this tool versus alternatives such as swell_get_customer for a single record or swell_query for generic querying. The mention of 'filtering, sorting, search, and expansion' implies bulk retrieval but does not state the conditions or exclusions.

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

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

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description adds only the underlying REST endpoint ('GET /invoices'), which is mild context and does not disclose pagination behavior, default limits, or auth needs beyond what the schema covers.

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, purpose front-loaded, no filler. The trailing REST-endpoint reference is somewhat redundant but compact enough not to hurt readability.

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?

A simple read-only list tool with fully documented params and annotations covering safety; an output schema is not needed for a list operation. The description is adequate, though it could note pagination defaults or the subscription-invoice distinction more concretely.

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 all five parameters. The description's mention of 'filtering, sorting, and expansion' loosely maps to where/sort/expand but adds 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 clear verb+resource ('List invoices') and adds the qualifier that these are typically subscription invoices, which helps position it against the swell_list_subscriptions sibling. It stops short of explicitly contrasting with that or any other sibling, so it is clear but not fully differentiated.

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 only implies usage through capability words ('filtering, sorting, and expansion'). It gives no when-to-use condition, no when-not-to-use, and does not route the agent to swell_list_subscriptions, swell_query, or the get_* siblings.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description adds essentially nothing beyond that: no pagination caps beyond the schema, no rate limits, no auth requirements, and no note that it returns a collection with paging metadata.

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 clauses, capability summary front-loaded before the REST endpoint reference. No filler, though the trailing endpoint line adds little decision 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 six-parameter read-only list tool with full schema coverage and no output schema, the description is minimally adequate: the schema carries parameter semantics and the annotation carries safety. However, nothing explains the returned shape/paging behavior or how this relates to sibling query/list tools, leaving 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 description coverage is 100%, so the schema already documents page, sort, limit, where, expand, and search with examples and defaults. The description only echoes the capability names (filtering/sorting/search/expansion) and adds no syntax or constraint detail beyond the schema — the baseline 3 applies.

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

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

States a specific verb (List) and resource (orders) and enumerates the supported capabilities (filtering, sorting, search, expansion). It is clearly distinguishable from get_order/update_order, though it does not differentiate itself from the sibling list_* tools beyond the resource noun.

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 guidance on when to use this versus alternatives like swell_query or swell_get_order, and no mention of prerequisites (auth, workspace scope) or exclusions. The only contextual hint is the raw REST endpoint, which is not usage direction.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the backend REST endpoint mapping (GET /products), which is useful context, but says nothing beyond the schema about pagination defaults or result shape.

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

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

Two tight sentences with the core action and capabilities front-loaded, followed by the relevant endpoint reference. No wasted wording.

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

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

For a read-only list tool with fully documented parameters and annotations covering safety, the description is nearly complete. The only minor gap is lack of any return-shape or pagination hint, which is acceptable given no output schema.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters with examples and defaults. The description naming 'filtering, sorting, search, field selection, and expansion' mirrors the parameters but adds no syntax detail 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 ('List products in the store') and enumerates the supported capabilities. It clearly reads as a collection-list tool distinct from the singular swell_get_product, though it does not explicitly name that sibling distinction.

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 offers no when-to-use or when-not-to-use guidance and names no alternatives among the many list/get siblings. An agent must infer that this is the bulk-retrieval path versus swell_get_product for a single item.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. The description adds that it maps to the Swell REST endpoint GET /subscriptions, but says nothing about pagination defaults, result ordering behavior, or rate limits beyond what the schema already documents.

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

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

Two short sentences with the capability summary front-loaded before the API endpoint detail. Slightly redundant with the title, but nothing wasted and no padding.

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

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

For a five-parameter list tool with no output schema and only a readOnly annotation, the description omits any indication of return shape, pagination semantics, or what a filtered result looks like. The fully documented schema carries most of the load, but the description is thin for a query 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 coverage is 100%, so every parameter (page, sort, limit, where, expand) is already documented with examples in the schema. The description's mention of 'filtering, sorting, and expansion' merely echoes the schema rather than adding syntax or format detail, 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 states a specific verb and resource ('List subscriptions') and adds the three capabilities (filtering, sorting, expansion), so the agent knows exactly what the tool returns. It does not explicitly contrast itself with the sibling swell_get_subscription, though the list/get distinction is inferable from the name.

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 mention of filtering, sorting, and expansion signals that this is the collection-level query endpoint, but there is no explicit when-to-use statement and no named alternative (e.g. swell_get_subscription for a single record). Adequate but leaves 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 cover readOnlyHint=true, and the description reinforces it with 'read-only (GET only)' and adds the underlying REST endpoint GET /{collection}, which is genuine behavioral context. It doesn't discuss rate limits or response shape, but for a read-only passthrough query tool the safety profile is well covered.

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 tightly-packed sentences, front-loaded with the scope and the sibling differentiator, then params, then the REST mapping. 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 generic read-only query passthrough with no output schema and a fully documented input schema, the description provides enough to invoke it correctly. Minor gaps: no mention of how to discover valid collection names or pagination envelope, but nothing critical 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 all eight parameters are already fully documented in the schema including examples and defaults. The description only lists the param names, adding no semantics beyond that. 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+scope: read-only GET access to any Swell model. It explicitly carves out its niche versus the dedicated sibling tools ('not covered by a dedicated tool'), so an agent can distinguish it from swell_list_products, swell_get_order, etc.

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?

Clearly states the context of use ('ANY Swell model not covered by a dedicated tool') and names concrete examples like stock, promotions, giftcards. It doesn't explicitly say when not to use it, but the 'not covered by a dedicated tool' qualifier effectively implies the routing rule.

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 the description reinforces this with 'MUTATES A LIVE ORDER.' It adds genuinely new behavioral context by specifying the update is partial, meaning unspecified attributes are left intact — an important distinction from a full replace that annotations do not convey. It still omits auth requirements, reversibility, and 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?

Three tight sentences, with the destructive warning front-loaded before the mechanics. Every clause carries information: the mutation warning, the semantics of partial update, the call shape, and the underlying endpoint. 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 mutation tool with no output schema and a free-form fields object, the description covers the essentials: mutation risk, partial-update semantics, required inputs, an example, and the backing REST endpoint. It stops short of documenting error behavior or permission requirements, which keeps it just below 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 coverage is 100%, so the baseline is 3, but the description earns more: the `fields` parameter is a free-form object with additionalProperties and no enumerated keys, and the description supplies a concrete example ('{"status":"complete"}') plus candidate attributes (status, fulfillment, notes) that the schema cannot express.

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 ('Partially update an existing order by id') and immediately scopes it with examples of what can change (status, fulfillment, notes). An agent can distinguish this from swell_get_order, swell_list_orders, and swell_update_product 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?

The description tells the agent how to call it ('Provide the id plus a `fields` object of attributes to change') but never states when to prefer this over reading an order first or over other update tools, and gives no prerequisites or exclusions. Usage is implied rather than guided.

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

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

Annotations already declare destructiveHint=true, and the description reinforces this with 'MUTATES LIVE STORE DATA', which usefully emphasizes that the change hits production data. It also clarifies partial-update semantics (unmentioned fields are preserved). It stops short of stating permission requirements, reversibility, or whether unknown attribute keys are rejected.

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

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

Four short clauses, with the most consequential fact (live-data mutation) front-loaded in caps. Every sentence carries information and none 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?

Two required parameters, both fully covered by the schema, and no output schema to explain, so the description needs only the mutation risk, the partial-update semantic, and the endpoint - all present. Minor gap: nothing describes how attribute keys are validated or what an error looks like.

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 already documented in the schema, including the example attribute payload. The description only restates that 'id' and a 'fields' object are needed, adding no syntax or format detail beyond the structured fields. Baseline 3 is correct.

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

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

States a specific verb and resource ('partially update an existing product by id'), and the word 'partially' plus the required 'fields' object distinguishes this from a full replacement or from the create/list/get siblings. An agent can tell it apart from swell_create_product and swell_get_product 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?

The mutation warning and 'provide the id plus a fields object' give practical invocation context, but there is no explicit when-to-use guidance and no alternatives named (e.g., that this is the correct tool for a targeted attribute change versus a full update). Usage is implied rather than stated.

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