Get pickup quote

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's job is to add context - and 'Nothing is booked' plus 'surcharges are listed apart' tell the agent what the call does and does not commit to, and that the response separates base price from surcharges. It stops short of saying how surcharges are returned or whether quotes expire.

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 lead sentence is front-loaded and the carrier conditions come after, which is the right order, but the second paragraph repeats the first almost verbatim ('Nothing is booked' / 'without booking it'; 'USPS pickups are free' / 'USPS collects for free'). Roughly a third of the text is redundant.

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 10-parameter, read-only, no-output-schema tool the description covers the decisions that matter: no booking occurs, USPS is free and next-day, UPS requires a date and a pickup window, and surcharges are reported separately. The main residual gap is the shape of the returned price/surcharge data, which the description only gestures at.

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?

At 60% schema description coverage the schema already explains the carrier-conditional fields (date, ready_time, close_time, overweight all marked 'UPS only'), and the description largely restates that dependency. It adds genuine meaning for carrier choice - USPS is free and arrives next delivery day, so those parameters go unused - but package_count, total_weight_oz, location and instructions get no description-level treatment beyond the schema.

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 resource (a USPS or UPS pickup) and a specific operation (what it would cost), and immediately rules out the adjacent action with 'Nothing is booked.' That scope plus the free-USPS vs. paid-UPS split lets an agent separate it from list_pickups and from any booking flow without opening the 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?

'Prices one pickup without booking it' and 'Nothing is booked' clearly establish this as a quoting step, and the UPS prerequisites (date, ready and close time) tell the agent what must be supplied to get a valid quote. It never names a sibling as the alternative for the booking step, so the when-not-to-use half is only implied.

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