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

Annotations already mark the tool as non-read-only and destructive; the description goes much further by disclosing that a successful update sends a new invitation, revokes old links, generates a new signeeId, and invalidates previously read IDs. It also surfaces the 60-minute cooldown and the concrete 403 failure modes, giving the agent a realistic model of side effects.

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 description is longer than average, but every sentence carries a precondition, side effect, or constraint. The operational prerequisite is front-loaded, and the numbered constraint list makes the 403 conditions scannable and actionable.

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 with no output schema, the description fully covers preconditions, failure modes, cooldown behavior, and the post-update invalidation of signeeId. The agent has everything needed to call the tool correctly and to avoid stale-state mistakes.

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 input schema covers all parameters with descriptions, and the description adds crucial semantics: signeeId must come from get_document and becomes stale after the update; email/phone can only change an existing contact method, not add a new one; and updateCooldown from get_document should be checked before retrying. This goes well beyond the schema's basic field descriptions.

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: 'Update contact details for one or more signees who have not yet signed.' It immediately scopes the operation to not-yet-signed signees and gives the canonical use case ('fix a wrong email'), which distinguishes it clearly from update_draft and the read-only get_document.

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?

It explicitly directs the agent to call get_document first to read signeeId and signatureStatus, and to check updateCooldown before invoking. It also gives strong when-not guidance: signed signees and completed documents cannot be changed, contact methods can only be changed not added, and breaking any constraint results in a 403.

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