Generate Relocation Report (PDF or HTML)

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

Annotations already cover safety (non-destructive, open-world, non-idempotent), so the description's job is to add what they cannot — and it does: a 5,000-credit cost that consumes roughly half a free monthly budget, an explicit instruction to confirm with the user first, the default A4 PDF vs HTML behaviour, and the side-by-side comparison that appears when more than one place is supplied. These are exactly the traits an agent needs before spending credits on a generation call.

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 core offer and tightly packed — the bolding of 'which planets changed house' and the parenthetical about diffing versus two tables are efficient emphasis. The trailing [Group]/[Endpoint]/[Required]/[Cost] block is scannable metadata rather than prose bloat. The single long per-place sentence carries many clauses, which is dense but each earns its place.

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 six-parameter, credit-consuming report generator with an output schema already present, the description covers the essentials: inputs consumed, document structure, format selection, and cost risk. Gaps remain around whitelabel branding, category subsetting, and whether generation is synchronous — but with an output schema handling return values, nothing critical to a correct first call is missing.

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 only 17%, so the description must carry the load, and it partly does: it establishes the five-location cap and that one chart drives everything. But the numeric values it states ('300 km', '19 life categories') read as fixed facts rather than as the tuneable orbKm (100–3000) and categories parameters, and language and whitelabel go entirely unmentioned. The chart's own nested fields are well documented in the schema, which keeps this at an adequate 3 rather than lower.

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 opens with a concrete verb and resource ('Compare up to five places for one birth chart') and enumerates exactly what the generated document contains: relocated ASC/MC with signed shift, planets that changed house (explicitly diffed), ACG lines within 300 km, and 19-category scores. That is far more precise than the title alone. It never names the lighter sibling astroway_geo_relocation or astroway_geo_acg_line_report, so the boundary between 'buy the report' and 'get the raw relocation data' is left to inference.

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?

Use context is clear ('Compare up to five places for one birth chart') and the output-format switch is spelled out ('add `?format=html`'), plus the required-parameter and credit warning give the agent operational guardrails. The premium warning telling the agent to confirm with the user before invoking is a genuine usage constraint. Missing is any explicit when-not or routing to a cheaper sibling for a single-location lookup.

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