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

The annotations only declare readOnlyHint=false and destructiveHint=false; the description goes beyond that by disclosing the account requirement and the full auth/session-then-retry flow, which is exactly the kind of context that cannot be inferred from the schema. It still omits the resulting state — whether the domain lands unverified awaiting a separate verification step, and whether re-adding an existing domain errors.

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 core action is front-loaded in the first sentence, with optional parameters immediately after and the auth prerequisite separated into its own labeled ACCESS block. The auth paragraph is slightly verbose (naming both a UI path and a tool fallback), but every sentence conveys actionable information.

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 mutation tool with annotations covering the safety profile and no output schema, the description covers the prerequisite and parameters but leaves the post-call lifecycle unexplained — what the add returns, and which sibling (start_domain_verification, verify_domain, connect_dns_provider) an agent should call next. That next-step linkage is the main gap given the dense domain-verification sibling set.

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 description coverage is 100% and the enum values for verification_method are enumerated in the schema, so the structured data already carries the parameter burden. The description adds only the relatively weak signal that email-sending intent and verification method are optional (the schema's required list already shows this), which is baseline-level value.

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 states a specific verb and resource ('Add a new domain') and adds the purpose clause 'to verify ownership', so an agent knows exactly what is being created. It does not, however, distinguish itself from the many verification siblings (start_domain_verification, verify_domain, check_domain_verification) that also operate on domains, so an agent must infer which one actually performs the add step.

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 ACCESS block gives concrete usage context: a Proof account is required, the client must be authenticated (via /mcp or start_login), and the tool must be re-invoked after a session opens. That is a clear precondition and sequence. What is missing is routing guidance — nothing says whether verification happens here or requires a separate start_domain_verification/verify_domain call, and no exclusions are stated.

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