Weigh the cartons

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

With no annotations, the description must carry the fullness of behavioral disclosure. It clearly describes the output fields and an explicit edge-case behavior ('chargeable weight goes null, not guessed'). It stops short of stating it is read-only or requires any permissions, but the report-like wording makes side effects unlikely.

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, front-loaded with the report contents, followed by a one-line edge-case rule. No fluff, no repeated schema details, no redundancy with the title.

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 description tells an agent what the report includes and one important null behaviorhol does not cover what happens for missing carton dimensions beyond 'null', whether an empty packing list is valid, or what units/output format is returned. Since there is no output schema, a bit more operational guidance would round it out.

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 covers both parameters (packing_list, divisor) descriptively. The tool description adds general output context but does not deepen understanding of how each parameter affects the result; it only implies that the packing list identifies the shipment and that the divisor factor influences volumetric weight.

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 the resource ('per carton and for the shipment') and enumerates the specific metrics it reports (net, gross, chargeable weight, volume, etc.). It lacks an explicit verb like 'calculates' or 'lists,' and does not contrast with sibling reporting tools, but the intent is unmistakable.

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 explains what the report contains but gives no guidance on when to use this tool over siblings like packing_slip or packing_list_show. There are no prerequisites, no mention of whether a packing list must exist, and no direction to alternative tools for other use cases.

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