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

Goes well beyond the annotations (readOnly=false, openWorld=true, idempotent=false, destructive=true) by disclosing the async session lifecycle, the correction/re-issue flow, the preview-execution risk, the data-privacy implication that the script 'may send visitor data to that provider,' and that publication is a separate step. Rich operational context an agent needs before invoking a destructive mutation.

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-loaded with the core purpose and scoped action, and dense with useful detail across seven sentences. It is appropriately sized for a complex asynchronous destructive tool, though the sentence about the Replo agent using 'its normal tools and connected integrations' is somewhat generic and could be trimmed.

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?

With no output schema, the description carries the full burden and does so: it explains the full lifecycle (start operation, poll get_agent_session, apply corrections, publish separately), preconditions, and side effects. Nothing an agent needs to call this correctly 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%, so the parameters are already documented (siteId from list_sites, sessionId continuation semantics). The description adds meaningful guidance on what the instructions field should contain ('Name the provider, identifiers, and requested behavior') and reinforces the sessionId reuse pattern, going modestly beyond the schema baseline.

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 set of verbs (add, change, remove), a specific resource (user-requested analytics or marketing script), and a specific location (the selected site's root layout). This clearly distinguishes it from siblings like update_site, update_site_metadata, and update_site_navigation without needing to open 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 names alternatives and the conditions that select them: poll get_agent_session for the async result, use publish_site separately to make changes public, and re-invoke this same tool with sessionId for corrections. It also states a precondition ('Requires a provisioned site'), leaving little to inference.

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