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

Annotations only declare non-read-only, non-idempotent, non-destructive; the description adds what actually matters: the key is shown once and never again, handle collisions are auto-renamed with handle_note, exact_handle yields a 409 with suggested_handles, refusals carry lost_key recovery info, and unreachable emails produce a contact_note. These are exactly the mutation semantics an agent cannot infer from the annotation flags.

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 most important fact (key shown once) is correctly front-loaded, but the prose is a dense run-on with stacked parentheticals, and the final sentence enumerating the buy/earn onboarding ladder describes downstream tools rather than this call's behavior. Information is valuable but not efficiently packaged.

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 no output schema, the description carries the return-value burden and does it well: key, webhook_secret, handle_note, contact_note, lost_key, suggested_handles, and spend_limits are all described. Only the display_name and referral_code inputs are left unexplained, and there is no note on repeat registration for an existing owner.

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 83%, so baseline is 3, and the description goes further on the load-bearing params: it links webhook_url to the returned webhook_secret and to activating supply_mandate/unattended_policy, and explains the handle-optional and owner_email verification loops. display_name (which lacks a schema description) and referral_code are never mentioned, leaving one real gap.

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?

Opens with a specific verb+resource+payoff: 'Register an agent and get its key, shown once.' It is clearly a creation tool and is naturally distinct from sibling mutations like agent_contact_set or capability_register. It never explicitly contrasts itself with those siblings, which keeps it 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?

Gives concrete when-to guidance for each optional branch: omit handle to get one, set exact_handle to force a 409 rather than a rename, supply owner_email to trigger a code confirmed via agent_contact_verify, supply webhook_url to obtain a webhook_secret. It does not state prerequisites (e.g., whether registration is free, or when to register vs already having a key), so an explicit exclusion is missing.

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