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

Annotations already declare it as a non-read-only, idempotent, non-destructive, closed-world mutation, and the description adds genuinely new behavior: partial update of only supplied fields and the price/currency coupling rule. It stops short of describing null-to-clear semantics or what happens on an invalid item_id, which would be the remaining behavioral gaps.

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?

Three tight sentences with the resource and scope front-loaded, followed by the two behavioral rules that matter. No filler or repetition of the title.

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 an eight-parameter mutation with no output schema and supporting annotations, the definition covers ownership scope, partial-update behavior, and currency handling. It falls short on null/clear semantics and error or permission behavior, which an agent would still need to guess.

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 63% and the description mostly re-lists the fields already documented in the schema (name, price, quantity, notes, link, must_have). It does add the currency coupling rule, but omits the required item_id and never explains that null values clear a field, which is the main ambiguity the anyOf/null schema leaves open.

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 ("Changes") on a specific resource ("an item on one of the signed-in person's own wishlists") and enumerates the editable fields, so the agent knows exactly what is touched. It does not explicitly name or contrast with siblings like add_wishlist_item or update_gift, leaving the boundary to be inferred from the resource wording.

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?

"Only the fields given are changed" usefully signals partial-update semantics, and "own wishlists, personal or in a group" scopes the ownership requirement. However, there is no explicit when-to-use/when-not guidance and no mention of the sibling tools (add/remove item, update_gift) that an agent might confuse it with.

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