Vastu overlay SVG

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely useful behavior the annotations cannot: transparent background, that geometry is rendered in the plan's own coordinate system for direct compositing, the layer variants, and a concrete cost of 20 credits (Tier 2). It stops short of covering output sizing limits or what the JSON variant returns, but the added context is solid.

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 visual content is front-loaded in a single dense sentence, followed by the one format-critical caveat, then a compact metadata block for group, endpoint, required fields and cost. Dense but every clause carries information; the only mild redundancy is restating the required parameters that the schema already enforces.

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?

An output schema exists, so return values need not be described, and the description supplies cost, endpoint, required inputs and the visual layer options — enough for a 13-parameter render tool. The remaining gap is that it never explains how to obtain the required coords/boundary/northAngle (presumably from the /vastu/plan input it references) or how it relates to the six vastu analysis siblings.

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 0% across 13 parameters with nested objects, so the description must carry the load and only partly does. It gives real meaning to options.layer (mandala/zones/directions) and options.format (svg returns the image itself) and repeats the three required fields, but school, entrance, entranceMethod, northReference, declination, scoreVersion, rooms/items shapes and options.width/labels are left entirely undocumented in both places.

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 verb (drawn as an SVG) and a specific resource (the Vastu plan overlay on a transparent background), and enumerates exactly what appears in the image: mandala with deities, 16 zones, 8 direction rays, verdict-coloured rooms, door pada, north arrow. It does not, however, contrast itself against the analysis siblings (vastu_mandala, vastu_zones, vastu_directions, vastu_plan), so the agent must infer that those return data while this returns an image.

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?

Usage is implied rather than stated: the frame 'to lay straight over the floor-plan image' tells the agent the intended scenario, and 'options.format: "svg" returns the image itself' signals that the default is JSON rather than an image. There is no explicit when-not, no naming of the vastu analysis siblings as the alternative when structured results are wanted, and no statement that coords/northAngle/boundary should come from the plan tool.

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