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

With no annotations, the description carries the full burden, and it does disclose meaningful return semantics: the five possible states, that preorder carries an expected date, that the delivery estimate applies only to in-stock items, and that quantities are never returned. It does not state behavior for unknown product ids, whether out-of-stock products still resolve, or any error/pagination characteristics.

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 compact sentences with no filler; the primary answer ('stock state') is front-loaded and the clarifying clause about quantities earns its place by preventing an agent from expecting stock counts.

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?

There is no output schema and no annotations, so the description must convey return values, and it does so by enumerating every state plus the conditional delivery estimate. Minor gaps remain around the expected-date format and whether 'lang' changes the state labels, but the definition is sufficient to call the tool 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 description coverage is 100%, with both 'id' and 'lang' documented including the allowed language list and default behavior. The description adds nothing about either parameter, so the baseline of 3 is appropriate when the schema does all the work.

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 a specific resource ('stock state of a product') and enumerates the exact return domain (in_stock, low_stock, preorder, backorder, out_of_stock), so an agent knows precisely what this tool answers. It does not explicitly differentiate itself from sibling get_delivery_options, and in fact mentions a 'delivery time estimate for in-stock items', which slightly overlaps that sibling's territory.

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 is only implied: an agent can infer this is the tool for checking stock before an order, and the note that no quantities are disclosed sets a boundary on what to expect. There is no explicit when-to-use/when-not guidance and no pointer to get_delivery_options for fuller delivery information.

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