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

Annotations only declare destructive/non-idempotent; the description adds far more: atomicity ('every file goes live or none does'), whole-site replacement semantics (unsent live files are removed), hard limits of 200 files and 4 MB, a required root index.html, quota_exceeded on site-limit overflow, content-type refusals for sensitive fields without a paid custom domain, and the draft fallback with published=false. All of this is consistent with destructiveHint=true and gives the agent the failure surface it needs.

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?

Front-loads the core action and the create/update fork in the first two sentences, then layers constraints. It is dense and long, but nearly every clause carries a real operational constraint; a slightly tighter grouping of the quota/policy rules would improve scanability.

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 destructive, non-idempotent mutation with no output schema, the description covers limits, failure modes, and policy refusals, plus hints at the response shape (published=false, quota_exceeded). It does not describe the overall return structure or what an update does to a site's deployment history beyond the message field, leaving a minor 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?

With 80% schema coverage the baseline is 3, and the description earns above that by tying semantics together: name is required only when creating, subdomain is derived from name unless given, and siteId omission flips the mode. It adds little on files, message, or encoding, which the schema already covers.

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 ('Uploads files and makes them live') with concrete scope ('{subdomain}.runlitehost.com address'), and immediately splits the create-vs-update behavior on siteId. An agent can distinguish this from siblings like upload_files, start_upload, or update_site without opening any 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?

Explicitly says 'Without a siteId it creates a new site ... with one it updates that site', giving clear when-to-use branching. It does not name sibling alternatives (e.g. upload_files or publish_upload) or say when not to use full deploy versus a partial update, so it stops short of the top band.

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