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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral nuance beyond those flags: content replaces the whole document (not a diff), earlier Versions remain in history (explaining why destructiveHint=false), and with content the call blocks until the new Version is live. This materially helps an agent understand side effects and response timing.

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?

Four sentences, all earning their place: scope and permission first, then content behavior, then metadata fields, then combination/before-return behavior. No filler or redundancy.

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?

The definition is complete for a mutation tool of this complexity. It covers who can use it, what each field does conceptually, the versioning model, non-destructive history, and synchronous behavior. An output schema exists, so omitting explicit return-value details is acceptable.

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 description coverage is 80%, so most parameters are already documented. The description still adds meaningful semantics for the content parameter ('the whole document, not a diff') and clarifies that parameters can be used in any combination in a single call. It does not repeat the per-parameter schema details, which is appropriate.

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 ('Change') and resource ('an Artifact you own or edit'), then enumerates exactly what can be changed (content, title, description, icon) and the key behavioral consequence (publishes a new Version at the same URL). This clearly distinguishes update_artifact from create_artifact, delete_artifact, and get_artifact.

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 context: use it to modify an existing artifact you own or edit, with a choice of content-based version publishing vs metadata field changes. It also notes that any combination can be sent in one call. It stops short of explicitly saying 'use create_artifact instead if the artifact does not exist yet', but the ownership/edit prerequisite makes the intended usage unambiguous.

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