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

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral context: it returns base64-encoded PDF/PNG per container, and it has the option to render a previously computed plan instead of recomputing. This goes beyond the basic read-only hint without contradicting it.

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 concise (two sentences), front-loads the core purpose, and includes a clearly flagged important usage note and return format. Every sentence contributes meaningful information without repetition.

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 gives a solid overview of the tool's purpose, key usage guidance (pass previous result), and return format, which is sufficient for a complex tool with a detailed schema. It lacks a few details such as fallback behavior when no `result` is passed, but the schema covers most parameter specifics.

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?

With schema coverage at 43%, the description needed to compensate for undocumented top-level parameters, but it only highlights the `result` parameter, which is already described in the schema. Other important parameters like `cargos`, `pallet`, and `loadingMode` are not addressed in the description, so it adds little semantic value beyond the schema.

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 states the tool generates a 'CAD-style PDF + 3D PNG report for a packing job,' using a specific verb and resource. It distinguishes itself from siblings like estimate_capacity and pack_containers by focusing on report output rather than estimation or packing.

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 provides clear usage context by emphasizing the IMPORTANT step of passing the `result` object from a previous pack_containers call to ensure consistency. It implies this tool is used after packing rather than as a standalone packing tool, but does not explicitly state when not to use it or name alternative reporting tools.

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