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

Annotations already declare this as destructive and not read-only, and the description adds important behavioral detail beyond them: the tool is proposed rather than performed directly, returns status='confirmation_required' with an action_id and plan_token, and only writes after confirm_action. It also explains that empty strings remove a channel, which is a meaningful mutation behavior. It does not cover permission requirements or validation constraints, so it is strong but not exhaustive.

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 dense but front-loaded: it first states the scope, then the field semantics, then the critical confirmation workflow. Every section earns its place for a 10-parameter mutation tool, though the long enumeration of site surfaces and channels makes it slightly heavy to scan.

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 destructive, multi-field mutation with no output schema, the description supplies the essential workflow (propose→confirm, action_id, plan_token), removal semantics, and channel formats. It is nearly complete, missing only explicit notes on permissions, validation rules, or what happens to unspecified existing values beyond the empty-string removal case.

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?

With schema description coverage at only 10%, the description carries most of the parameter burden and does so well: it names every channel field and clarifies formats such as Telegram accepting @handle or link, Viber and WhatsApp requiring numbers, and empty strings removing a channel. It does not explain the expected format for opening hours or address, leaving a small gap.

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 uses a specific verb and resource: change the site's contacts everywhere they appear, then enumerates the exact surfaces (header, hero call button, contacts block, lead form, footer, phone bar messenger buttons). This is far more precise than a generic update tool and lets an agent distinguish it from sibling site-content tools such as website_update_text.

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 description clearly establishes the context for use: updating contact channels across the site, with empty strings removing a channel, and it explicitly routes the agent into the propose→confirm workflow via confirm_action. It does not explicitly compare against alternatives like website_update_text, but the field list and site-surface scope make the intended use clear.

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