Floor plan to verdicts

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so safety is covered. The description goes well beyond that by disclosing the output contract: the mandala wall-alignment reference, the sector and deity attribution, direction-share coverage, the door pada result, findings sorted heaviest-first with remedies, and that scoring is version 2 weighted-by-importance with a band. What is missing is whether coordinate normalisation, school selection, or north reference materially change the verdicts.

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?

Length is moderate and the input requirements are front-loaded, but the prose is a dense run-on that fuses input specification, geometry conventions and output contract into two long clauses. Bullet-style separation of inputs versus results would cost nothing and improve parseability.

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 12-parameter nested-schema tool with 0% parameter documentation, the description covers the core geometry inputs and the return shape, and an output schema exists so return values need not be spelled out. It remains incomplete on six or more parameters, including the school and north-reference choices that plausibly alter the verdicts, so an agent cannot fully reason about the call from the description alone.

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 12 parameters, so the description carries real weight, and it does explain the coordinate convention (image pixels, normalized fractions, or metres), that geometry may be points or polygons, and that boundary/entrance are supplied spatially. However it says nothing about facing, school (three named traditions), declination, northReference, entranceMethod, scoreVersion as an input, or what the top-level items array is for versus rooms.

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 imperative names the exact resource set required (outline, north angle, rooms, fixtures, main door) and the second half states precisely what is computed (per-room bearing, 8/16/32 sector, mandala cell and deity, direction share, verdict, door pada, ranked findings, version-2 score). The purpose is therefore unambiguous, but the description never distinguishes this bundled plan call from the narrow siblings vastu_rooms, vastu_entrance, vastu_mandala and vastu_zones, even referencing the /vastu/rooms source inline without saying when to call this instead.

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?

There is no explicit when-to-use or when-not-to-use statement, and no alternative tool is named. Usage is only implied by the input inventory, so an agent must infer that this is the composite analysis call rather than the per-topic siblings.

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