save_thread_summary

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

With no annotations, the description carries the full burden, and it does disclose two real behaviors: the write is local and it 'does not modify Apple Mail'. That is meaningful because it tells the agent the source mailbox is untouched. However it says nothing about where the summary is persisted, whether an existing summary is overwritten, or what permissions are required, so disclosure remains partial.

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?

Two sentences, front-loaded with the core action and followed by the non-obvious safety clause. Every clause earns its place, including the closing 'It does not modify Apple Mail'.

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 four-required-param mutation with no annotations and no output schema, the description covers the safety profile and the approval precondition but leaves the storage location, overwrite behavior, and the meaning of the email parameter unexplained. Adequate but with clear gaps an agent would want before calling it.

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 25% (just user_approved), so the description must compensate, and it partially does by clarifying that source_message_ids must be 'the exact source message ids used' — semantics the bare array-of-strings schema does not convey. It says nothing about the email parameter (contact address vs account) or the summary field, so the compensation is incomplete.

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 gives a precise verb and resource ('Save a local, user-approved summary of a selected contact thread') and notes the payload ('the exact source message ids used'), so an agent can tell it produces a stored summary rather than sending mail. It never names a sibling such as save_contact_context or get_contact_context, so differentiation is inferred rather than stated, which keeps it out of the top band.

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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative, even though save_contact_context, get_contact_context, and get_contact_brief sit in the same family. The only usage signal is 'user-approved', which merely echoes the required user_approved const already enforced by the schema.

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