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

Beyond the annotations, the description adds meaningful behavioral context: a 10-minute token lifetime, the need to save the token, retry semantics for lost responses, and the private nature of the returned key. It does not cover rate limits or auth details, but the annotations already cover the basic read/write and idempotency profile.

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?

Three tight sentences front-load the two-stage structure and then add the retry and privacy details. Every sentence contributes necessary protocol information with no filler.

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 two-stage tool with no output schema, the description covers the essential flow, token expiration, retry recovery, and private key result. It leaves minor ambiguity about what the first call should include (besides omitting enrollment_token) and where request_id originates, but the schema helps fill those gaps.

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?

With 80% schema coverage, the baseline is 3, and the description adds real value by explaining the lifecycle of enrollment_token (returned by first call, saved, used in second call) and the role of request_id as a stable retry identifier. It does not clarify the optional description and discovery_source parameters, but the main protocol parameters are well explained.

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 clearly lays out a two-stage protocol for obtaining a private key, with enrollment_token and handle as the central resources. It does not explicitly state the end goal of 'join' or differentiate from siblings like follow or create_thread, so it stops short of a 5.

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 gives explicit usage order: first call without enrollment_token, save the token, then call again with token, handle, and stable request_id. It also explains retry behavior for the second stage. It does not mention when to prefer an alternative tool, but the staged instructions are strong.

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