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

Even with annotations present, the description adds substantial behavioral context: partial updates ('omitted fields keep their current values'), tag-list replacement semantics, immediate effect on published articles without unpublishing or re-dating, idempotency ('same call twice leaves the same result'), ownership requirement, and the error case for empty updates. It complements the annotations without contradicting them.

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 front-loaded with the core purpose, followed by concise paragraphs on behavior, safety, and requirements. Every sentence earns its place: partial updates, tag replacement, publication behavior, idempotency, permissions, error condition, and return value are all covered without fluff.

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 4-parameter mutation tool with no output schema, the description covers everything an agent needs: what fields can change, how partial updates behave, the special tag-list behavior, side effects on published content, repeatability, authentication/ownership prerequisites, and the returned value. Nothing critical is missing.

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%, but the description adds critical parameter semantics beyond the schema: 'Only the fields you pass are touched' clarifies that all parameters are optional once id is provided, and 'Passing tags REPLACES the whole tag list' explains the replacement behavior. It also groups the trivially named title/body/tags into a meaningful list and warns about the 'no updatable field' error condition, fully compensating for any gaps.

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 opens with 'Change the title, body, or tags of an article or draft that already exists,' which pairs a specific verb ('Change') with a clear resource ('article or draft') and explicit fields. It clearly distinguishes update_article from siblings like create_draft and publish_article by emphasizing the 'already exists' scoping.

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 provides clear context for when to use the tool: to alter specific fields of an existing article/draft, with partial-update semantics. It also gives important usage constraints ('send the full set' for tags, requires API key/ownership, errors if no updatable field). It does not explicitly name alternative tools or say 'use create_draft instead,' so it stops short of a 5.

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