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

Annotations mark this as a mutation (readOnlyHint=false) with external calls (openWorldHint=true). The description adds genuinely useful behavior beyond that: it enumerates the return fields (id, editToken, ownerUrl, shopUrl, wishlist, storage) and flags that editToken must be retained for later item additions, which is a real workflow constraint. It omits error/permission behavior, but with mutation annotations present the bar is lower.

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-loads the core action, then tacks on the return shape and the editToken instruction efficiently. The trailing 'OpenAPI: createWishlist' is marginal filler but does not bloat the definition.

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 seven parameters, no output schema, and no destructiveHint, the description partially fills the void by listing return fields and the token-persistence workflow. It remains incomplete on the many under-described input parameters, so an agent can call the tool but must lean heavily on the raw schema.

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 only 43%, and the description adds no parameter guidance at all. Key inputs like items (with its undescribed nested sub-properties), occasion, giftCategories and hostName are left entirely undocumented, and the description does nothing to compensate for the coverage gap as required at low coverage.

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?

Clear verb+resource: 'Create a party gift wishlist' states the action and object precisely. It does not explicitly contrast with the sibling create_and_fill, but the stated purpose is unambiguous on its own.

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?

'Save editToken for add_wishlist_item' gives one concrete post-call instruction, implying this is the entry point of a wishlist workflow. However, it never states when to prefer this tool over create_and_fill, nor any preconditions, leaving the choice between the two creation tools to inference.

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