update_shopping_list_items

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals several key behaviors: item_ids affect whole lines, store/category moves work on multiple lines, text edits apply to one line and collapse merged lines, and the tool returns the updated lines. It also warns about stale item_ids. This is transparent for a mutation tool, though it doesn't discuss failure modes or permission requirements.

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 a single paragraph with several sentences, but each sentence carries distinct, useful information. The main action is stated first, followed by usage patterns and a return-value note. It is not overly verbose, though it could be tightened by removing the mention of 'title, amount, unit, note' twice (it appears in the sentence and then in parentheses). Overall, it is efficient and front-loaded.

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?

The tool has 7 parameters and multiple behaviors, and the description covers the essential aspects: how to select lines, how to perform different types of updates, the return value, and a critical caveat about re-reading item_ids. Since there is no output schema, the description correctly explains the return format. It does not cover error cases or permissions, but for a shopping list tool this is likely sufficient.

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 57% (note, item_ids, store_id, category_id have descriptions; unit, title, amount do not). The description compensates by explaining parameter interactions: it clarifies that store_id/category_id on their own move items, while title/amount/unit/note edit text and apply to one line. It also explains the collapse behavior for merged lines, which is not apparent from the schema. This adds substantial meaning beyond 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?

The description clearly states the tool's purpose: 'Change shopping list lines.' It specifies the resource (shopping list lines) and the primary action (changing). It references get_shopping_list as the source for item_ids, which distinguishes it from add/remove tools by implying it operates on existing lines. However, it does not explicitly name sibling tools like add_shopping_list_items or remove_shopping_list_items, so differentiation relies on context.

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 guidance on when to use the tool: it requires item_ids from get_shopping_list, and explains that moving items (store_id/category_id) works across multiple lines, while editing text applies to one line at a time. It also instructs the agent to re-read item_ids from the result rather than reusing the ones sent. This gives clear context for invocation, though it does not explicitly contrast with add/remove tools.

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