White Automotive & Media Services Catalog

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

With no annotations, the description carries the burden and does substantial work: it discloses the returned fields (search-result fields plus tags, warranty, core charge, dealer-service requirement), states that UCP calls receive structuredContent in UCP shape, and warns that no part number or vehicle-to-part mapping is ever returned. It omits auth requirements and error behavior, keeping it off a 5.

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

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

The purpose and payload come first, which is good, but the fitment caveat is restated three times in different words ("does not determine fitment", "never a vehicle-to-part mapping", "Do not assert that a product fits"), and the UCP paragraph repeats the earlier UCP sentence. Perhaps a third of the text 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 single-record read with no output schema and a nested UCP object, the description supplies the return-field inventory, the dual request shapes, and the critical negative guarantee about fitment, so an agent can call it correctly. It stops short of describing what happens on a missing/invalid SKU.

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 would be 3, but the description adds real routing value by explaining that the same operation has two input forms – a top-level identifier and a UCP-form catalog.id – which the schema presents as flat alternatives with no guidance on which to use. It does not add format or validation detail for identifier 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?

"Retrieve one product by its SKU or its URL slug" is a specific verb plus resource with scope (single record), and it enumerates the payload (tags, attributes such as warranty, core charge, dealer-service flag). It never mentions the sibling tools lookup_catalog or search_catalog, so an agent still has to guess why it would prefer this over a catalog lookup for a single 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?

It gives concrete usage context: accept a SKU/URL slug, pass catalog.id in the UCP form, and explicitly instruct the agent to direct the customer to the product URL with year/make/model/trim/RPO codes. It also states a clear boundary (no fitment resolution). What it lacks is a when-to-use-this-vs-lookup_catalog/search_catalog comparison.

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

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

With no annotations, the description carries the full burden and does so: it discloses that results are never part numbers or vehicle-to-part mappings, that fitment is resolved externally against VIN/RPO codes, that output mirrors search_catalog's summary shape, and that UCP calls return structuredContent in UCP shape. These are exactly the behavioral facts an agent needs to avoid over-claiming fitment.

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?

Purpose and scope are front-loaded, and the UCP variant is deferred to the end where it belongs. The fitment warning is repeated three times in slightly different words ('never a vehicle-to-part mapping', 'Do not assert that a product fits', 'resolved against the VIN'), which is defensible for a safety-critical constraint but is genuine redundancy.

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

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

No output schema exists, yet the description explains the return shape (summary shape matching search_catalog, full detail via get_product, UCP structuredContent) and covers both the native and UCP input forms across all five parameters. Nothing material is missing for correct 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 100%, so 3 is the baseline; the description earns above that by explaining what the slugs actually denote ('category slugs describe GM platforms and applications; tag slugs describe characteristics such as global-a or vin-programmed') and by clarifying that catalog.ids accepts product IDs, SKUs or URL slugs. It does not add anything about limit or the meta profile beyond what the schema already says.

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 a specific verb+resource ('List products within a product category or tag') and immediately disambiguates from both siblings by naming search_catalog for discovery and get_product for full detail. It also scopes the tool's limits (platform/application-level only, no fitment), so an agent knows exactly what class of answer this returns.

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?

Explicitly states the prerequisite workflow ('Use search_catalog first to discover which categories and tags exist'), the escalation path ('call get_product for full detail'), and the alternative form ('In the UCP form, look up by catalog.ids instead'). It also gives a clear when-not-to-use rule: do not use this to determine or assert vehicle fitment.

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

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

With no annotations, the description carries the burden well: it discloses the shape of returned summaries, the fitment limitation and the reason for it (VIN/option-code resolution), and that UCP-shaped calls return structuredContent rather than the default shape. It does not mention pagination behavior or result caps beyond the schema's limit maximum.

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 purpose, examples and return shape, then constraints. The fitment disclaimer spans three sentences and partially restates itself ('does not determine fitment' / 'never a vehicle-to-part mapping' / 'do not assert that a product fits'), which is a small amount of redundancy, though it does serve agent-safety guidance.

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 search tool with no output schema and a nested dual-shape input, the description supplies return fields, the UCP form, and the critical fitment caveat. Pagination/cursor semantics are left entirely to the schema, a minor gap given the tool can return up to 20 results.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by explaining the dual invocation shape — the UCP variant takes inputs under "catalog" with optional "meta" — which the schema alone does not make obvious to an agent choosing between the two forms.

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 (search products) with three concrete example queries, and names what is returned per match (name, SKU, price, availability, categories, description, URL). It also explicitly differentiates from the sibling get_product, which handles full item detail.

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 explicit routing: use this for discovery, call get_product for full detail. It adds a strong negative constraint (this endpoint does not determine fitment) and a concrete alternative workflow (direct the customer to the product URL with year/make/model/trim/RPO codes).

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