ozon_category_tree

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

With no annotations at all, the description carries the full behavioral burden. It adds genuinely useful context beyond the schema by disclosing the scale (9,800 nodes), implicitly warning that fetching the whole tree without search/depth is expensive, and framing search as the narrowing mechanism. However, it does not disclose what happens when called with no arguments, how results are structured, or how depth and search interact when combined.

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 short sentences with no waste: the first establishes identity, the second delivers the navigation logic. Every word earns its place and the key behavior (tree size and two usage modes) is front-loaded.

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 simple tool with two optional, fully documented parameters, the description covers identity, scale, and both usage modes. Since there is no output schema, the response shape of the tree is left implicit, and the combined depth+search case is not addressed, but these are minor gaps for a straightforward lookup tool.

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 per the baseline the description need not re-document the parameters. The description adds modest semantic value by tying the parameters to usage intent ('pass search to find a category, or depth to go deeper'), but provides no extra detail above the schema's own descriptions of depth levels and case-insensitive search.

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 a specific resource (the Ozon category tree), states its size (9,800 nodes), and explains what the tool lets you do (find a category or go deeper than top level). It is easily distinguished from siblings since no other tool covers the category tree itself, though the fetch/get verb is implied rather than explicit.

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 usage guidance: use 'search' when you need to find a category, use 'depth' when you need to go deeper than the top level. It explains both navigation modes clearly, but does not explicitly discuss when not to use this tool or name alternatives, since the category-tree resource has no true sibling overlap.

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