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

With no annotations provided, the description carries the full burden and does so excellently. It discloses that notes disappear from later get_feedback results, the reviewer sees the resolution live, nothing is deleted, and resolved:false reopens a note. It also explains the security rationale for requiring creatorKey.

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 front-loaded with the core purpose and every sentence adds distinct value: trigger condition, system effect, payload guidance, authentication requirement, and reversibility. There is no filler or repetition.

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 mutation tool with six parameters and no output schema, this is complete: it covers when to use it, what payload to write, the required credential, the behavioral impact on get_feedback, and how to undo the action. No critical calling information is missing.

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 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that 'what' is shown directly to the reviewer and should be written for them, that creatorKey comes from share_page and can claim legacy rooms, and that resolved:false reopens. This exceeds baseline.

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 states a specific action ('mark notes resolved'), the target object ('reviewer notes'), and the concrete effect ('leaves the active list for every later get_feedback'). This clearly distinguishes it from sibling tools get_feedback, share_page, and share_pages.

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?

It says when to call: 'once you have actually applied them,' and it gives an important prerequisite: the creatorKey is required and the review link alone cannot resolve. It does not explicitly list alternative-tool routing, but no sibling is a true alternative to resolving feedback, so the context is sufficient.

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