create_account

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

With no annotations, the description fully carries the behavioral disclosure burden. It reveals that the endpoint is public, that it creates a user or logs one in, that the response is intentionally uniform to avoid user enumeration, that email sends nothing, that sms responses contain no destination number, and that verification sets JWT and refresh cookies. This is exceptionally transparent.

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?

Although lengthy, the description is dense, well-structured, and front-loaded with the core purpose before the workflow. Every paragraph and numbered step earns its place given the channel-specific caveats, and the warnings are concrete rather than generic.

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?

There is no output schema, so the description takes on the burden of explaining return fields and follow-up expectations. It covers session id, deep_link, qr_code, qr_text, sms_message, email_sent, send_required, and the verification handoff. It also covers edge cases like sms lacking a destination number and the danger of treating qr_text as a link. This is complete for an onboarding tool with this complexity.

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 schema already covers all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful channel-specific semantics: email requires confirmation and a follow-up call, sms requires a phone number with no destination in the response, and telegram/whatsapp use deep_link for rendering. It does not fully enumerate parameter formats beyond the schema, but it substantially augments the schema.

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 identifies a specific verb and resource ('Create an account-bootstrap session for agent-driven onboarding') and adds the public-endpoint qualifier. It is clear, but it does not explicitly differentiate itself from closely related siblings like create_session, start_login, or create_verification, so an agent must infer the distinction from context.

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 gives an explicit numbered agent workflow, including when to call send_account_email versus relying on deep_link, when to use render_auth_link, and when to call wait_for_account_creation. It also states the condition for calling get_current_user to distinguish new vs. returning users, and warns against using sms deep_link or handing qr_text to a link renderer.

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