update_site

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses in-place replacement, PII pre-flight scan behavior with a default and override, the two 409 error variants with distinct meanings, and that direct edits to a managed_portal would be overwritten. This goes beyond basic mutation expectations.

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 dense but every clause serves a purpose: core behavior, sibling distinction, PII behavior, and error recovery. The primary action is front-loaded, and the exception handling is organized clearly. No filler or tautology.

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 mutable update operation with no output schema and no annotations, this description covers the key decision points an agent needs: when to call it, which alternative to avoid, how parameter overrides work, and how to recover from both documented 409 states. Nothing crucial 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 50%, and the description significantly enriches the pii_check parameter by explaining its MCP default (block) and how to override with 'warn'. It also reinforces the content parameter's role. However, neither the schema nor description elaborates on filename, so compensation is good but not complete.

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 a specific verb and resource: 'Replace the HTML of an existing site in place.' It clearly differentiates from the sibling publish_html by contrasting the URL behavior and slot consumption, so an agent can distinguish it without examining 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?

It explicitly states when to use this tool over publish_html ('every time you revise a page you have already published') and why not to use the alternative. It also covers the restore_site prerequisite for the site_deleted 409 and warns against re-publishing, which would create a new URL.

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