audit_product_history

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 adds genuine value by revealing the two-phase interaction: the caller is asked to pick one candidate before the full audit runs. However, it never explicitly states that the operation is read-only/non-destructive, nor what happens when no lookup parameter is supplied.

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 sentences with zero filler: the first front-loads the purpose and lookup modes, the second discloses the disambiguation behavior that materially affects how the agent should drive the interaction. Every phrase earns its place.

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?

The output schema covers return values and the multi-step candidate-selection flow is described, but the tool has 4 optional parameters with zero required and the description gives no hint of what happens with no arguments, how the candidate selection output is presented, or what include_cancelled controls. It is minimally viable but leaves clear gaps.

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 carry the parameter meaning. It implies a mapping of product_query to name/code, product_id to ID, and lot_number to lot, but does not name the parameters or state how they combine, and one parameter, include_cancelled (default true), is entirely unexplained. An agent cannot judge whether to override the default or what its effect on the audit results is.

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 uses a specific verb ('audit') with a specific resource ('a product's complete stock history') and enumerates the lookup methods (name, code, or ID). The 'complete' qualifier and the audit verb reasonably differentiate it from search, summarize, and report-generation siblings, though it never explicitly names any sibling.

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?

No guidance is given on when to choose this tool over closely related siblings such as search_products, get_product_detail, search_stock_moves, reconstruct_product_stock_ledger, or generate_product_stock_audit_report. The candidate-selection note describes a behavioral consequence of ambiguous matches, not a usage decision, and no alternative conditions or exclusions are stated.

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