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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, and the description adds meaningful context on top: the exact return fields (valuable since there is no output schema) and the authentication prerequisite ('Needs the user's Cotlet API key with access to this app'). Pagination/rate-limit behavior is still unstated, keeping it out of 5 territory.

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 lists the same field set twice — once as 'giver, message, value, giver address, order status and thank-you note status' and again as 'order number, name, quantity, value, gift message, giver's address, order status and thank-you note status' — which is redundant padding rather than front-loaded information.

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 single-optional-param read tool with no output schema, the description covers the essentials: what is returned, the auth requirement, and how the output chains to mark_thank_you_sent. It stops short of explaining filtering or ordering behavior, but nothing critical for a correct call is missing.

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 100% and the single thank_you enum is fully documented in the schema, so the baseline is 3. The description mentions 'thank-you note status' as a returned field but adds no extra semantics for the thank_you filter itself (e.g., how 'all' behaves).

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?

States a specific verb and resource ('Returns the gifts in your gift tracker') and enumerates the returned fields, so the agent knows exactly what this lists. However it never distinguishes itself from the other zola_* list tools (list_events, list_guests) beyond the name, so a 5 is not warranted.

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 chaining hint 'Use gift_id from each item in mark_thank_you_sent' implies the workflow this tool feeds, which is real guidance. But it gives no explicit when-to-use/when-not versus zola_track_rsvps, zola_list_guests, or joy_list_registry_gifts, so usage remains inferred.

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