Generate Vastu Report (PDF or HTML)

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

Annotations only say readOnly=false, destructive=false, idempotent=false, openWorld=true; the description adds material beyond that — a concrete credit cost with a budget-impact warning and an instruction to confirm before invoking, plus the storage side effect (pdf is stored and returns a url, html/markdown are not stored). It does not mention rate limits or what happens to a previously stored PDF on re-run.

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?

Front-loaded with the deliverable and its contents, then the input reference, then language behavior, then a clearly demarcated metadata block for endpoint/required/cost. Dense but nearly every clause carries information; the contents enumeration is the only mildly long part.

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?

Output schema exists, so return values need not be explained, and the cost/storage/format behavior is well covered. However, for a 15-parameter tool with 7% schema coverage and nested items/rooms/whitelabel objects, the description leaves the majority of the input surface undocumented beyond the '/vastu/plan input' pointer.

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?

With 15 parameters and only 7% schema description coverage, the description must carry most of the parameter burden, but it only touches format (default pdf), school (sixteen-zone) and the general 'takes the /vastu/plan input' pointer. It says nothing about items, rooms, facing, entrance, declination, northReference, entranceMethod, scoreVersion or the whitelabel object, and its claim that texts are Ukrainian/English with English fallback conflicts with the schema's 21-language enum, which could actively mislead an agent.

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 (generate a report) and resource (the /vastu/plan Vastu reading) and enumerates the document's actual sections — cover with school and north, score band, plan with mandala, findings ordered heaviest first, remedies with effort/reversibility. This is enough to distinguish it from the sibling analysis tools (vastu_plan, vastu_zones, vastu_mandala) that supply inputs rather than a finished document.

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?

Gives a clear invocation context: it consumes the /vastu/plan input, defaults to PDF, and the bracketed block explicitly warns it is Premium at 5,000 credits (~50% of a free monthly budget) and says to confirm with the user first. The gap is that it never names an alternative sibling (e.g. the non-report render/analysis tools) or states when NOT to produce a report.

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