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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this with 'Nothing is created or charged', which is the key behavioral reassurance for an agent deciding whether a quote is side-effect free. It also discloses the shape of the returned data (per-facility quotes, delivery day ranges), adding value beyond the annotation set. No auth or rate-limit context is given.

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 tight sentences plus the endpoint path. The core purpose and the no-charge guarantee are front-loaded, and the create_order handoff is placed last where it is most actionable. No filler.

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?

With no output schema, the description usefully compensates by describing the return payload (prices and shipment methods with uid, price, min/max delivery days and dates, per facility) and the read-only nature. It is close to complete; only edge behaviors such as the effect of allow_multiple_quotes on the response are left to the schema.

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 description coverage is 100% and the nested product/recipient objects are thoroughly documented in the schema, so the baseline is 3. The description mentions no input parameter semantics of its own (currency, allow_multiple_quotes, recipient fields are all explained only in the schema), so it adds nothing beyond structured data.

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 ('Price an order before placing it') and enumerates exactly what the response contains: product prices and shipment methods with shipmentMethodUid, price and delivery days per fulfillment facility. This clearly separates it from siblings like gelato_create_order (which actually places the order) and gelato_list_shipment_methods (which is not address-specific).

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?

Explicitly frames the tool as a pre-purchase step ('before placing it', 'Nothing is created or charged') and gives a concrete handoff: 'Pass a returned shipmentMethodUid to gelato_create_order.' It does not state any exclusions (e.g. when to prefer gelato_get_product_prices instead), so it stops just short of full when/when-not coverage.

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