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

Goes well beyond the annotations: it discloses the return contents (registration status, canonical form, account status), the conditional disclosure rule for engagement/archetype/attunement (tier labels only when the member has opened their profile, otherwise empty with a stated reason), and the authentication prerequisite including how to self-mint a credential. Annotations only cover the safe-read profile; the description carries the rest.

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?

Front-loads the verb and the when-to-use rationale, then moves to return semantics and auth. It is on the long side and some clauses (the tier-label explanation) could be tightened, but every sentence conveys information an agent needs.

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?

No output schema exists, yet the description explains what comes back, including the conditional-empty case and why. Combined with the auth prerequisite and the pre-action usage framing, an agent has everything needed to call this correctly.

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% and the schema itself already documents tilde-optional, case-insensitive matching and the 64-char cap, so description-level parameter detail is redundant. With a single fully documented required param, baseline credit applies; the description only reaffirms the handle concept rather than adding new syntax.

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+resource: checking whether a ~handle is known to the ~alter identity field, and frames it as an existence/trust check before acting on a handle. This is clear, but it never distinguishes itself from the sibling alter_resolve_handle, which an agent could easily confuse it with.

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 guidance ('before you address, pay or trust someone by handle') with the rationale (avoid acting on a name that was typed at you). It also names the credential-minting path (register_autonomous_challenge then register_autonomous), but stops short of any when-not guidance or an alternative to alter_resolve_handle.

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