save_contact_context

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the write is confined to local storage and contacts no one, but omits the mandatory user-approval gate and says nothing about whether a repeat save merges or overwrites existing context.

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 short, waste-free sentences with the action front-loaded and the safety caveat second. Efficient, though the second sentence is doing double duty as usage and behavior guidance.

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 11-parameter mutation tool with no annotations and no output schema, two sentences are thin. Missing pieces include approval semantics, merge/overwrite behavior on repeat saves, and any indication of what the call returns.

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 36%, so the description is expected to compensate, and it adds nothing about any of the 11 parameters. Fields like notes, open_commitments, timeline_summary, preferred_language, and timeline_direction are left to bare type declarations.

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 (Save) plus resource and scope (local relationship context for one contact), and explicitly separates itself from email-modifying siblings. It does not name its read counterpart get_contact_context, so the differentiation from siblings is implied rather than stated.

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 description gives an implicit trigger (saving local relationship context) and an explicit exclusion ('does not modify Apple Mail or contact the person'), which helps route the agent away from email tools. However, it never says when to prefer this over get_contact_context or similar, and does not surface the user_approved prerequisite.

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