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

Annotations only declare the safety profile (destructive, idempotent, non-readonly); the description adds the behaviors that actually matter here: shallow-merge semantics, merged-result validation against the content_type schema, fuzzy title resolution with error-on-ambiguity, 308 redirect on rename, ownership verification via parent site user_id, and slug-collision failures. This is far beyond what 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?

A single dense paragraph, but it is front-loaded with the core action and every clause earns its place (resolution, patch semantics, validation, image handling, ownership, errors). It is long relative to typical definitions, though for a nested-object mutation with no output schema the density is defensible rather than padded.

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?

Covers the entire call path an agent needs: how to resolve the item, what patch fields do, merge/validation rules, image-field gotchas, and failure modes. With no output schema, the description also carries return-adjacent context through its error behavior, leaving no obvious gap.

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 high (83%), so the baseline is 3, but the description adds real semantics: the image field object shape and the bare-URL coercion rule, the shallow-merge warning that re-sending alt is required, the validation and rejection behavior when content is patched, and the conditional requirement linking site_id/content_type to slug/title resolution.

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?

States a specific verb and resource ('Update fields on an existing content item') and immediately clarifies scope via the identification paths, which separates it from siblings like add_content_item, delete_content_item and publish_content_item. An agent can tell what the tool mutates without opening the 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?

Gives clear conditional guidance on resolution ('Identify it by item_id, OR — when you only know its name — by site_id + content_type + (slug | title)') and states the 'at least one field is required' constraint. It stops short of naming alternative sibling tools or when-not-to-use conditions, so it sits below explicit routing.

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