My Identity

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

Annotations already declare read-only and idempotent safety. The description adds valuable behavior beyond annotations: the target parameter switches to an institutional projection, only ~alter is recognized, other values fall through to self-projection, and institutional mode is free. It also discloses the authentication prerequisite. No contradiction with annotations.

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 compact and front-loaded with the primary purpose, then explains the optional parameter and authentication context. Every sentence adds useful information without padding. It manages to convey substantial behavior in a few sentences.

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 one-optional-parameter read-only tool with a fully described schema and annotations covering safety, the description covers the return concept, the special mode, the fallback behavior, and authentication. No output schema exists, but the description sufficiently outlines the response semantics for an agent to understand what to expect.

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 already documents the target parameter. The description adds meaning beyond the schema by explaining the projection switch, the protocol-tier handle behavior, and the fall-through path requiring member_self scope. This enriches the parameter semantics beyond a mere restatement.

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 and resource: 'Returns canonical handle and user summary for the authenticated member.' This clearly identifies the tool as a self-identity lookup and differentiates it from sibling tools like alter_resolve_handle or alter_presence_read by focusing on the authenticated member's own identity.

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?

Provides clear context: use for the authenticated member's identity, with an optional institutional projection mode, and explicitly notes authentication requirements plus a free registration flow. It does not explicitly name alternatives or when-not-to-use conditions, but the context is strong enough for an agent to select it appropriately among siblings.

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