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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint and openWorldHint, so the bar is lower. The description still adds real value: it discloses that errors are returned as {"error": ...} objects rather than protocol errors, and that retry after correction is always safe. It does not discuss solver non-optimality/timeout behavior beyond the time_limit_s parameter.

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?

Front-loaded with the core purpose and use cases, and the example is illustrative rather than padding. The inline JSON example is fairly long, but it earns most of its space by showing input/output shapes and slack/solver_status semantics.

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 solver tool with an output schema, nested objects and 100% schema coverage, the description covers purpose, input shape, an example return, error contract and retry safety. Nothing essential an agent needs to call it correctly 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 already 100%, yet the description adds semantics not in the schema: any numeric item field named in limits is treated as a constrained resource, and qty allows repeated selection of an item. That is meaningful behavioural meaning beyond the field descriptions.

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?

Names a specific operation (choose items maximising value under capacity limits) and a concrete resource model (items with value plus constrained fields). It also distinguishes scope from siblings like pack_bins/cutting_stock by stating what it is not for (dependencies between items).

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?

Explicitly lists concrete use cases (budgets, cargo, campaign or feature selection) and an explicit exclusion ('Not for dependencies between items'). This gives an agent both positive selection criteria and a routing boundary.

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