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

Annotations already declare destructiveHint=true and openWorldHint=false; the description adds genuinely new context beyond them: cost ('Free') and required scopes (read to list, write to change). It also discloses the side effect that resolve/expand auto-create watch entries, which is behavior an agent could not infer from the annotations. It stops short of saying what happens when untracking a node that isn't tracked.

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?

Five short clauses, all load-bearing: mode semantics, sibling side effect, cost, and scopes. Slightly telegraphic phrasing ('it stops', 'by itself') costs a little readability but nothing is wasted or padded.

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?

With an output schema covering return values and 100% schema coverage on four optional parameters, the description supplies everything else an agent needs: mode selection, side effects from sibling tools, authorization requirements, and cost.

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 baseline is 3, but the description adds combinatorial semantics the flat schema cannot express – which pairs of parameters activate which mode, and that remove is the inverse of tracking. The note parameter ('why, up to 500 characters') is left to the schema.

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?

It states the resource (the tracked-node list scoped to this account) and the three roles, plus the mutation modes via node+role and node+remove. The opening clause is a noun phrase rather than a verb, so the fact that a bare call returns a list is only confirmed later by 'Needs the read scope to list'. Sibling differentiation is present through the explicit mention of resolve and expand.

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?

Clear argument combinations are given: node+role changes role, node+remove stops tracking, and a bare call lists. It also flags an important interaction with siblings – identity_resolve and identity_expand implicitly add their node as watch – which tells an agent when this tool is unnecessary. No explicit 'do not use when' beyond that, keeping it at 4.

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