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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds genuine value by clarifying that the POST /api/deliveryservices call is a query ('QUOTE ONLY', 'Nothing is purchased, created or printed'), which resolves the confusion of a read operation exposed as POST. It also discloses the include_pricing behavior. No return format or pagination detail, but the safety profile is well covered.

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 front-loaded sentences with no filler; 'QUOTE ONLY' leads with the key constraint. The trailing endpoint path earns its place by flagging the POST semantics, though it could be woven in more cleanly.

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 tool with nested sender/destination/packages objects and no output schema, the description covers purpose and the read-only nature but is thin on how the required shipment inputs (destination, packages) shape the result and on the many optional flags. Adequate as a minimum-viable definition, but not complete for the complexity.

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?

With 40% schema description coverage across 10 parameters, the description is expected to compensate, but it only addresses include_pricing (already documented in the schema) and gestures at the shipment via 'for a shipment'. It says nothing about sender, return_order, declared_value, dangerous_goods, insurance_value, authority_to_leave or signature_required, leaving six-plus parameters unexplained in both places.

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 (list/quote) and resource (carrier delivery services available for a shipment), and enumerates what is returned (carrier, service name and code). It separates itself from write tools by asserting nothing is purchased/created/printed, though it never names the closest sibling (get_rates). Clear and specific, but no explicit sibling differentiation.

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 'available for a shipment' framing and the include_pricing toggle imply this is a pre-order quoting step, but it never states when to use it instead of get_rates or the create_order flow. Usage is inferable rather than stated.

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