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

Annotations already mark the tool as destructive and not read-only, so the description builds on that by specifying what exactly gets altered: only the listed files, with the same URL and a reset 24-hour clock. This adds context about scope and side effects beyond the annotations, without contradicting them. It does not mention rate limits or authorization, but the key behavioral traits are disclosed.

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?

Two sentences deliver the core purpose, key behavioral fact (clock reset), scope, and a usage recommendation. Every clause earns its place; there is no fluff 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?

For an iterative update tool with no output schema, the description covers the essential facts: what it does, when to prefer it, and how scope is controlled. It does not explicitly mention the required previewId or the exact parameters, but the schema provides those. The missing details (e.g., file size limits) are already in the schema's nested descriptions. Overall, an agent gets enough context to select and invoke the tool 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 only 33%, with the top-level 'files' parameter lacking any description. The tool description mentions 'deletePaths' but does not clarify the structure of 'files' or the interplay between files, content, and sourceUrl. The schema has detailed nested property descriptions, but the description fails to compensate for the overall low coverage, leaving some parameters underspecified for an agent that doesn't read the schema deeply.

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 states a specific verb and resource ('Update files on an existing preview') and immediately distinguishes it from the alternative 'publishing a new preview.' It also clarifies the 'same URL' and the 24-hour clock reset, which are unique traits that differentiate it from other preview tools. The purpose is unambiguous and distinct from siblings.

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 explicitly advises 'Prefer this over publishing a new preview when iterating,' giving a clear when-to-use condition. It also explains the scope of changes ('Only the listed files change; pass deletePaths to remove files'), which implicitly instructs when to use the parameter. This is explicit guidance without requiring inference.

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