catalog

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses meaningful behavior: dates are business days from today in Central time, the standard estimate includes proof/production/transit, rush skips the proof wait, and rush starts same business day only when artwork arrives before noon Central. This goes well beyond the structured 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?

The description is three sentences with no filler. It front-loads the main outcome, then covers shipping-lane input, date calculation basis, and the rush rule efficiently.

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?

Even without an output schema, the description tells the agent what the call returns (standard date and rush date, if offered), how dates are calculated, what is included, and the cutoff behavior. Combined with the fully documented input schema, an agent has enough to invoke the tool 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%, so the schema already documents both parameters thoroughly. The description adds minor context about using the destination state for a real shipping lane and assuming typical US transit when omitted, but it does not materially change or expand parameter understanding.

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

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

The description clearly states the tool estimates when an order placed today would arrive, returning both the standard FedEx Ground date and the rush date when available. This is a specific verb-resource pairing (estimate + delivery dates) that distinguishes it from sibling tools like quote_price, search_catalog, and 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?

The description gives clear context: use this when you need delivery dates for an order placed today, and provide the buyer's US state for a more accurate shipping lane. It also explains what happens if the state is omitted. However, it does not explicitly name alternatives or state when not to use this tool, so it stops 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, idempotentHint, and destructiveHint=false, so the description does not need to cover side effects. It adds output semantics but no extra behavioral caveats such as empty results for non-imprintable products or rate limits. There is no contradiction with 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?

The description is one long, dense sentence, but it is front-loaded with the core purpose and each clause contributes a distinct piece of information. It is efficient, though breaking the enumeration into a list would improve scannability.

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

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

There is no output schema, so the description must carry the return-value burden. It does so thoroughly, covering imprint methods, quantity ranges, setup charges, run charges, locations, sizes, color limits, and usage guidance. An agent has enough context to call the tool and interpret the result.

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 product parameter is fully documented, including the exactly-one-of guidance for slug, id, or sku. The description adds no parameter-specific meaning, but it does not need to because the schema already carries the burden.

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 identifies a specific resource — decoration/imprint options for a product — and then enumerates the exact data returned: quantities, setup charges, run charges, locations, sizes, color limits, and usage guidance. This clearly separates it from siblings like get_product_options and search_catalog.

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 when to use the tool: whenever an agent needs to know how a product can be decorated. However, it does not explicitly state conditions, exclusions, or alternatives, so an agent receives no direct routing guidance versus sibling tools.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by scoping the returned content, but it does not disclose additional behavioral details such as pagination, auth requirements, or error conditions—though none are strongly needed for a read-only lookup.

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 convey the return scope and the key alternative without fluff. The long field list is purposeful and front-loaded before the cross-reference to quote_price.

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 compensates by listing the major fields of the full record and directing price-specific queries elsewhere. Combined with the schema's identifier guidance, an agent has what it needs to call the tool 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%: each of id, sku, and slug has a clear description and the object-level 'exactly one' constraint is stated in the schema. The tool description itself adds no parameter semantics, so the baseline 3 applies.

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

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

The description identifies the tool's purpose as returning the full UCP product record and enumerates its contents, which clearly distinguishes it from quote_price (price at a specific quantity) and the options-focused siblings. The title 'Get a product' reinforces the resource being retrieved.

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

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

The description explicitly routes price-at-quantity requests to quote_price, giving one clear when-not/alternative signal. It does not discuss other siblings such as get_product_options, but the 'full product record' framing provides enough context for basic 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 establish read-only, idempotent, non-destructive behavior. The description adds useful conditional details beyond annotations, such as stock being reported 'when tracked' and the free-sample link appearing 'when the product qualifies', giving the agent accurate expectations about conditional response fields.

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

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

The description is a single sentence that packs a lot of specific information efficiently and front-loads the core purpose. It is slightly dense with a long comma-separated list, but every item adds value and there is no filler.

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

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

With no output schema, the description takes on the burden of explaining return contents, and it does so in substantial detail: colors, sizes, pricing ladders, stock, shipping, lead time, and free-sample eligibility. Combined with the fully documented input schema, an agent has enough context to call the tool 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%, with the product object's slug/id/sku fields clearly documented in the input schema. The tool description does not need to restate parameter details and adds no new parameter-specific meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the resource (product options) and the exact content returned: colors with hex values, size-based quantity price ladders, stock levels, free-shipping status, lead time, rush availability, and free-sample link. This is specific and distinct from sibling tools like get_imprint_options or quote_price, which concern different resources or purposes.

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 'The choices before a quote' gives clear contextual guidance: this tool is for retrieving product options needed when preparing a quote. It does not explicitly name alternative tools or state when not to use it, but the scope is unambiguous enough for an agent to select it appropriately.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that results are full UCP records obtained in one call, which is useful, but it does not go deeper into error handling, idempotency edge cases, or any limitations beyond the schema's maxItems.

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 with no filler. The core capability and constraint are front-loaded, and the sibling pointer is a separate, easy-to-parse clause. Every word 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 single-parameter lookup tool with full schema coverage and comprehensive annotations, the description is nearly complete. It defines the return payload as 'Full UCP product records' and gives the single-product alternative. It is slightly opaque about 'UCP' and error behavior for invalid ids, but these are minor gaps 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?

Schema description coverage is 100%: the single 'ids' parameter is fully documented as product ids or handles with min/max items. The description only repeats 'by id or handle' and 'up to 6', adding no new semantic value 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 (look up), resource (Full UCP product records), and scope (up to 6 products by id or handle in one call). It explicitly names get_product as the single-product alternative, so it is clearly distinguished from siblings.

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

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

The description provides an explicit routing rule: use lookup_catalog for batch lookups up to 6 products, and get_product when you need one. This gives the agent a clear decision criterion without needing to inspect other tool definitions.

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 mark the tool read-only and idempotent, and the description adds meaningful behavioral detail: it excludes shipping and tax ('subtotal before shipping and tax'), reports orderability and the next price break, and states that the deep_link preserves the same configured total. There are no side effects or contradictions.

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 definition is a single dense sentence that is front-loaded with the core action and then lists the returned fields and optional inputs. It contains no filler, though the long list makes it slightly heavy; still, the structure is efficient and readable.

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

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

Since there is no output schema, the description compensates by enumerating the key result fields and the key exclusion of shipping and tax. The remaining gaps, such as the exact-one product identifier requirement and sizes replacing quantity, are already covered by the input schema, so the overall documentation is sufficiently complete for invocation.

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

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

Schema coverage is 86%, and most parameters already carry useful descriptions, such as color being 'from get_product_options' and product being identified by exactly one of slug, id, or sku. The description repeats that these inputs are optional but adds little semantic detail beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description names the exact action, 'Price an order of a given quantity,' and enumerates the returned price components: per-unit price, setup, run charges, rush and tariff, subtotal, orderability, next price break, and deep_link. This clearly distinguishes it from sibling catalog/option/delivery tools because it is specifically about pricing a configured order.

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 when to use the tool—once a product and quantity are known—and lets the caller optionally specify color, decoration method, imprint colors, per-size quantities, and rush. However, it never explicitly says to prefer this over estimate_delivery or to first call get_product_options/get_imprint_options for valid option values, so the usage guidance is implicit rather than explicit.

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 readOnly/idempotent annotations, the description discloses ranking behavior, the browse mode when query is omitted, returned product summaries with from-price, and the no-match behavior exposing facets.categories and notes. This gives an agent a clear picture of what to expect from the call.

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

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

The description is compact and front-loaded, with the main action and examples first, followed by ranking, browse behavior, and fallback behavior. Every sentence adds operational value and none are redundant with 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?

Given no output schema, the description adequately explains what is returned: product summaries, a from-price, and a handle for downstream tools. It also covers ranking, browser-style usage, and no-match fallback, which is sufficient for an agent to select and invoke the tool 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 56% schema coverage, the description compensates by explaining how query, category, color, size, and price filters interact, and how sort relates to relevance/price. It also clarifies the important query-omission browsing behavior. Page and page_size are not elaborated, but the core semantic choices are well covered.

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

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

The description clearly states the tool finds branded merchandise by keywords with optional filters, and explains the returned handle is meant for get_product or quote_price. This is a specific verb+resource and conveys what the tool does, though it does not explicitly contrast itself with sibling lookup_catalog.

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 concrete guidance: omit query with a category to browse, use category facets when nothing matches, and pass the returned handle to get_product or quote_price. It provides useful context and a fallback path, though it does not formally list exclusions or sibling alternatives.

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