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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds materially new behavior: partial-update semantics, all-or-nothing atomicity ("A refused call changes nothing"), delayed propagation ("shows a change within a few minutes"), replacement-not-merge semantics for accounts and review sources, and the coupling constraint that leaving a campaign requires accounts in the same call. The embed_code_changed caveat even explains the downstream human action required on the user's site, which is exactly the kind of consequence an agent would otherwise miss.

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 with the core action and the key rule ("send only what changes"), then organized by widget type, which is the right structure for a type-dependent tool. The middle enumeration of social-widget fields is a long, clause-heavy run-on sentence that takes effort to parse, but virtually every clause carries usable information rather than repetition.

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 7-parameter destructive mutation with a nested settings object and no output schema, the description covers the hard parts: partial updates, atomicity, per-type field applicability, list-replacement ordering, campaign coupling, and propagation delay. The only gap is the shape of the response beyond the mentioned embed_code_changed flag, which is a minor omission for an otherwise thorough definition.

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, and the description goes beyond it: it establishes that accounts and source_ids replace the entire current list in order, that the first account of a social widget's service supplies the header, that settings names come from get_widget and values from list_widget_types, and that campaign_id pairs with the "hashtag-campaign" filter_type. These are real semantic constraints the schema only hints at, though the ordering/header rule could be stated even more operationally.

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?

Opens with a specific verb+resource ("Changes a widget") and immediately differentiates itself from create_widget/delete_widget/copy_widget by framing the operation as a partial update ("send only what changes"). It further disambiguates applicability by widget type (social vs review) and by which fields each type accepts, so an agent knows exactly what category of operation this is.

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 clear operational guidance: send only changed fields, a refused call is a no-op, and the widget-type branching tells the agent when each parameter group applies. It also routes to sibling tools for prerequisite data (get_widget settings, list_widget_types for allowed values, list_accounts, list_review_sources, list_campaigns) and to get_embed_code for the post-update site step. It stops short of explicit when-not-to-use exclusions against copy_widget or update_review_source, which keeps it at 4.

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