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

Annotations cover the read-only safety profile, so the description goes further with real operational detail: city/address is required or no price can be reported, fromPrice is a storefront floor to be quoted as 'from ₪X', pricedAtStorefronts=1 signals a single-shop price, and results are sorted cheapest per unit. This is substantial context beyond what readOnlyHint/openWorldHint provide.

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?

Purpose and trigger are front-loaded, and nearly every sentence carries information, but the pricing digression (fromPrice vs normalizedUnitPrice economics) is dense and the when-not guidance sits last rather than beside the purpose. Slightly longer than strictly needed.

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?

There is no output schema, and the description compensates by describing the returned fields (fromPrice, normalizedUnitPrice, rejected, pricedAtStorefronts) and their sort order, plus the required geographic input for pricing. For a 7-param workflow tool with no output schema, an agent has everything needed.

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%, so baseline is 3; the description adds meaning the schema doesn't, e.g. that query should be Hebrew and that product_id is dropped from results, plus the concrete 'נקניקיות פרגיות → query=פרגיות' mapping. It doesn't explain near/location/radius_km interactions, which are left to 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?

States a specific verb+resource and ties it to a concrete trigger ('After optimize_delivery priced the wrong product, use this to show other things the shopper might have meant'), and explicitly separates itself from the sibling by scope. An agent can identify this tool 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?

Gives explicit when-to-use, a worked recovery workflow (re-call optimize_delivery with the line pinned), an alternative use case ('is there a cheaper one?'), and an explicit when-not: 'Do not use this for a first-pass shopping list — call optimize_delivery once with every line.' Both the alternative and the exclusion are named.

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