swell

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

The description opens with 'MUTATES LIVE STORE DATA', which reinforces the destructiveHint annotation but adds little beyond it. It does explain the field-merging behavior and references the REST endpoint, but it does not disclose irreversibility, required permissions, or consequences beyond mutation. The annotation already covers the destructive nature, so the description adds only marginal behavioral context.

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

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

Two sentences that are information-dense and well-structured. The warning is front-loaded, followed by purpose and usage. No wasted words; every clause contributes to comprehension.

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 schema covers all 8 parameters and the annotation indicates destructiveness, the description completes the picture by naming the endpoint, emphasizing 'name is required', and explaining how to pass extra fields. It does not mention return values, but with no output schema this is not a critical gap. It is sufficient for safe invocation.

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 parameters are fully described. The description adds value by explaining the partition between direct fields and the `fields` object ('anything else goes in `fields`'), which helps agents decide where to place parameters not explicitly listed. This is a useful semantic clarification 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 clearly states 'Create a new product in the store' with a specific verb and resource. It stands out from sibling tools (get/list/update), making its purpose 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?

Provides clear guidance on how to use: 'Provide the common fields directly (name is required); anything else goes in `fields`'. It implies the context (creating new products) but does not explicitly mention alternatives or when not to use it. The sibling list shows update_product for modifications, but the description itself lacks such differentiation.

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

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

Annotations already declare readOnlyHint=true, and the description adds the HTTP method GET and the accounts model mapping, which is useful but not extensively beyond annotations. It does not describe response format or error behavior, but this is a simple read operation.

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 main action, no redundant filler. The mention of endpoint and parameter support is efficient and directly useful.

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 low complexity, the description plus schema provide adequate context: what the tool does, the endpoint, and parameter behavior. Lacking output schema, but a simple resource fetch doesn't require extensive explanation.

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 parameters are documented. The description only says 'Supports expand and fields', which adds no new semantics beyond the schema, justifying the baseline score.

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

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

The description clearly states 'Fetch a single customer (Swell `accounts` model) by id', using a specific verb and resource, and distinguishes from list_customers by focusing on a single record. The endpoint and parameter support reinforce the tool's purpose.

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 single customer id is known, providing clear context. It does not explicitly mention alternatives like list_customers, but the 'by id' qualifier gives sufficient guidance for selection.

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 the REST endpoint and mentions support for expand and fields, but 'Supports expand and fields' merely repeats what the schema already documents. It does not disclose additional behaviors like error handling, response format, or rate limits, so the added value 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?

The description is highly concise: two sentences (three if counting the endpoint) that immediately state the purpose, then mention parameter customization and the underlying API endpoint. No filler or redundancy. Each sentence adds distinct value, and the key information is front-loaded.

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 robust schema annotations and a readOnlyHint, the description adequately covers purpose, input flexibility, and underlying API context. It does not explicitly state the return type or error behavior, but the tool name ('Get an order') and the action ('Fetch a single order') imply the response is the order object. Given the absence of an output schema, a brief note on the return value could be helpful, but it is not a major gap.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description clarifies that 'id' can be an order number or record id (repeating schema) and that expand/fields are supported (also in schema). It adds no new semantic details beyond what the schema provides, keeping the score at the baseline of 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?

The description clearly states the tool's verb and resource: 'Fetch a single order by its record id or its order number.' This distinguishes it from sibling tools like swell_list_orders (multi-order) and swell_update_order (mutation). It also names the REST endpoint (GET /orders/{id}) which adds specificity.

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 'Fetch a single order' establishes a clear context for when to use this tool (when you need one specific order). It doesn't explicitly mention exclusions or alternatives, but the described scope is self-evident. The endpoint and single-order wording imply it is not for listing or updating. Sibling names further clarify the distinction.

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

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

With readOnlyHint already declaring the safety profile, the description adds useful context by specifying the resource locator (id or slug), supported options (expand, fields), and the exact REST endpoint. It does not discuss response format or errors, but for a read-only get operation, this is sufficient extra transparency beyond the annotation.

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 two sentences, each earning its place: the first states the core operation and scope, the second lists supported options and the endpoint. It is front-loaded, concise, and free of 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 simple read-only tool with full parameter schema and a clear endpoint, the description covers the essential usage information. It does not detail the response shape, but the phrase 'Fetch a single product' implies the return value, and the absence of an output schema is compensated by the clear action and REST reference.

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

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

Schema coverage is 100%, with descriptions already explaining 'id or slug,' expand, and fields. The description only restates these parameter categories without adding new semantics, so it stays at the baseline score of 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?

The description uses the specific verb 'fetch' and identifies the resource as 'a single product by its record id or its slug,' clearly distinguishing it from list/create/update product tools. It also references the underlying REST endpoint, further disambiguating the action.

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 'Fetch a single product' makes the primary use case clear, and the sibling tool list shows there is a separate list_products for broader queries. However, it does not explicitly state when to prefer this over list_products or mention any constraints, so it lacks explicit exclusions or alternative 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, so the agent knows it is a safe read. The description adds the REST endpoint and expand support, providing some context beyond the annotation, but does not disclose error behavior or return format. Given the existing readOnlyHint, this is adequate.

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 core action and scope. Every word earns its place, with no fluff or repetition.

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

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

For a simple get-by-id tool with full schema coverage and readOnlyHint annotation, the description is complete enough. It identifies the endpoint and the expand option. No output schema exists, but the description does not need to detail return values for such a straightforward retrieval.

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 'id' and 'expand' fully described. The description mentions 'Supports expand' but adds no new meaning beyond the schema. 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 clearly states 'Fetch a single subscription by id', using a specific verb and resource. This distinguishes it from sibling list tools like swell_list_subscriptions, and the REST endpoint disambiguates the exact operation.

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

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

The description implies usage when a single subscription id is known ('Fetch a single subscription by id') and supports expand. It does not explicitly mention alternatives, but the contrast with list_subscriptions is implicit and clear from the singular focus.

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?

The annotations already declare readOnlyHint=true, so the description needs only to add context beyond that. It adds that abandoned carts are included and that filtering/sorting/expansion are supported, which are useful behavioral details not present in the annotation.

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 two sentences long, with no filler. The first sentence conveys the core functionality, and the second provides a precise API reference. Every word earns its place, and the key information is front-loaded.

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 list tool with five optional parameters and no output schema, the description gives a reasonable overview of scope and capabilities. It lacks explicit return format details, but given the simple resource-oriented nature and the schema coverage, it is complete enough for agent use.

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 fully describes all five parameters. The description's mention of 'filtering, sorting, and expansion' maps to the where, sort, and expand parameters but adds no new meaning beyond what the schema already states.

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

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

The description clearly states the tool lists shopping carts, explicitly including abandoned carts, with filtering, sorting, and expansion. This distinguishes it from sibling list tools that target other resources (orders, products, customers) and from single-resource get tools.

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

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

The description provides clear context that this is for listing carts, including the API endpoint. It does not explicitly mention when not to use it or alternatives like swell_query, but the resource-specific scope and capabilities are evident, giving the agent a solid basis for selection.

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?

The readOnlyHint annotation already covers the safety profile. The description adds the REST API endpoint (GET /categories) and mentions capabilities, but does not disclose additional behavioral traits such as response format, authentication needs, or default pagination beyond what the schema already provides.

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, concise sentence that front-loads the action ('List product categories') and then lists capabilities and the endpoint. Every element earns its place with no redundant 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?

The description is adequate for a simple list operation but omits mention of return values (no output schema) and does not explain any special behaviors or constraints beyond the parameter schema. The complete parameter descriptions help, but some context around expected output or edge cases 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% for all 6 parameters, so the description itself adds no extra semantics beyond what the schema already provides. Baseline of 3 is appropriate since the schema does the heavy lifting.

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 explicitly states the tool lists product categories and lists its capabilities (filtering, sorting, search, expansion). It clearly distinguishes this tool from sibling list tools that target other resources (e.g., products, 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 resource name ('product categories') but the description gives no explicit guidance on when to use this tool versus alternatives, nor any exclusions. It simply states what it does without framing the appropriate context.

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 tool is known to be safe. The description adds the REST API endpoint (GET /coupons), but provides no additional behavioral details such as pagination behavior, default limits, or return format. Given the annotation coverage, this is adequate but not rich.

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 concise sentence that leads with the core action and resource, then adds the REST endpoint. No word is wasted, and all information is relevant.

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 4 optional parameters fully described in the schema and a readOnlyHint annotation, the description covers the essential purpose and context. The mention of the backend REST API adds a useful implementation detail. It does not explain return values, but this is typical for a list tool without 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%, with each parameter individually described. The description's mention of 'filtering and sorting' aligns with the 'where' and 'sort' parameters but adds no new semantic meaning beyond the schema. Baseline of 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 uses a specific verb ('List') and resource ('discount coupons'), clearly distinguishing it from sibling list tools for other resources. It also mentions filtering and sorting, which further clarifies its purpose.

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

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

The description explains that it lists coupons with filtering and sorting, implying when to use it. Since no alternative coupon tool exists among siblings, explicit exclusions are unnecessary. This provides clear context without being overly verbose.

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, lowering the bar. The description adds context that customers map to the accounts model and the endpoint, but it does not disclose behavioral details like pagination defaults, rate limits, or return format beyond what the schema and annotations already convey.

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

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

The description is two concise sentences with no unnecessary words. It front-loads the core purpose and adds a single valuable clarifying detail about the endpoint and capabilities.

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 operation with a fully documented schema and no output schema, the description is sufficient. It provides the endpoint and model mapping, and the parameters are self-explanatory. It could be more complete by describing the return shape or pagination behavior, but it's strong overall.

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 six parameters. The description merely states generic capabilities (filtering, sorting, search, expansion) without adding any syntax or semantics not already present in 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 clearly states it lists customers and explicitly maps to GET /accounts, distinguishing it from the singular get_customer and other list_* sibling tools. The verb 'list' plus the resource 'customers' is specific 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?

It provides clear context by describing the underlying endpoint and capabilities (filtering, sorting, search, expansion), which implies when to use it. However, it does not explicitly name alternatives or state when not to use it, such as pointing to get_customer for a single record.

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?

The annotations declare readOnlyHint=true, covering the safety profile. The description adds that the tool supports filtering, sorting, and expansion, and provides the REST endpoint. It does not disclose return format or pagination behavior, but the schema already covers page/limit parameters. This is adequate but not rich.

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 two sentences: the first states the action and key capabilities, the second provides the API endpoint. It is front-loaded, concise, and every sentence adds value with no redundancy.

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

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

For a list tool with good annotations and detailed schema, the description is sufficient. It clearly states the resource and the main features (filtering, sorting, expansion). While there is no output schema and no explicit return description, 'List invoices' implies a list of invoice objects, and the endpoint reference adds context. It could mention return format, but overall it is fairly complete.

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

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

Schema description coverage is 100%, with each parameter having a description and examples. The description mentions filtering, sorting, and expansion, which maps to where/sort/expand but adds no syntax details beyond the schema. Thus it meets the baseline 3 but does not exceed it.

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

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

The description clearly states the tool lists invoices, with a specific resource (invoices) and a scope hint (typically subscription invoices). It also references the REST API endpoint. It does not explicitly name sibling tools, but the resource is unambiguous, so it partially distinguishes itself.

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

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

No explicit guidance on when to use this tool vs alternatives. It says 'typically subscription invoices' but does not mention when to use this over swell_query or other list tools. There are no exclusions or alternative tool names, leaving the agent to infer usage from the resource name.

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?

The readOnlyHint annotation already declares this as a read-only operation. The description goes beyond by specifying supported behaviors (MongoDB-style filtering, sorting, search, expansion) and the exact REST endpoint, giving the agent a solid sense of operational scope. It doesn't discuss pagination limits or return shape, but these are partially covered by schema parameters.

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 two concise sentences: the first states the core purpose and features, the second provides the REST endpoint context. No filler or redundancy; every sentence contributes useful information and is front-loaded with the tool's main function.

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 listing tool with six optional parameters and no output schema, the description sufficiently conveys the tool's role and capabilities. It doesn't explicitly state the return format (a list of orders), but this is strongly implied by the name and the context. The schema covers parameter details, so overall the description is complete enough for effective selection and invocation.

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?

All six parameters (page, sort, limit, where, expand, search) are already fully documented in the schema, including examples. The description's mention of 'filtering, sorting, search, and expansion' mirrors the parameter names without adding extra semantic depth beyond the schema, so it earns the baseline score for high schema 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?

Clearly states the tool lists orders and describes key features (MongoDB-style filtering, sorting, search, expansion). The resource is explicit ('orders'), distinguishing it from sibling list tools for other resources (e.g., list_carts, list_products). The underlying REST endpoint (GET /orders) adds further specificity.

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 action is clear ('List orders'), so an agent knows when to use this tool: when order listing is needed. However, it doesn't explicitly contrast with alternatives like swell_get_order (for single order retrieval) or swell_query (generic query), so it falls short of full 'when-to-use vs alternatives' 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?

With readOnlyHint=true already provided by annotations, the description adds useful behavioral context by detailing the supported operations (filtering, sorting, search, field selection, expansion) and mentioning the underlying GET /products endpoint, without contradicting the annotation.

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 that conveys the core purpose and key features with no redundant content or unnecessary length.

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 7 parameters, no output schema, and read-only annotation, the description covers all functional dimensions (filtering, sorting, search, field selection, expansion) and references the REST API. It does not mention response format, but the 'list' phrasing implies an array and the schema handles parameter details.

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 reinforces the parameter capabilities at a high level (e.g., MongoDB-style filtering) but does not add meaningful detail beyond what the schema already documents for each parameter.

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

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

The description clearly states the action ('List products') and the resource (products in the store), and enumerates capabilities (MongoDB-style filtering, sorting, search, field selection, expansion) that distinguish it from sibling tools like get_product or list_carts.

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

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

The description implies the use case (when needing to list products) but does not explicitly state when to use it over alternatives such as get_product for a single product, or how it compares to other list_* tools. No exclusions or alternative tool names 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, signaling a safe read operation. The description adds the capability to filter, sort, and expand relations, and mentions the REST endpoint, but does not disclose behavioral traits like pagination limits, default values, or response structure beyond what the schema provides. This is acceptable but not rich additional context.

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

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

The description is a single sentence with zero wasted words. It front-loads the core purpose ('List subscriptions') and includes only essential capability hints and the endpoint reference. Ideal conciseness.

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?

The tool is a straightforward list operation with a complete schema and a read-only annotation. The description mentions filtering, sorting, and expansion, which are the main behaviors an agent needs to know. No output schema exists, but the return value (a list of subscriptions) is implied. It is complete enough for agent invocation, though it could mention that the result is a paginated list.

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 explains all five parameters. The description's mention of 'filtering, sorting, and expansion' maps to the where, sort, and expand parameters, adding a small layer of context but not surpassing the schema's semantics. Baseline 3 is appropriate.

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

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

The description states 'List subscriptions' with a specific verb and resource, and adds capability scope ('filtering, sorting, and expansion'). This clearly distinguishes it from sibling tools like get_subscription (single item) and other list_* tools for different resources.

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

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

The description implies the tool is used to list subscriptions, which is clear from the name and resource. It does not explicitly name alternatives (e.g., get_subscription for a single subscription), but the context of sibling tools provides implicit differentiation. No exclusions or when-not-to-use guidance is given, so it falls slightly short of explicit usage 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?

Beyond the readOnlyHint annotation, the description adds that this is a 'Power tool' with GET-only access, and reveals it can target ANY collection (including payments or shipments), implying potentially sensitive data access. It also specifies the backend REST API path. These are useful behavioral details not present in the annotation, though the core safety trait (read-only) is already declared.

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

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

The description is compact and front-loaded with the core purpose ('Power tool: read-only...'). The two sentences contain only essential information: the fallback role, example collections, parameter list, and API endpoint. No redundant wording or 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?

Given the tool's generality and 8 parameters, the description covers the core context: what it does, when to use it, and the collection/parameter requirements. With no output schema, it doesn't need to describe return values, but it could slightly expand on the nature of results (e.g., that it returns a list of objects). Overall, adequate for a generic fallback 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 input schema provides descriptions for all 8 parameters (100% coverage). The description only lists the parameter names ('limit, page, where, sort, expand, fields, search') without adding new meaning or examples beyond the schema. Baseline of 3 applies since the schema already fully documents the parameters.

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

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

The description clearly states the tool's purpose: 'read-only (GET only) access to ANY Swell model not covered by a dedicated tool' with a concrete verb ('query') and specific resource examples (stock, promotions, giftcards). It also distinguishes itself from sibling tools by explicitly noting it covers models lacking a dedicated tool.

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

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

The description explicitly states when to use this tool: for any Swell model 'not covered by a dedicated tool', naming examples. This implicitly tells the agent to prefer dedicated sibling tools when they exist. It also instructs on required inputs ('Supply the collection name plus the usual list params'), making the usage context clear.

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

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

The description goes beyond the destructiveHint annotation by adding 'MUTATES A LIVE ORDER' in all caps, emphasizing the mutating nature and the 'live' context. It also clarifies partial-update semantics. This provides meaningful behavioral context beyond the annotation, though it does not discuss side effects or permissions.

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 two sentences, front-loaded with the mutation warning, and includes the endpoint and a concrete example without unnecessary words. Every part 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?

For a two-parameter mutation tool with a destructive annotation and clear schema, the description is largely sufficient. It includes the API endpoint and a concrete example, though it does not mention the return value, which is a minor gap given no output schema exists.

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 schema already provides full descriptions for both parameters (id and fields) with 100% coverage, including an example similar to the description. The description adds no significant new parameter semantics, so the baseline of 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 clearly states the tool's function: 'Partially update an existing order by id' with concrete examples (change status, fulfillment, or notes). It distinguishes itself from sibling tools that get/list orders or update products.

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

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

It explains the usage pattern (provide id and a fields object) and gives a use-case example, making it clear when to invoke this tool. It does not explicitly mention alternatives, but no sibling tool offers order-update functionality, so the guidance is adequate.

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 set destructiveHint=true, and the description reinforces this with 'MUTATES LIVE STORE DATA' and 'Partially update'. It adds context about live store data and the partial-update behavior, going beyond the annotation. 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?

Three short, impactful sentences. The warning is front-loaded, then the usage pattern, then the API endpoint for reference. No filler or redundant text.

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

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

For a 2-parameter mutation tool with destructiveHint, the description fully covers the essentials: what it does (partial update), required inputs (id, fields), and the underlying API. Given low complexity and full parameter schema, no significant gaps remain.

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

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

Schema coverage is 100% and both parameters are well-described in the schema (id required; fields with example). The description repeats this guidance but doesn't add new semantic detail beyond what the schema already provides. 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 states a specific verb ('partially update') and resource ('existing product by id'), and includes the API method PUT /products/{id}. This clearly distinguishes it from sibling tools like swell_create_product (create new) and swell_get_product (read).

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

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

The description gives explicit usage guidance: 'Provide the id plus a fields object.' It implies the product must exist and clarifies partial update semantics, though it doesn't explicitly state when to prefer this over create or when not to use it. Sibling context makes the use case clear.

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