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

Beyond the annotations (destructive, openWorld, non-idempotent), the description discloses that this starts an asynchronous internal-agent operation requiring polling, that source edits may execute in the site preview, and that scripts may send visitor data to a third-party provider post-publication. These are consequential behavioral facts an agent would otherwise not know.

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 critical facts (what changes, async model, polling, publication separation) are front-loaded in short sentences. A couple of sentences, notably 'The Replo agent uses its normal tools and connected integrations to implement and verify the requested changes,' add little operational value and dilute an otherwise tight definition.

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 still covers the async lifecycle (sessionId continuation, get_agent_session polling), the preconditions, the blast radius (preview execution, visitor data egress), and the follow-up step (publish_site). Nothing an agent needs to invoke 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 baseline is 3; the description goes further by telling the agent what to put in instructions ('Name the provider, identifiers, and requested behavior') and reinforcing the sessionId continuation contract ('same tool with its sessionId and unchanged target'). That adds actionable meaning beyond the schema's field-level text.

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 opening sentence gives a specific verb set ('Add, change, or remove') and a precise resource ('analytics or marketing script in the selected site's root layout'), which cleanly separates it from siblings like update_site_metadata, update_site_navigation, and publish_site. An agent can identify the operation without opening 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?

Explicit routing is provided: poll get_agent_session for async progress, call update_site_tracking again with sessionId for corrections, and use publish_site separately to make changes public. It also names 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.