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

Annotations only declare the generic write/destructive/openWorld profile; the description adds substantive behavior: confirmation email flow with double_opt_in, immediate welcome email, and autoresponder triggering — all side effects an agent must anticipate. It also discloses the underlying endpoint (POST /api/v1/sign_up/generate).

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?

Front-loads 'WRITE:' and the core action, then layers the email side effects and the parameter hint. Four tight sentences with no filler; every clause carries operational meaning.

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 7-param mutation with no output schema, it covers side effects, consent conditions, input provenance, and the endpoint. The only untouched item is return_contact semantics, which the schema already documents adequately.

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%, so the baseline is 3; the description still adds value by explaining that `fields` is keyed by user_tag sourced from robly_list_fields, which ties the parameter to another tool. The email-sending flags are restated from the schema rather than extended.

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 an explicit verb+resource and mode ('WRITE: add a new subscribed contact'), and adds the re-submit case. It is clearly differentiated from siblings like robly_add_contact_to_list and robly_update_contact by describing sign-up-form semantics rather than list ops or edits.

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 a real consent guardrail ('Only subscribe people who agreed to receive email') and points to robly_list_fields / robly_list_sub_lists as prerequisites for building inputs. It stops short of explicitly saying when to prefer robly_update_contact or robly_add_contact_to_list instead, so routing is inferable rather than stated.

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