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

With no annotations supplied, the description carries the full burden and does well: it flags the operation as STATE-MUTATING, names the escape hatch (dry_run=true), and discloses per-item error isolation, invoice-based idempotency, and the summary fields returned. What it omits is whether a partially failed batch still books the successful items, and whether any rate limit applies at 100 items.

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 sentences, both front-loaded with the highest-value facts (batch capability, then mutation risk) and no filler. The mutation warning slightly restates the preceding dry_run mention, but the repetition is defensible emphasis for a write operation.

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 two-parameter batch mutation with no annotations and no output schema, the definition covers capability, limit, error model, idempotency, return shape, and safety mode. The remaining gap is failure semantics at the batch level — whether partial success commits — which matters most for an agent deciding whether to retry.

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%, so the baseline is 3, but the description adds real meaning beyond the schema by attributing idempotency semantics to the invoice field and by explaining that dry_run applies to the whole batch rather than a single item. The 1-to-100 item bound is also stated in prose, reinforcing the array constraint.

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 concrete dual verb ("Validate or book") on a specific resource (parcels) with a hard batch ceiling of 100 and explicit batch semantics. The batch framing implicitly separates it from the singular create_parcel sibling, but no sibling is named, so the differentiation is left to inference rather than stated.

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 dry_run flag effectively documents a validate-only mode versus a real booking mode, which gives the agent a clear branch point. However, there is no guidance on when to prefer this over create_parcel for a single item, nor on prerequisites such as balance, courier availability, or required credentials before booking.

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