render_site

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose the full-site rendering behavior, URL return, and the one-shot vs. patch lifecycle. However, it omits the destructive overwrite behavior implied by the overwrite parameter, which defaults to true and replaces an existing site with the same slug; that detail is only present in the schema.

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 short, purposeful sentences front-load the core action and outcome, then provide essential lifecycle guidance. There is no filler, repetition, or unnecessary detail.

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 complex tool with a large nested SitePayload schema, the description gives the key selection and lifecycle context an agent needs: call once per site, then patch afterward. It is slightly incomplete because it does not directly explain that re-rendering with the same slug can overwrite an existing site, but the schema's overwrite parameter description covers that.

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 description coverage is 100%, so the payload and overwrite parameters are already well documented in the schema. The description adds only "full site" framing, which reinforces the payload meaning but does not materially extend the schema.

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?

Opens with a specific verb, resource, and outcome: "Render a full site and return its URL." This clearly distinguishes render_site from sibling add_* and update_* tools, which patch stored payloads incrementally rather than rendering a complete site.

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?

"Use this once per site" is an explicit when-to-use instruction, and the description directly names the alternatives: "prefer the add_* and update_* tools." It even explains why they are preferred, eliminating ambiguity about later edits.

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