Delete symptom (erases the entry)

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so safety is covered structurally. Beyond that, the description discloses propagation timing (vanishes from get_symptoms immediately, from the app and other readers after the next iPhone sync), a version-dependent side effect on earlier update_symptom copies, and the returned deleted_entry payload that allows re-logging. This is unusually rich behavioral context that annotations cannot express.

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 core decision (when to delete vs. not) and the alternative are front-loaded before the sync-propagation detail. The long parenthetical about app 1.3.0 and sealed copies is dense but does describe a real behavioral caveat, so it earns its place even if it could be tightened.

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 destructive tool with an output schema, this covers the destructive scope, the path to recover a mistaken delete, the sibling to use instead, and a hard exclusion (Apple Health imports). An agent has everything needed to decide and invoke correctly; return values need not be explained further given the output 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 0% for the single entry_id parameter, so the schema does not define it. The description references entry_id by name in the sibling example but never states what identifies it, its format, or how to obtain it (presumably from get_symptoms). It adds partial context but does not fully compensate for the coverage gap.

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 ('Erase one reported symptom'), constrains scope ('that was logged by mistake'), and explicitly carves out the boundary against the nearest sibling by naming update_symptom as the tool for symptoms that ended. An agent can distinguish this from log_symptom and update_symptom without opening any schema.

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?

Gives explicit when-to-use cases (duplicate, wrong person, symptom they did not have), an explicit when-NOT case ('a symptom that simply ended is NOT deleted'), the alternative to use instead with exact call syntax (update_symptom(entry_id, end_at=…)), and an additional exclusion (Apple Health imports cannot be deleted here). Nothing is left to inference.

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