Twice Commerce MCP by usefulapi

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

Annotations only carry destructiveHint=true, which alone is thin for a write tool. The description compensates by disclosing the required write scope and, importantly, that each invocation appends a new comment rather than upserting, which is a real side-effect trait not expressed in annotations.

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

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

Three compact clauses, front-loaded with the WRITE marker and operation, followed by the auth requirement, the idempotency caveat, and the endpoint. No filler or repetition of the title.

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

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

For a two-parameter append operation with no output schema, the description covers auth, side effects, and transport endpoint. The only gap is what the call returns (new comment id / created object), which an agent might want for follow-up, but that is minor.

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

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

Schema description coverage is 100%, so order_id (uuid) and content (1-5000 chars) are already fully documented in structured form. The description adds only the path-parameter framing via the endpoint; it offers no extra semantics such as whether content supports markdown or is sanitized.

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 (add a comment to an order) plus the underlying Admin API endpoint POST /v1/admin/orders/{orderId}/comments. The 'WRITE:' prefix immediately separates it from the otherwise read-only sibling set (get_order, list_orders, 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?

Gives a concrete prerequisite (a key with Write access to Order details) and a non-idempotency warning ('do not repeat a call that succeeded'), which is exactly the guidance an agent needs before retrying. It stops short of naming an alternative or exclusion, though no sibling offers comment creation, so little is missing.

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 underlying endpoint (GET /v1/admin/availability/{catalogItemId}/period) and reinforces the pre-order timing, but never says what a 'check' returns — a boolean, a set of bookable slots, or per-location detail — which is the key unknown for an agent, especially with no output schema.

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

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

Two sentences plus the endpoint reference, front-loaded with the purpose and the timing caveat, with no filler. Every clause carries information an agent does not already get from the schema or annotations.

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 predicate tool this is close, and the pre-order guidance plus the endpoint are useful. Missing is any indication of the result shape or how partial availability is expressed, which matters because there is no output schema to fall back on.

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 four parameters are documented in the schema itself; the description only echoes the ISO 8601 UTC format and the single-item constraint. It adds no semantics for location_ids, such as whether omitting it checks all locations.

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?

Uses a specific verb and resource ('check whether one catalog item can be booked for a date-time window') and scopes it to a single item, which distinguishes it from the list_* siblings that return collections. The parenthetical '(before you create an order)' pins the intent further.

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

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

The phrase 'before you create an order' gives a clear workflow trigger for calling this tool. It does not name an alternative or state exclusions, but no sibling tool offers comparable availability checking, so there is little to route away from.

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 safety is covered. The description adds value beyond that by disclosing the returned fields and the underlying Admin API route (GET /v1/admin/catalog/{id}), which helps an agent anticipate the response shape given there is no output schema.

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

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

Two tight clauses: purpose and returned fields first, endpoint second. Every element earns its place with no repetition of the name or title.

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

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

For a read-only single-parameter fetch with no output schema, the description covers what the call returns and the endpoint context. Minor gap: it does not state error behavior for an unknown id or whether variants/links are inlined versus summarized.

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?

Single parameter with 100% schema description coverage, so the schema already explains the id and where to get it. The description only restates 'by id' and adds no format, prefix, or validity details 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 and resource ('Get one catalog item by id') and enumerates the payload ('name, status, variants, rules and pricing links'). The singular 'one ... by id' implicitly separates it from twicecommerce_list_catalog_items, but it does not explicitly name or contrast with related siblings like get_sku or get_stock_item.

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: you have an id and want the item. There is no explicit when-to-use / when-not, and the guidance about sourcing the id from twicecommerce_list_catalog_items lives in the schema parameter description rather than the tool description. No prerequisites or alternatives are mentioned.

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 read-only profile, so the description only needs to add context — and it does, by disclosing the returned fields and the underlying Admin API route (GET /v1/admin/customers/{customerId}), which signals the admin scope/permissions involved. No error or not-found behavior is mentioned.

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, zero filler, with the purpose front-loaded and the API detail placed after it as supporting context.

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

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

There is no output schema, so the description's enumeration of returned fields (contact details, addresses, type) is the only signal about the response shape, and it is sufficient for a one-parameter getter. Minor gap: no not-found or auth-failure behavior for the admin 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% and the customer_id property already documents that it is a uuid sourced from twicecommerce_list_customers. The description's "by id" adds nothing beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ("Get one customer by id") and enumerates the payload (contact details, addresses, type). The word "one" implicitly separates it from twicecommerce_list_customers, but no sibling is named explicitly.

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

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

Usage is only implied: fetch a single record when you already have the id. There is no statement about when to prefer list_customers or get_customer_orders instead, and no prerequisites are called out.

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 covers the safety profile, and the description adds the underlying Admin API route (GET /v1/admin/customers/{customerId}/orders). It does not disclose pagination, ordering, or result limits, which matter for a list endpoint.

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 purpose front-loaded and the endpoint reference trailing as secondary detail. Nothing is redundant.

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

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

For a one-parameter read-only list tool with full schema coverage and a safety annotation, the description is close to sufficient. The remaining gap is pagination/result-size behavior, which the description leaves to the API route rather than stating directly.

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 the single customer_id parameter, so the schema carries the load. The description adds no format hints (e.g. UUID vs. legacy id) beyond restating that it targets one customer.

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

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

States a specific verb and resource ('List the orders') scoped to 'one customer', which implicitly separates it from the sibling twicecommerce_list_orders and twicecommerce_get_order. It stops short of naming the alternatives explicitly, 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?

Usage is only implied by the phrase 'of one customer' — an agent can infer this is the per-customer variant, but there is no explicit when-to-use, when-not-to-use, or named alternative such as list_orders for cross-customer queries.

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, so the description's burden is reduced. The helpful addition is the "Admin API: GET /v1/admin/merchant" note, which hints at the underlying access level. It discloses nothing further about response shape or errors, which is acceptable given the annotations cover the safety profile.

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

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

Two tight sentences: the payload fields come first, then the usage cue and endpoint reference. No filler, nothing an agent would have to skim past.

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

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

For a no-argument read of a single object with no output schema, the description lists what comes back and how to invoke it. An agent has everything needed to call it correctly without further context.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing parameter-related for the description to explain. The description correctly signals the caller needs no arguments, matching the baseline for zero-param tools.

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

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

Specific verb+resource ("Get the merchant account") followed by an enumeration of the fields returned (name, country, currency, timezone, languages, plan, enabled features). This clearly separates it from siblings like twicecommerce_get_customer or twicecommerce_get_order, which target 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?

"Good first call" gives the agent a concrete routing cue for when to reach for this tool, and the account-level scope implicitly excludes per-record lookups. It stops short of explicitly naming an alternative or a when-not condition, so it falls just under the top mark.

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 this a safe read, so the bar is lower. The description adds that this is the Admin API surface and what data categories are returned, but says nothing about auth/permission requirements or what happens for a missing order id. Adequate, 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?

One front-loaded sentence names the operation, the identifier, and the returned field groups, followed by the concrete 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?

With no output schema, the field enumeration is what makes the return value predictable, and the API path grounds it. The only real gap is the absence of any error/not-found behavior, which for a single-resource read is a minor omission.

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 single parameter is fully documented in the schema (uuid, sourced from twicecommerce_list_orders), so the baseline of 3 applies. The description only restates 'by id' and adds no format, validation, or lookup-path detail beyond the schema.

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

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

States a specific verb and resource ('Get one order by id') and enumerates the payload fields (status, customers, line items, stock items, comments, totals and pricing), so an agent knows exactly what comes back. It does not explicitly distinguish itself from near siblings like twicecommerce_get_customer_orders or twicecommerce_get_order_invoices, keeping it just 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?

Usage is only implied: the description names the Admin API path and the enclosing schema note points to twicecommerce_list_orders as the id source, which hints at the list-then-get workflow. There is no explicit statement of when to prefer this tool over the sibling order/payment/invoice getters.

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 already establishes that this is a safe read operation. The description adds useful behavioral context beyond annotations, specifically the Payments-area key requirement and the optional inclusion of upcoming scheduled subscription invoices, though it does not describe pagination or return format.

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, stating the core operation first, then the optional behavior, prerequisite, and endpoint. Every element adds useful information without 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 two-parameter read-only list operation with complete schema descriptions and a readOnly annotation, the description gives enough context to select and invoke the tool. It could be richer about return shape or pagination since no output schema exists, but the essential context is present.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaning by explaining that include_scheduled relates to upcoming subscription invoices and that this option requires a Payments-area key, which is not 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 states a specific verb and resource: 'List the invoices of one order.' It also clarifies the optional scope for scheduled subscription invoices and gives the exact Admin API endpoint, letting an agent distinguish this from payment-history tools such as get_order_payments.

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 usage context for listing invoices tied to a single order and notes the Payments-area key prerequisite for scheduled invoices. It does not explicitly name alternatives or when not to use this tool, so it falls short of full when/when-not 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?

The description adds meaningful context beyond the readOnlyHint annotation by disclosing the authorization requirement ('needs a key with the Payments area') and the underlying Admin API endpoint. It does not describe return shape or pagination, but the auth prerequisite is a useful behavioral detail.

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

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

Front-loads the purpose and follows with the permission and endpoint details. It is compact with little waste, though the endpoint reference is somewhat secondary for an agent that does not call HTTP directly.

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-parameter read tool with full schema coverage and a readOnlyHint annotation, the description supplies the key missing context: the Payments-area permission requirement. No output schema exists, but the return type is sufficiently implied and an agent can 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%, and the sole parameter is already documented as the order uuid. The description reinforces that the parameter identifies one order but adds no syntax or format details beyond the schema, so 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?

States a specific verb and resource: listing payment transactions for one order. It is clear what the tool returns, though it does not explicitly distinguish itself from nearby siblings like get_order or get_order_invoices.

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 implied use case is clear from 'payment transactions of one order', but there are no explicit when-to-use or when-not-to-use instructions, and no sibling alternative is named.

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

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

readOnlyHint=true already declares the safe read profile. The description adds the underlying endpoint path (GET /v1/admin/skus/{skuId}), but says nothing about not-found/error behavior or return 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 short sentences, front-loaded with the action and backed by the endpoint, with zero 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 annotated read with a fully documented single parameter and no output schema, the description is sufficient to invoke correctly, though it omits error/return 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 coverage is 100%, so the sku_id uuid and its provenance are already documented. The description only restates 'by id' and the path template, adding nothing beyond the schema.

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

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

States a specific verb (get) and resource (SKU) scoped to a single id. It does not explicitly contrast with twicecommerce_list_skus, but the singular 'one SKU by id' implicitly distinguishes 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?

Implies a single-record lookup and the schema notes the id comes from twicecommerce_list_skus, but the description itself gives no explicit when-to-use or when-not (e.g., use list_skus to browse).

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 safety profile, so the description's added value is the disclosure of which fields come back and the underlying Admin API route (GET /v1/admin/articles/{id}), which helps an agent correlate this with the REST surface. It stops short of noting error behavior for a missing/invalid id, which matters for a lookup tool with no output schema.

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

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

One sentence for purpose and return fields, then the endpoint as a compact trailing detail. Front-loaded and free of 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?

No output schema exists, and the field enumeration compensates by telling the agent what a successful response contains. The only gap is the absence of anything about failure modes or whether the item is workspace-scoped, which is minor for a one-parameter read.

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

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

Schema coverage is 100% and the single parameter's description already says it comes from twicecommerce_list_stock_items. The description's 'by id' adds nothing beyond the field name, 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?

Specific verb and resource ('Get one stock item by id') plus an enumeration of the fields returned (SKU, condition, quantity, location, status). The singular 'one' implicitly separates it from twicecommerce_list_stock_items, but no sibling is named explicitly.

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

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

Usage is only implied: fetch a single stock item when you have an id. There is no statement of when to prefer this over list_stock_items, get_sku, or check_availability, all of which are adjacent in the toolset.

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, so the description only needs to add context; it contributes the underlying endpoint (GET /v1/admin/catalog/), which signals the admin scope. It does not mention default page size behavior, what the response envelope looks like, or whether results are scoped to the merchant.

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

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

A single sentence plus the endpoint reference; purpose, scope and available filters are front-loaded with no filler. Nothing 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 five-parameter, all-optional read-only listing tool with no output schema, this covers what an agent needs to invoke it correctly. The main remaining gap is sort_by, which has no description anywhere, but the enum values are self-explanatory enough to keep this from being a blocker.

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 80%, so the parameters are largely self-documenting and a baseline of 3 applies. The description only echoes the name search and paging that the schema already documents in more detail, and adds nothing for sort_by/sort_direction or for the substring-match semantics of name.

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 catalog items') and then defines the resource in domain terms ('the listings customers rent, buy or subscribe to'), which removes ambiguity for an agent unfamiliar with the platform's vocabulary. The 'list' vs sibling 'get_catalog_item' split is clear from the verb alone.

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

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

The description implies browsing/name-search usage and says the name filter is optional, but it never states when to prefer this over twicecommerce_get_catalog_item (which presumably fetches a single item by id) or when a search is warranted versus a plain page-through. Usage is inferable but not spelled out.

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 this is a safe read, so the description's main added value is that search is a contains match across name and email and results are paged. It says nothing about result ordering or return shape, and it silently omits the sort capability that the tool actually offers.

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

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

A single tight sentence with the core purpose front-loaded and the qualifiers (search, paging, endpoint) trailing. Nothing is padded or redundant.

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

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

For a read-only list tool with no output schema, the agent still lacks basics such as whether a total count or cursor is returned, the default ordering, and the presence of sorting. The endpoint hint is useful but does not substitute for that missing operational context.

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

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

Schema coverage is 80%, so the baseline is 3. The description adds real meaning for `search` (which fields it matches, contains semantics) beyond the bare 'Text to search for', but sort_by and sort_direction go unmentioned, leaving those to the bare enum.

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') plus the two notable capabilities, search and paging, so an agent knows exactly what operation this performs. It is distinguishable from the get_customer sibling by the plural/list framing, though it never names that sibling explicitly.

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

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

Usage is only implied: 'optional text search over name and email' hints that this is for browsing or finding customers, but there is no statement of when to prefer this over twicecommerce_get_customer (single lookup) or how to page through large result sets. No exclusions or alternatives 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, so safety is covered; the description adds that results include usage and validity data and are paginated, plus the admin API surface, which is useful context. It doesn't disclose admin permission requirements, default/max page behavior beyond the schema, or ordering of results, so it adds moderate value only.

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, no repetition, resource and scope front-loaded followed by the API endpoint as supporting reference. Every clause carries information.

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

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

For a zero-required-parameter read-only list with fully documented params and no output schema, the description covers what the tool returns at a high level, paging behavior, and the admin endpoint. Only the shape of returned fields and search matching semantics are left implicit, which is a minor 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% — page, size, and search are all documented in the schema, including defaults and max. The description's 'with paging' merely echoes the schema and it says nothing about what 'search' matches against, 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 discount codes') and adds scope detail ('with usage and validity, with paging'), which tells the agent what data comes back. Siblings are all distinct resources, so no explicit differentiation is required, but it stops short of a 5 because it doesn't distinguish this list from any filtered variant.

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

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

The 'Admin API: GET /v1/admin/discount-codes' note implies this is an admin-scoped read and the paging hint suggests the iterative listing pattern, but there is no explicit when-to-use or when-not-to-use guidance or named alternative. 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?

Beyond readOnlyHint=true, the description discloses a critical behavioral trait the annotations cannot convey: the API does not paginate, results are truncated to `limit` rows (newest as returned), and the untruncated count is exposed as totalCount. This prevents an agent from mistaking a partial list for the full set.

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: what is returned, the truncation caveat, and the filter/endpoint. The most decision-relevant fact (no pagination) is front-loaded in the second sentence, and nothing is redundant.

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

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

With only two optional params, full schema coverage, a read-only annotation, and no output schema, the description covers what an agent needs: returned fields, truncation semantics, totalCount, filtering, and the endpoint. Nothing material is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description exceeds it by explaining the consequence of `limit` (hard truncation rather than paging, with the true count in totalCount) and framing location_ids as a narrowing filter. The precise syntax of location_ids is still left to 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 plus the fields returned ('List orders with status, customers, line items, totals and dates') and names the backing endpoint GET /v1/admin/orders. It does not, however, distinguish itself from siblings like get_order or get_customer_orders, so an agent must infer that this is the unfiltered/unscoped list variant.

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

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

Offers narrow-scope advice ('Narrow it with location_ids') and explains the limit behavior, which implies when to use it for bulk retrieval. But there is no explicit guidance on when to prefer get_order (single order) or get_customer_orders (per-customer), so the routing decision against siblings is left implicit.

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 the underlying Admin API endpoint (GET /v1/admin/service-locations/) which is modest extra context. Return shape and pagination behavior are not described.

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

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

Two short sentences with no waste; the purpose and the practical use of the ids are both 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 read-only, one-parameter list tool with a fully documented schema, the description covers purpose, downstream use and endpoint. Only minor gaps remain around what fields the returned locations contain.

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

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

Schema description coverage is 100% and the single 'scope' enum is fully documented in the schema, including the default. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List pickup and return locations (service locations)') and clarifies the downstream use of the returned ids. It is distinguishable from the many list_* siblings by domain, though it never names a sibling to contrast with.

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

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

'Use the ids to filter orders and stock items' implies downstream context, but there is no explicit when-to-use guidance or statement of when another tool (e.g. get_stock_item) is preferable.

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 pagination behavior and the underlying admin endpoint (GET /v1/admin/skus), which is useful context but no return-format detail.

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

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

One tight sentence plus endpoint reference, front-loaded with the definition and paging behavior. Every element earns its place with no filler.

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

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

For a zero-required-parameter paged list with no output schema, the description plus schema covers what an agent needs to call it. Return shape and default ordering remain unstated but are minor gaps.

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 page and size fully documented including defaults and max. The description's 'with paging' merely restates this, 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 (List) and resource (SKUs), and usefully glosses SKU as 'the product definitions that stock items belong to'. It distinguishes itself from twicecommerce_get_sku via the list-vs-get verb, though it never names that sibling explicitly.

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

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

Usage is only implied by 'List' and the paging mention – there is no statement of when to prefer this over get_sku or list_stock_items, and no prerequisites given. Adequate but leaves the agent to infer 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 useful context beyond that: pagination behavior, the location-scoping constraint, and the 'Admin API' label implying admin-level auth. It still says nothing about default page size behavior beyond what the schema states or about ordering/return 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?

Three short clauses, front-loaded with the core action and followed by the terminology clarification, the filtering hint, and the endpoint. Nothing is padded, though the endpoint reference is marginal for an agent that already has tool routing.

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 three-optional-parameter read-only list tool with full schema coverage and no output schema, the description covers purpose, paging, and filtering adequately. It leaves return-item shape undescribed, which is a minor gap given there is 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 coverage is 100%, with each parameter (page, size, location_ids) fully documented including defaults and max. The description's 'with paging' and 'narrow by location ids' merely echo that, adding no syntax or format detail, so baseline 3 applies.

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

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

The description states a specific verb and resource ('List stock items') and disambiguates the domain term by noting these are the physical units the API calls 'articles', plus the underlying endpoint. It does not explicitly contrast itself with nearby siblings such as get_stock_item or list_skus, 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?

It says to 'narrow by location ids', which implies the supported filtering scenario, but gives no when-to-use versus alternatives (e.g., prefer get_stock_item for a single unit, or list_skus for SKU-level data). Usage is implied rather than prescribed.

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

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

readOnlyHint=true already declares the safe-read nature, and the description adds only the underlying endpoint path, which is of little value to an agent. For a list operation it says nothing about pagination, result limits, or whether all tags are returned regardless of scope.

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 purpose, with zero redundant or filler content.

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-enum read tool with annotations covering safety and no output schema, the description supplies enough to invoke correctly. The only meaningful omission is pagination/completeness of results, which is minor at this complexity.

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

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

Schema coverage is 100% and the single parameter has an enum with its own description, so the schema fully carries parameter meaning. The description merely restates the same four scope values without adding format or behavior detail, making baseline 3 appropriate.

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

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

States a specific verb and resource ('List tags') and enumerates the four scopes (inventory, catalog, customers, orders), matching the enum exactly. It's clearly distinct from the siblings, none of which list tags, though it doesn't explicitly note that 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 intended usage is implied — supply a scope to retrieve that area's tags — but there is no explicit guidance on when to reach for this versus, say, list_catalog_items and then extracting tags, and no stated prerequisites (e.g., admin authorization) despite referencing an admin endpoint.

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, so the description only needs to add context. It adds the GET endpoint path, which corroborates read-only behavior but is largely redundant; it says nothing about pagination, result volume, or whether taxes are merchant-scoped vs global beyond the phrase "set up for the merchant".

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 purpose, with the endpoint as secondary detail. Nothing wasted and nothing buried.

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

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

For a zero-parameter, read-only list tool this is close to sufficient. The only gap is that with no output schema, the description doesn't hint at what the returned tax-rate objects contain or whether the list is paginated — a small omission given the tool's simplicity.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering or pagination inputs are required, consistent with the empty schema.

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

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

States a specific verb and resource ("List the tax rates set up for the merchant"), which is unambiguous and clearly distinct from the other list_* siblings by resource. The API endpoint reinforces the resource mapping. It stops just short of a 5 because it does no explicit sibling routing, though none is really needed here.

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

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

Usage is only implied — an agent can infer it should call this when it needs merchant tax rates, but there is no stated when/when-not, no prerequisites, and no mention of alternatives (e.g., fetching a single tax rate). Minimum viable guidance.

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