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

With no annotations, the description carries the full burden. It discloses that this is a manual commit, computes totals, returns a shareable URL, and allows omitting retailers with no good match. It also warns against blindly passing product_ids, which adds meaningful operational context beyond what the schema conveys.

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 description is front-loaded with the critical warning, then the rule, then how-to guidance. Each sentence adds distinct value, and the structured paragraphs make it easy to scan despite its length. No redundancy or 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?

For a single-parameter tool with no output schema, the description thoroughly covers input shape, item-level requirements, alternatives, prerequisites, and return value. It falls just short of full completeness by not explicitly stating what 'commit' does in terms of persistence or any possible error behavior, but it is enough for an agent to invoke correctly.

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?

Even though the schema documents selections/query/picks, the description enriches these parameters by explaining that product_ids should be the best match from batch_search, that not every retailer needs a pick, and that the query is the original shopping-list item. This goes well beyond the schema's generic property descriptions.

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?

Description opens with 'ADVANCED / manual commit' and clearly states it commits a basket from product_ids the user has already chosen, computes totals, and returns a shareable URL. It explicitly distinguishes save_basket from build_basket, making its unique purpose unmistakable.

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?

Provides explicit when-to-use and when-not-to-use: 'Do NOT use this to build a basket from a shopping list: for any list of 2 or more items, call build_basket' and 'Use save_basket only to commit a basket from product_ids you have ALREADY chosen yourself.' Also adds a concrete example and prerequisite ('Only call this after you have reviewed batch_search results').

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