start_domain_verification

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

Annotations already establish readOnlyHint=false and destructiveHint=false, so the write profile is covered; the description adds genuine value beyond them by disclosing the auth prerequisite (Proof account + PROOF_API_KEY + server restart) and that the call emits DNS/HTTP instructions for the customer. It omits expiry/idempotency behavior and whether a duplicate call for the same domain creates a second record.

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-loaded: the core action and its output come first, followed by the access constraint as a clearly separated block. No filler sentences, though the ACCESS paragraph is slightly verbose for what it conveys.

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, and the description compensates by stating what comes back (DNS/HTTP instructions) and by covering the account/API-key prerequisite that would otherwise block a call. What remains thin is the workflow context — no pointer to check_domain_verification/delete_domain_verification for the follow-up states a B2B flow implies.

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 schema already documents domain, customer_id, and the manual_dns/http_file enum. The description only implicitly maps 'DNS/HTTP instructions' onto the two verification methods and adds no format, default, or constraint detail beyond the schema — the baseline 3 applies.

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?

States a specific verb+resource ('Start a B2B domain verification') and adds what it produces: 'Creates a verification record and returns DNS/HTTP instructions.' That separates it from read-side siblings like check_domain_verification or get_verification, but it never names the near-identical siblings (start_domain_email_verification, start_user_domain_verification, verify_domain), so differentiation still requires reading the tree.

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 concrete precondition ('needs a Proof account. Set PROOF_API_KEY and restart this server, then call this tool again') and an explicit exclusion ('start_login does NOT open this tool'), which is real routing guidance. It does not say when to prefer this over the other domain-verification starters or which tool to call afterward to poll status.

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