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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Free, no side effects' at the end, which is exactly the kind of behavioral transparency expected. It also reveals important behavioral details: inclusion of unregistered tools with registered:false flags, drift detection against the live wire surface (issue #175), and the canonical-UUID behavior where mcp_name changes but tool_id stays. It doesn't describe output structure details, but the description covers the meaningful behavioral traits comprehensively.

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 thorough but front-loads the core purpose in the first line, then layers detail progressively (authoritative use case, then edge-case behavior, then drift detection). Every paragraph adds distinct value: identity semantics, unregistered handling, mcp_name vs tool_id stability, and wire-surface diffing. It's on the longer side but dense with necessary nuance—the version-reference and issue-number citations slightly inflate length without adding agent-relevant behavioral detail.

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?

This is a zero-parameter read-only introspection tool with an output schema and no annotations. The description covers: what it returns (canonical identities), its purpose (authoritative source), its edge cases (unregistered tools, registered:false), its semantic guarantees (tool_id stability across renames), and its safety profile (free, no side effects). For a tool of this complexity, the description is fully complete—there's nothing an agent would need to know that isn't stated.

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?

The tool has 0 parameters with 100% schema coverage (an empty object), so the baseline for parameter semantics is 4. The description adds no parameter info because there are none, and that's entirely appropriate—the description isn't expected to document parameters that don't exist. The introduction of 'tool_id, mcp_name' as output concepts adds value by priming the agent on what the return shapes are. Given zero params, this dimension is essentially N/A and deserves full marks.

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+resource ('Return canonical (tool_id, mcp_name, …) for every tool the wheel exposes') that precisely states what the tool does. It distinguishes itself from siblings by clearly identifying itself as the authoritative identity source, contrasting with the operational tools in the sibling list (all authority_* operational functions). The 'canonical-UUID design' framing makes its distinct role unmistakable.

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 explicitly states when to use this tool: 'The authoritative source for any client (Studio, agents, FE) that needs to know how this MCP identifies its tools.' It also names the specific consumer (Reconcile) and explains the exact usage pattern (UUID-join against stored pricing model, with explicit non-usage guidance: 'no name-based UUID derivation, no guessing'). This is exceptional guidance that clearly discriminates against alternatives.

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