5-Element Balance

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 new behavioral context: a deprecation contract with an exact end date, RFC 8594 Deprecation/Sunset response headers, and the credit cost. It does not discuss error behavior or pagination, but for a computation endpoint that is minor.

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?

Purpose is front-loaded in the first sentence, followed by the response-shape detail and then the deprecation warning; no sentence is filler. It does spend most of its length on output fields that the output schema already documents, which crowds out input guidance.

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?

Because an output schema exists, explaining `balance`, elementCounts and dominantElement is largely redundant, yet that is where nearly all the words go. For a 12-parameter tool with 17% schema coverage, the description leaves the agent without guidance on which optional inputs to send or how they alter the balance.

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% across 12 parameters, so the description carries the burden of explaining them — and it explains none. Optional inputs that materially change results (dayBoundary, trueSolarTime, stageSchool, includeFullTable, includeLuck, gender, longitude) go unmentioned, and no defaults or interactions are disclosed.

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 names a specific resource and scope: element balance across the whole chart, computed over all eight characters. It is clear what is being produced, though the verb is implicit (compute/return) and no sibling is named — nearby 'element_balance' tools exist in the psychological and synastry families, so a one-clause differentiator would have helped.

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 implicit guidance: the `balance` object is presented as the thing to read, and the top-level fields are flagged as deprecated with a sunset date, which steers consumers away from them. But nothing says when to call this tool versus alternatives (e.g. astroway_bazi_hidden_stems or astroway_bazi_strength), and no prerequisites are stated beyond '[Required: date]'.

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