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

Annotations already declare read-only, closed-world, idempotent behavior, and the description adds substantial context beyond them: free calls are capped at 2 per caller per UTC day, full answers require full:true or payment, and pricing is $0.50 per calculation/item via x402. It also notes that custom vehicle input is full-mode only.

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 definition is a dense run-on that packs purpose, usage, schema, and pricing into a few long sentences; the first sentence alone is overloaded with lists. It front-loads purpose, but it repeats schema text and would benefit substantially from paragraphing or bullets.

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 complex planning tool with nested input and no output schema, the description covers the inputs, free/paid modes, list mode, and what the plan includes: vehicle counts, positions, securing, and sources. It still does not specify the exact full-answer format or error behavior, so it is strong but not fully 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%, and the description mostly repeats the same input string already present in the schema, including vehicle enum, dt, width, gross, qty, mat default, and custom fields. The only added semantics are minor clarifications such as mat as the friction factor and custom being full-mode only, so baseline 3 fits.

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 opening sentence names a specific planning task: how many vehicles a drum quantity needs by space and payload, plus rows/positions, chocks, securing, and vehicle comparisons. It explicitly distinguishes this from drum_fit, so an agent can select it without inspecting siblings.

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?

It tells the agent to use drum_fit first to choose the drum, then this tool to plan how filled drums travel. It also explains the free-verdict versus full paid-answer split and states that list mode is always full and paid per item.

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