render_site_plan

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

With no annotations provided, the description carries the full behavioral burden: it does state that the tool returns one SVG and points to the server instructions for conventions and coherence contract. However, it does not disclose side effects or permissions — e.g., whether writing via outputPath is signed, whether the operation is purely non-destructive, or what happens on invalid input/coherence contract violations.

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 sentences with no filler: the first packs verb, scope of the plan, and the input; the second states the output format and directs to the authoritative conventions. The categories listed are concrete and useful, and the pointer to server instructions keeps the text from bloating.

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 tool with an extensive nested schema, the description plus the richly documented parameter schemas give an agent what it needs to invoke correctly: expected input domain, output shape, the optional file write behavior, and the path to the required conventions/coherence rules. Return-value semantics are reasonably covered by 'single SVG', though there could be marginally more context about acceptance/validation behavior when a spec is malformed.

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%; the schema already explains both spec and outputPath in detail, including that spec can be SiteSpec object or JSON string and that outputPath is optional. The tool description adds little parameter-level insight beyond reiterating the SiteSpec input and SVG output, so the baseline 3 applies.

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 uses a specific verb ('Renders') with a specific resource ('exterior site plan'), enumerates the content types (buildings, parcels, roads, hardscape, water, landscape, barriers, trees), names the input form (SiteSpec), and states the exact output ('one SVG'). The explicit 'exterior' qualifier differentiates it from the sibling render_floor_plan without needing to open either 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?

The description gives clear context: exterior site plans from a SiteSpec, and the sibling-tool name render_floor_plan makes the alternative obvious. It does not explicitly state 'for interior layouts, use render_floor_plan' or list exclusion conditions, so it rises to 'clear context, no exclusions' but not to the explicit when-to-use/when-not-to-use level of a 5. The pointer to server instructions also guides the agent on where to read expected conventions.

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