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

Annotations declare the mutation profile (readOnly false, destructive false, idempotent false, openWorld false), and the description adds genuine extra context: drop is reversible via restore, version conflicts surface as conflict:true, and failures return reason codes 'created'/'committed'. It does not describe auth requirements or the full shape of the returned list, but the disclosure goes well beyond the annotations.

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?

Front-loaded with the core action and packed into a few dense sentences where each clause carries op semantics, conflict handling, or error routing. The run-on parenthetical style and domain jargon ('rikma') add reading cost, but there is little pure 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 5-param mutation tool with no output schema and low schema coverage, the description covers the important ground: op vocabulary, version/conflict handling, and terminal error reasons. It does not explain sessionId or enumerate the group values, and success return content is only alluded to ('show the returned list').

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 only 40%, so the description has to carry weight, and it does: it explains key ('refer to rows only by their key'), spec contents (price, keywords, hours), setField targets (rikma name, description), link (a product recipe), and expectedVersion ('pass the version you last saw'). sessionId and the group enum values are left to the schema, but the operation-bearing parameters are well covered.

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 states a specific verb+resource ('change the draft list with small ops') and enumerates the eight operations, so the agent knows exactly what the tool mutates. It also implicitly separates the draft list from committed rows, which is what distinguishes it from applyAssistantTool, though no sibling is named explicitly.

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?

It maps real user utterances to ops ("that is right"→keep, "not now"→drop) and gives an explicit negative case: rows already on the platform or a supplier-answered wish row cannot be changed here and the person should be sent to the site. The conflict path (pass expectedVersion, conflict:true means show the list and ask again) is also spelled out.

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