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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds meaningful context: invalid input returns a structured error object instead of raising a protocol error, and retrying after correction is safe. It also notes the premium license requirement. The only weakness is that it repeats the read-only/idempotent annotations rather than adding new detail there.

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 front-loaded with the core decision and usage guidance, and the examples are informative. It is somewhat long and partially repeats annotation-level facts, but the structure is clear and most sentences contribute to correct selection or invocation.

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?

Given the tool's decision-support purpose, six parameters, full schema descriptions, annotations, and an output schema, the description provides enough context for an agent to select it and call it correctly. The error contract and example input/output make it especially 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 100%, so the schema carries the baseline burden. The description still adds value by showing a typical input mapping values to named parameters and illustrating the resulting output shape, which helps an agent understand how the parameters interact in practice.

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 decision task—deciding how much to order using demand, lead time, and available cash—rather than merely restating the tool name. It also explicitly distinguishes this tool from the sibling margin_check by naming what this tool is not for.

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 gives a clear when-to-use rule: 'Use before committing to a supplier's minimum.' It also gives an explicit when-not-to-use rule and names the correct alternative, margin_check, for per-unit margin analysis.

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