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

Annotations already establish this as a read-only, idempotent, closed-world query, so the description's job is to add semantics — and it does, disclosing the costing method (moving average), the granularity (one shipment line), and the computed fields (sale, cost, margin). It omits output shape and pagination/period-default behavior, which keeps it off a 5.

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?

A single sentence that front-loads granularity and then lists the three returned measures, with no filler or restatement of the tool name.

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 no output schema, the description must carry return semantics, and it does identify the three per-line values — but an agent still doesn't know whether results are aggregated, what ordering or pagination applies, or how an omitted from/to is interpreted. Adequate, not 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 coverage is 100%, so both from and to are fully described as ISO dates with inclusive/exclusive boundaries already documented. The description only echoes the notion of a period and adds no defaulting or open-ended-range behavior, so the baseline 3 applies.

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 resource precisely (each shipment line in a period) and spells out exactly what the row carries: sale value, moving-average cost, and margin. It reads as a report of per-line COGS rather than an action, and it never distinguishes itself from neighbors like inv_valuation or inv_moves, so it falls short of a 5.

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?

"In a period" implies this is a date-range report, which is the only usage cue given. There is no explicit when-to-use, no statement about what happens if from/to are omitted, and no pointer to the alternative valuation or movement tools.

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