CustomCat MCP by usefulapi

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, yet the description still adds substantive behavior the annotations can't express: the production-state refusal rule, the required Write API key, and a mandatory user-confirmation step. The concrete HTTP verb/path also removes ambiguity about what is actually deleted.

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

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

Four short sentences, front-loaded with the write/destructive classification and the operation itself, then preconditions and the endpoint. No filler or restated name/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 one-parameter destructive tool with no output schema and annotations covering the safety profile, the description supplies everything else that matters: failure precondition, credential requirement, confirmation policy, and endpoint. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single order_id parameter is already documented in the schema as "your order id, exactly as sent when the order was placed." The description's "by YOUR order id" reinforces the same point but adds no format, constraint, or sourcing detail beyond the schema, so the baseline of 3 applies.

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

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

Opens with an explicit operation class ("WRITE: cancel (delete)") plus a specific resource and key ("an order by YOUR order id"), and names the underlying endpoint DELETE /order/{order_id}. This clearly separates it from siblings like customcat_create_order and customcat_get_order_status.

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?

States the hard precondition (only orders not yet in production; printed/shipped orders are refused), the auth requirement (Write API key), and a policy instruction ("Confirm with the user first"). An agent knows exactly when invocation will fail and what gate to pass before calling.

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 annotations, it discloses that a real order charges the payment method on file, the front+back $5 per-line-item fee, that sandbox=true only validates, that confirm=true is required for real orders and must follow user confirmation, that duplicate order ids are rejected, and that a Write API key is needed.

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

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

It is front-loaded with 'WRITE' and the charge consequence, then proceeds through sandbox/confirm, id uniqueness, prerequisites, and endpoint. Every sentence carries actionable information; nothing is 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 complex 15-parameter destructive purchase tool with no output schema, the description covers the critical invocation and safety details very well. It could go slightly further by stating what a successful response contains or how payment/stock failures surface, but an agent has enough to call 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?

With only 53% schema description coverage, the description compensates by explaining order_id uniqueness, sandbox vs. real semantics, confirm gating, and how items are composed, while the schema's own nested item descriptions cover the rest. It also directs the agent to the correct sibling tools for SKU and shipping-method values.

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 ('place an order') and adds consequence ('to print and ship'), plus the HTTP endpoint. It is clearly distinguishable from siblings like customcat_cancel_order and customcat_get_order_status.

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 explicitly names prerequisites (check stock with customcat_get_catalog_sku, method with customcat_list_shipping_methods, confirm details with the user), explains when to use sandbox vs. real orders, and states the confirm=true gate. This is an unusually complete routing and timing guide.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context by saying the response bundles colors, sizes and SKUs, but says nothing about behavior for a nonexistent or out-of-range id.

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

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

Two short sentences, front-loaded with the resource and followed by the response contents, with no filler. The trailing GET path partially duplicates what the name already conveys but does helpfully anchor the tool to an endpoint.

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

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

For a single-parameter read tool with rich annotations, the description covers resource scope and response shape adequately. The absence of an output schema means the brief field list (colors, sizes, SKUs) is doing real work, though error behavior remains unstated.

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 integer parameter is documented in the schema, so the baseline is 3. The description's 'numeric id' confirms the type but adds no format, range, or sourcing detail 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?

States a specific retrieval verb ('One catalog product by numeric id') plus the payload it returns (colors, sizes, SKUs), and names the endpoint. It clearly contrasts with list-style siblings like customcat_list_catalog, but does not explicitly distinguish itself from customcat_get_catalog_sku or customcat_get_product.

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 catalog product when you already have its numeric id. There is no statement about when to prefer customcat_get_catalog_sku or customcat_get_product, nor any precondition or error-case guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds the returned fields and the downstream failure consequence of a bad SKU. It says nothing about what happens when the id itself is invalid or unknown (error vs. empty result), which is the one behavioral gap.

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

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

Three short sentences, front-loaded with the result shape then the usage rule. The raw endpoint string is minor weight but does convey the REST path, so it mostly 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 one-parameter read tool with no output schema, the description adequately states what is returned (price, stock status) and why it matters. Only the error/not-found behavior is left unstated.

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 is documented with a numeric example, so the description needn't repeat it. The endpoint template hints the id is a path segment but adds no semantics beyond the schema — baseline 3.

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

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

"One catalog SKU with its price and stock status" names a specific resource and the exact payload, separating it from list_catalog and the product-level tools. It does not explicitly distinguish itself from customcat_get_catalog_product or customcat_get_product, leaving the SKU-vs-product boundary to be inferred from the name.

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

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

"Use it before ordering" gives an explicit trigger and the rationale (out-of-stock, discontinued or invalid SKUs make the order fail). It does not name customcat_create_order as the sibling it pairs with, but the context makes the workflow unambiguous.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by previewing the returned payload (status values, per-item production status, tracking ids), which compensates for the missing output schema. It does not mention error behavior for unknown order ids or any auth requirements.

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

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

Front-loaded with the resource and the returned data, then the sandbox condition, then the endpoint path. Dense but every clause carries information; the trailing 'GET /order/status/{order_id}' is modestly redundant padding but useful for callers reasoning about the underlying API.

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

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

With no output schema, the enumeration of returned fields is precisely what an agent needs to decide this tool answers a status query, and the sandbox flag is explained. Remaining gaps (not-found/error behavior, auth) are minor for a two-parameter read-only lookup.

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

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

Schema coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description merely restates the sandbox behavior already described in the schema and emphasizes 'YOUR order id', adding little syntax or format detail beyond the structured fields.

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

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

States a specific verb+resource ('Status of an order by YOUR order id') and enumerates exactly what is returned: order status enum values, per-item production status, shipments with tracking ids, totals, ship-to address. That scope clearly separates it from the sibling write tools (create_order, cancel_order) and catalog lookups.

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 real usage context: the lookup key must be 'YOUR order id' (the CustomCat-issued id), and 'Set sandbox=true to look up a sandbox test order' distinguishes test from live lookups. It stops short of explicit when-not/alternative routing against siblings such as customcat_cancel_order or create_order, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context by naming exactly which fields come back and which endpoint backs it, but says nothing about auth requirements, error behavior for unknown ids, or latency/rate limits.

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

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

Very short and front-loads the resource and the return payload before the endpoint. The telegraphic fragment style ('One of your CustomCat products by id') costs a little readability, but no sentence is wasted.

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

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

A one-parameter read-only lookup needs little more than this; annotations cover the safety profile and the description enumerates returned fields in lieu of an output schema. Minor gap: no mention of failure mode when the id doesn't exist or belongs to another account.

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 a single required product_id, and the description's example id (22-2580581) merely repeats the schema's own example. Baseline 3 applies since the schema does the heavy lifting and the description adds no validation or format nuance beyond 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?

Names a specific verb+resource (fetch a single product by id) and enumerates the returned payload — variants, SKUs, cost, price, options, designs — plus the endpoint. It implicitly distinguishes 'your' products from catalog products via the sibling set, but never explicitly contrasts with customcat_get_catalog_product or customcat_list_products, and the verb is elided in favor of a noun fragment.

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

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

No statement about when to use this versus list_products (browse) or get_catalog_product (catalog lookup). The only hints are 'by id' and 'your', leaving the agent to infer the selection conditions from the 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description reinforces this with the non-obvious clarification "Read-only quote: it places nothing" and discloses that the underlying call is POST /shipping/{shipping_id}, which usefully prevents an agent from assuming POST means mutation. It does not mention rate limits, currency, or whether the quote expires.

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 zero filler: the purpose and scope lead, followed by the read-only caveat and the prerequisite endpoint reference. Every sentence contributes information an agent needs.

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 four-parameter quote tool whose annotations and schema are fully populated and which has no output schema, the description covers purpose, safety, and the prerequisite lookup. Minor gaps remain: what the returned cost represents (currency, whether it excludes tax/duties) and whether a state is required for non-US destinations.

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 already documented, including the note that shipping_id comes from customcat_list_shipping_methods. The description adds only a general restatement of the inputs (destination, SKUs, quantities) with no format details, defaults, or constraints beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Calculate the shipping cost") plus the exact scope of inputs: one shipping method, a destination, and a list of catalog SKUs with quantities. It is clearly distinguishable from sibling tools, and it explicitly names customcat_list_shipping_methods as the source of shipping_id, separating it from the listing endpoint.

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

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

The description gives clear usage context: this is a read-only quote for pricing a shipment, and shipping_id must come from customcat_list_shipping_methods, which routes the agent to the prerequisite call. It does not state explicit exclusions (e.g., that it does not create an order or that customcat_create_order is the next step), so it falls short of a 5.

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, openWorldHint, and destructiveHint=false, so safety is covered. The description adds that the response carries the total in `total` and cites the underlying endpoint (GET /catalog), which is useful but modest extra context; pagination semantics live in the schema, not the description.

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

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

Three short sentences, front-loaded with what the tool returns and what the items are, then filtering provenance. The trailing 'GET /catalog' is mild filler but doesn't obscure anything.

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

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

With no output schema, the description covers enough to call correctly: what the collection is, how to filter it, where valid filter values come from, and the presence of `total`. It doesn't describe result shape or pagination flow, though the schema's page/limit text covers the latter.

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 four parameters are already documented with defaults, ranges, and enum values. The description only adds that category/subcategory values come from the categories sibling, which is helpful provenance but not detail beyond the schema baseline.

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

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

States a specific verb and resource ('Browse the full CustomCat catalog of printable blank products') and clarifies in parentheses that these are items orderable with your own artwork, which distinguishes it from customcat_get_product and customcat_list_products. An agent can tell what this returns without opening the schema.

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

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

Gives clear context for filtering and explicitly routes the agent to customcat_list_catalog_categories for valid category/subcategory values. It doesn't state when to prefer this over customcat_list_products or get_catalog_product, so the alternative-selection guidance is incomplete.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the underlying endpoint (GET /catalogcategory) and concrete example values (Digisoft, Sublimation, T-Shirts), which help an agent recognize the returned data shape even without an 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?

A single compact sentence with the resource named first and the examples inline. Slightly clipped phrasing ('The CustomCat catalog categories ... and their subcategories ... , to narrow ...') reads a little awkwardly but wastes no words.

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

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

For a simple no-param, read-only listing tool with no output schema, the description covers what is returned (top-level categories and example subcategories) and why. Only a brief note on response structure or typical call sequence 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; this meets the baseline for a no-parameter tool.

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

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

States a specific verb+resource ('CustomCat catalog categories... and their subcategories') and explicitly scopes the tool's role ('to narrow customcat_list_catalog'), distinguishing it from the sibling listing 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 phrase 'to narrow customcat_list_catalog' gives clear usage context and implies this should be called before or alongside the catalog listing. It does not state when not to use it or spell out a full workflow, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing the return fields and the backing endpoint, but says nothing about pagination ceilings, ordering, or auth requirements beyond what the schema states.

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

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

A single front-loaded sentence plus the endpoint; every clause (verb, scope, returned fields) earns its place with no filler.

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

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

With no output schema and all four parameters optional, the description usefully compensates by listing the returned fields. The remaining gap is guidance on filtering/pagination behavior, which is only partially handled by the 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% — page, limit, since_id and updated_since are all documented in the schema, including the 'pass the previous reply's next_page' hint. The description contributes no additional parameter semantics, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the designs uploaded to your CustomCat account') and enumerates the returned fields, plus the underlying endpoint GET /design. It is clearly distinct from the order/catalog/shipping siblings by resource, though it never explicitly contrasts with them.

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 no when-to-use context, no mention of when to apply filters like since_id or updated_since, and no routing to alternative tools. An agent must infer usage entirely from the name and title.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that by enumerating the returned fields (variants, SKUs, cost, price, stock flag, design images) and naming the underlying endpoint GET /product, which matters since no output schema exists.

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

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

Two compact sentences with zero filler. The core purpose and returned data are front-loaded, followed by the actionable ordering hint and the endpoint reference.

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 description covers purpose, returned fields, and the downstream use of the SKUs; pagination semantics live in the schema. It stops short of noting result limits or rate behavior, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100% and all four parameters (page, limit, since_id, updated_since) are documented in the schema with defaults and formats. The description contributes nothing about parameters, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the products you set up in CustomCat') and adds a parenthetical defining a product as 'a design on one or more catalog items', which implicitly separates it from catalog-level siblings like customcat_list_catalog and customcat_get_catalog_product. It never names those siblings explicitly, so the differentiation is inferred rather than stated.

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

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

'Use the variant SKUs when placing an order for these products' gives downstream workflow context, which implies this is the step before customcat_create_order. However, there is no explicit guidance on when to use this list versus customcat_get_product for a single product, and no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are ids and names and that the method name feeds order placement, but says nothing about rate limits, transient data, or what happens with unsupported country codes — the open-world risk the annotation flags.

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

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

Three short sentences with the resource and return shape front-loaded and the downstream requirement placed last where it belongs. The trailing 'GET /shipping' is mild filler but not harmful.

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

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

There is no output schema, so the description carrying 'ids and names' is valuable, but it is only a partial account of the response for an open-world list tool. Nothing an agent needs is dangerously missing, but the definition is thin for a tool with no structured return documentation.

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 country_code pattern and the US default are already fully documented in the schema. The description only says 'for a destination country' and adds no syntax, format, or default detail beyond that.

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 ('shipping methods CustomCat offers') and scopes it to a destination country, plus notes the return shape (ids and names). It does not explicitly distinguish itself from the sibling customcat_get_shipping_cost, 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?

The line 'The method name is required when placing an order' implies the tool is a prerequisite lookup for customcat_create_order, which is useful implied usage. However, there is no explicit guidance on when to use this vs customcat_get_shipping_cost, and no stated alternatives or exclusions.

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