diff_mylist

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, which covers the safety profile of the operation. The description adds value by enumerating the categories of rows the diff will show (additions, updates, removals, duplicates, unchanged), providing more behavioral detail than the annotations alone. It does not mention auth or rate limits, but the annotation coverage lowers the burden.

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, well-structured sentence that front-loads the key verb and resource. It is concise with no redundant words or filler, and every word contributes to the understanding of the tool's purpose.

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 a nested request object with many fields, and the description gives no details on how to construct the request or what the actual return structure looks like. It mentions high-level diff categories, but with no output schema and no parameter explanation, the description is insufficient for an agent to invoke the tool correctly without additional context.

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 0%, and the description provides almost no parameter guidance. It mentions 'proposed BOM' but doesn't explain list_id, request, or the nested proposed_items structure. The schema itself documents defaults and constraints, but the description should compensate for the lack of coverage and fails to do so.

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 uses a specific verb 'Dry-run' and clearly states the resource (a proposed BOM against a MyList) and the output (additions, updates, removals, duplicates, unchanged rows). It distinguishes this from sibling tools like sync_mylist or get_mylist, which either apply changes or retrieve list contents without diffing.

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?

The description implies the tool is for previewing changes ('Dry-run'), which suggests it should be used when you don't want to mutate the MyList. However, it does not explicitly state when to use this vs. alternatives like sync_mylist or add_parts_to_mylist, nor does it mention exclusions like 'do not use if you want to apply changes'.

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