zara_product

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

With no annotations present, the description carries the full burden of disclosure, and it does so reasonably well: it tells the agent exactly what the response contains (color variants, real marketing descriptions, per-size inventory, image galleries) and documents an error case ('unrecognized productId returns 404'). It doesn't cover auth, rate limits, or pagination, but for a single-id lookup tool with no output schema, the behavior is disclosed well enough for safe invocation.

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?

At roughly two sentences, the definition is brief and front-loaded with the core action and output composition. There is minor duplication — 'Get a full product detail' is restated as 'Returns a full product detail' — but every component (returned fields, sibling differentiation, id derivation, error behavior) earns its place in a compact form.

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 id-based lookup with no output schema, the description provides most of what an agent needs: what is returned, where the id comes from, and what happens on bad input. It also names the neighboring summary tools, which helps an agent decide when to call the detail endpoint. Minor gaps, such as whether stock is numeric quantities vs availability booleans and whether prices are included, don't seem fatal given the descriptive list already given.

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

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

The schema already documents productId's has 100% coverage, so the baseline is 3. The description adds extraction guidance that is genuinely beyond the schema — specifically that productId is the digits after '-p' in the product-detail URL. This tells an agent how to transform a natural-language URL reference into a callable argument, which raises the value above 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?

The description opens with a specific verb and resource pair — 'Get a Zara product's full detail' — and then enumerates exactly what that detail contains (color variants, marketing description, per-size stock, image gallery). It also differentiates the tool from zara-category-products and zara-search by describing its output as 'richer' than their summaries, so an agent can disambiguate at a glance.

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 names the alternatives (zara-category-products and zara-search) and implies the condition for choosing this tool: pull up a full detail view when summaries are insufficient. It also communicates the prerequisite workflow by explaining that productId comes from a search/category result's url field. It stops short of explicitly stating when not to use the tool or framing the choice as an if/else decision.

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