Find categories

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

Annotations cover read-only/idempotent safety. The description adds a critical nuance: the Persian vs English search coverage difference and the accessory-mixing behavior in parent categories, which go beyond annotations. It doesn't discuss limits or output structure (though output schema exists), so not perfect.

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-loads the output types then describes modes cleanly. It's not overly long, but the parenthetical about Persian and the final caution sentence could be tighter. Still, every sentence provides useful information.

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 an output schema present and annotations covering safety, the description fills the remaining gaps: the relationship to sibling tools, the parameters' effects, and the accessory caveat. An agent has everything needed 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?

Schema coverage is 100%, so baseline is 3. The description adds real semantic value: it explains what each parameter does in terms of the result set (query matches name/code, parent_id lists children, neither returns top-level), and gives a concrete example of Persian vs English behavior. This goes beyond the schema's simple descriptions.

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 specific artifact this tool produces (category codes for dk_category_products and main-category ids for dk_best_sellers), which explicitly connects it to sibling tools and distinguishes it from dk_search, dk_suggest, etc. The purpose is concrete and actionable.

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 explains the three modes (query, parent_id, neither) and gives a behavioral caveat about mixed accessories. It doesn't explicitly compare against siblings like dk_search or dk_suggest, so it's slightly short of the top score, but the mode explanations are strong guidance.

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