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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the description is free to add the things annotations cannot: the algorithm is a first-fit-decreasing heuristic and explicitly not proven optimal, and invalid input never raises a protocol error but returns {"error": ...}. That optimality caveat and the error contract materially change how an agent should interpret and retry results.

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?

Purpose and limits are front-loaded and every later sentence (rotation modes, support rule, freight use case, optimality caveat, error contract) carries distinct information. The embedded input/output JSON is longer than strictly necessary given a full schema and an output schema, but it does resolve the free-form object shapes, so it mostly earns its space.

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?

For a nested, free-form-schema tool this covers what an agent actually needs: the size ceiling, unit consistency requirement, rotation and support semantics, the heuristic's non-optimality, the in-band error shape, and retry safety. Return values are shown in the example and further backed by an output schema, so nothing material is missing.

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 baseline is 3, but the description earns extra by defining semantics the schema only names: rotation modes with "upright (rotate around the vertical axis only)", "fragile items carry nothing", and rules.min_support as the share of a box's base that must rest on the floor or on boxes below, default 0.6. The worked example also disambiguates the free-form item and container objects.

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?

States a specific verb and resource ("Place up to 20 boxes into containers or pallets") plus the constraints it honors (rotation, weight, support). The 20-box cap also implicitly separates it from the sibling pack_bins_large, so an agent can pick between them without opening either schema.

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?

"Use to decide pallet or carton count before booking freight" gives a concrete decision context rather than a generic restatement. It does not explicitly name pack_bins_large as the alternative for larger problems or state when-not to use it, so it stops short of full routing guidance.

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