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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's added value is real: it discloses that results are live checkout rates including GST sourced from carrier and shipping-rules apps, and mandates mentioning free pickup. It stops short of describing latency, failure modes, or what happens with unsupported postcodes, but adds meaningful context beyond the annotations.

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?

Dense but every sentence carries operational weight — scope, trigger, prerequisite chain, prohibition, and the pickup reminder. Slightly over-emphatic with capitalization and stacked clauses, but front-loaded and free of padding.

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 read-only pricing tool with an output schema, the description needn't explain return values, and it doesn't. Combined with a nested options object, 7 params, and a sibling estimate tool, the description supplies the prerequisite dependency on vivid_price/product and the anti-estimation rule. Minor gap: no guidance on invalid or unmapped postcodes.

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 71%, so the schema documents most parameters. The description still adds value: it tells the agent postcode is required, suburb 'improves accuracy', and state is derived from postcode if omitted, plus the ordering constraint that size/options/quantity must come from vivid_price. It does not explain the options nested-object contract itself, which the schema partly covers.

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+resource: exact delivery/freight cost to an Australian postcode for a product configuration, and pins it to the same live checkout rates (carrier + shipping-rules apps, incl. GST). This clearly separates it from the sibling vivid_delivery_estimate, which the description explicitly warns against using.

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?

Gives an explicit trigger ('Use whenever the customer asks what shipping/delivery costs'), a prerequisite chain (resolve product + size/options + quantity first via vivid_product / vivid_price), and a negative instruction ('Never estimate freight yourself'). It also names the free-pickup alternative to surface. Nothing about when-to-use is left to inference.

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