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

Annotations only give a coarse safety profile (readOnlyHint=false, destructiveHint=true, non-idempotent), while the description discloses the consequential traits: new-service mode is a PAID monthly per-number subscription billed at staff activation, the two-call confirmation gating that submits nothing on the first call, that resubmit is free and ungated, and that zero assigned numbers auto-cancels the service. It also explains token retry safety, none of which the annotations convey.

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?

Purpose and mode selection are front-loaded, then billing, gating and prerequisites follow in a logical order. It is dense rather than padded, though the length is substantial for a single tool and a few billing/auto-cancel details could be tightened.

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 billing-affecting mutation with no output schema, the description covers what an agent needs: prerequisites, mode selection, cost implications, the confirmation round-trip, and the return contract ('pending verification id, or a readable error when validation fails'). Nothing material is left for the agent to guess.

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 goes beyond it by stating the cross-parameter mode constraint and adding a qualifier the schema omits — DIDs must be 'of the same country and DID group type as the emergency requirement'. It also frames confirmation_token as a preview-then-confirm handshake rather than just a field.

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 first sentence states a specific verb and resource ('Submit an emergency verification for staff review'), then splits the tool's two distinct modes (new service vs. resubmit) with the exact parameters that select each. An agent can distinguish this from siblings like create_address_verification or create_regulation_upload_link without opening any schema.

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?

Explicit when-to-use for each mode, including status preconditions ('allowed when the service is in new, changes required or active status') and mandatory pre-steps ('BEFORE calling, run list_emergency_requirements ... fill any missing identity fields with update_identity'). It also names the alternative route when proofs are missing (create_regulation_upload_link with purpose "emergency"), which is genuine routing guidance.

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