render_site_plan

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

No annotations are provided, so the description must carry the burden. It mentions 'Returns one SVG' which indicates the output format. It also references 'server instructions for conventions and the coherence contract', implying there are rules the agent must follow, but it does not disclose what those conventions are. It doesn't mention side effects, permissions, or failure modes. The behavior is fairly predictable as a rendering operation, but the coherence contract reference is vague and could hide important constraints.

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 concise, two sentences, and includes the core purpose. It mentions the output format and references the server instructions, which is a useful pointer but keeps the description short. It is somewhat front-loaded with the action and input, but the reference to 'coherence contract' is a bit vague, which is a minor deduction.

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?

Given the complex nested schema, the description is quite brief and relies heavily on the schema and external 'server instructions'. It doesn't explain how to handle coordinates, units, or style defaults. The output is described as one SVG, but no details on scale, viewbox, or error behavior. The description is sufficient for a basic understanding but leaves a lot to the agent to figure out from the schema and external instructions.

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% with the spec parameter having a description and properties, but the description adds little beyond the schema. The tool description mentions the SiteSpec and its element types, but doesn't clarify the required fields (unit, scale, theme) or the optional outputPath behavior. The spec description in the schema is generic ('See this schema's properties for every field'), and the tool description doesn't help the agent construct valid SiteSpec. The outputPath parameter is briefly described in the schema, but the tool description doesn't reinforce defaults or paths.

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 clearly states the tool renders exterior site plans from a SiteSpec, enumerating the element types (buildings, parcels, roads, etc.) and notes it returns one SVG. This distinguishes it from sibling render_floor_plan, which presumably handles interior plans. The verb 'renders' plus the resource 'site plan' and input 'SiteSpec' is specific and unambiguous.

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 states when to use it (to render exterior site plans) but does not explicitly discuss when not to use it or explicitly route to siblings. The noted sibling render_floor_plan is implied to be for floor plans, but no direct comparison or exclusion is given. Some guidance is provided via the element list, but not explicit alternatives.

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