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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description adds substantial non-obvious behavior: 24-hour expiry, that retrying an unavailable ID cannot recover it, that rebuilding does not restore ticks or partial coverage, and that a linked Chop It account is required. This is exactly the kind of context annotations cannot carry.

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 first sentence front-loads purpose well, but the recovery/rebuild material spans several sentences and reads as create_shopping_list or open_saved_week territory rather than this read tool's job. Roughly half the text is tangential to invoking get_shopping_list.

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 an output schema present and annotations covering the safety profile, the definition gives the agent everything needed to call it correctly, including the expiry failure mode and account prerequisite. The only gap is that it never says what to do on expiry beyond 'cannot recover', which nudges the agent toward a sibling tool by inference rather than instruction.

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 coverage is 100% and the single parameter already carries a warning against inferring the list from an old widget, so the schema does the heavy lifting. The description reinforces exactness and links the returned revision number to downstream tools, but adds little about the parameter's format or source beyond what is already structured.

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 and resource ('Returns the latest saved revision of a shopping list') and enumerates what comes back: lines with stable IDs, tick/partial-coverage state, and the revision number. It names the sibling consumers (update_shopping_list, open_shop_handoff) that take the returned revision, so an agent can place it precisely among the 35 siblings.

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?

Usage is implied rather than stated: it establishes that saved state supersedes earlier conversation output and that the ID must be exact ('Never infer the list from an old widget' is in the schema), which tells the agent when this tool is authoritative. However, it never explicitly contrasts with create_shopping_list or says when to read versus re-create, leaving the routing decision partly to inference.

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