forget

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

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description aligns with that while adding useful context: the operation is a 'Hard-delete' and it redacts identifying audit history. It goes beyond the annotations by specifying exactly what kind of destructive action occurs and that audit data is also affected.

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 a single, tight sentence with no filler. The primary action is front-loaded, and every word contributes meaning about the operation and its audit implication.

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?

The output schema and annotations reduce the need for return-value and safety details, but the two required parameters remain essentially unexplained. For a destructive tool like this, leaving 'target' and 'scope' open to interpretation is a significant completeness gap that the description does not fill.

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%, so neither 'target' nor 'scope' has description details. The description only hints that a person or record is involved, but it never explains what 'scope' means, what string values are expected, or whether scope selects the kind of entity, the deletion breadth, or the audit scope.

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 opens with the specific verb 'Hard-delete' and names the resource ('a person or record'), then adds the distinctive effect of redacting identifying audit history. This clearly distinguishes it from sibling tools such as correct_record, supersede_fact, and merge_people, which imply modification rather than permanent deletion.

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 states what the tool does but gives no explicit guidance on when to choose it over alternatives. It does not mention that hard deletion should be reserved for cases where correction, supersession, or merging is insufficient, leaving the agent to infer usage from the tool name alone.

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