Update account settings

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

Annotations only flag the tool as destructive, non-read-only and idempotent; the description adds substantial context beyond that: partial-update semantics ('Only the fields sent are changed'), the exception that content_rules is replaced wholesale, 412 behavior on if_match mismatch, reason being persisted into the revision, dry_run writing nothing, and that loosening a guardrail may block on owner confirmation. These are exactly the side effects an agent cannot get from the structured fields.

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 opening sentence is a single run-on enumeration of every parameter and every content_rules sub-key, almost all of which is already in the schema at 100% coverage, so that bulk does not earn its place. The behavioral sentences that follow (dry_run, if_match, guardrail confirmation) are the valuable part and are appropriately placed, but the structure would be stronger if the field inventory were trimmed.

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 12-parameter, nested, destructive mutation with no output schema, this covers the hard parts: merge semantics, guardrail approval gating, preview mode, optimistic concurrency and the 412 response. Minor gaps remain — no pointer to preview_account_settings as the non-writing alternative or to revert_account_settings_batch for undoing a bad change — but an agent has enough to call it correctly.

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, but the description earns more by explaining semantics the schema does not: whole-replacement of content_rules versus per-field merge for everything else, the concurrency contract behind if_match (412 rather than overwrite), and the audit role of reason. It re-lists field names and limits that the schema already documents, which dilutes the added value slightly.

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 an account's ...') and enumerates the exact mutable fields, so the agent knows precisely what domain this touches. It only partly differentiates from siblings: it references get_account_settings for the etag but never contrasts with apply_account_settings or preview_account_settings, which overlap heavily.

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 closing sentence gives an explicit trigger ('Applies when the user asks to change voice, posting times, review mode, auto-reply or content rules'), which is a genuine when-to-use statement. It stops short of stating when NOT to use it or naming the alternative tools (apply_account_settings, preview_account_settings) that an agent would otherwise have to infer from the sibling list.

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