search_products

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose one meaningful constraint ('never traverses the complete catalogue as a fallback'), which tells an agent not to expect exhaustive results. However, it says nothing about authorization (a sibling auth_status exists), result behavior on no matches, or rate limits, leaving notable gaps for a tool with zero annotation coverage.

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 tight and efficient, about four short sentences, and front-loads the critical constraint ('Search one concise Spanish product phrase; never send a full instruction') before any examples. Every sentence earns its place, with only minor redundancy in the example phrases.

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?

Although an output schema exists (so return values need not be described), the description leaves two of three parameters (warehouse, limit) entirely unexplained and omits any authorization context despite the auth_status sibling. For a search tool with zero annotation coverage, this is adequate but not complete.

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 0%, so the description must compensate. It thoroughly explains the query parameter format ('concise Spanish product phrase', product nouns, constraint examples like 'pepino holandés'), but it says nothing about the warehouse parameter or the limit parameter, which remain undocumented in both schema and description. It compensates for query only.

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 action (search) on a specific resource (products) with a precise constraint: the query must be a concise Spanish product phrase. It clearly differentiates itself from the sibling search_products_batch by limiting itself to a single product phrase, so an agent can tell the tools apart without opening either 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?

Usage guidance is explicit: never send a full instruction, use product nouns with constraints (with concrete examples), route to search_products_batch for multiple products, and try several plausible Spanish phrases for conceptual requests. The sibling alternative and the condition selecting it are named directly.

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