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

With no annotations provided, the description carries the full burden. It discloses the key behavioral traits: hiding from public view, non-destructive nature, and reversibility. It does not mention permission requirements, but 'your own annotations' implies authorization. This is sufficient for a simple toggle operation.

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 two sentences and contains no filler. Every phrase adds meaningful information: the action, the target, the effect, and the reversibility. It is front-loaded with the verb and resource.

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 simple tool with no output schema, the description covers the essential aspects: what it does, the target ownership, and the non-destructive reversible nature. It doesn't mention the default visibility value, but that is in the schema. Slight gap is not specifying that the annotation remains visible to the author, but 'from public view' implies this.

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 0%, so the description must compensate. It implies annotation_id by referencing 'one of your own annotations' and suggests the visibility parameter through 'public view' and 're-shown later.' However, it does not explicitly name the parameters or explain the enum values, leaving some ambiguity that the schema alone doesn't resolve.

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 uses a specific verb ('hide') and resource ('one of your own annotations'), and clarifies the effect ('from public view'). It clearly differentiates from deletion by stating 'Does not delete; can be re-shown later.' This is unambiguous and distinguishes from sibling tools like post_annotation or list_annotations.

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 implies usage context: it is only for your own annotations, and explicitly contrasts with deletion by noting reversibility. It does not name alternative tools or explicitly state when not to use, but the ownership restriction and reversibility provide clear guidance.

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