Delete contact

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

The description adds significant behavioral detail beyond the annotations (which already mark destructive and idempotent). It explicitly states that deletion is not soft-marked, that missing contacts are reported as successful erasure (matching idempotentHint), and that no mail is deleted or server contacted—clarifying the exact side effects. This aligns with annotations and provides additional context the agent needs to understand consequences.

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 is efficient and well-structured. It leads with the core purpose, then explains irreversibility, scope of deletion, idempotent behavior, and a safety note—all in about five sentences. Every sentence contributes new, non-redundant information, and nothing is overly verbose.

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?

Given the complexity of a destructive operation, the description is comprehensive. It covers side effects (no mail deletion, no server contact), irreversibility, unusual behavior for missing contacts, and even provides a human-facing confirmation instruction. The presence of an output schema means return value documentation is not needed. All necessary behavioral and safety details are included.

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?

The schema already provides 100% coverage for the single parameter `contactId`, including a detailed description of its source and the caveat to read via get_contact first. The main description adds only that all addresses are removed, which is a behavior detail but not parameter-specific semantics. Since the schema covers the parameter well, the description doesn't need to add more; baseline 3 is appropriate.

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 clearly states the tool erases one person from MailFathom's contact book and removes all associated addresses. It uses a specific verb (erase) and resource (contact record), and distinguishes from siblings like update_contact, get_contact, and create_contact by focusing on deletion. It also clarifies what is not affected (no mail deletion, no server contact), making its purpose unambiguous.

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 provides strong contextual guidance: it warns that deletion is irreversible, advises confirming with the person being acted for, and notes that the operation is idempotent (safe to repeat). It also explains that it only affects the contact record, not mail, which helps the agent decide when to use it. However, it does not explicitly compare with alternative tools like update_contact or delete_draft, so it lacks direct differentiation guidance, though the scope is clear.

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