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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them by disclosing the deprecation window with a sunset date, the 5-credit cost, and – most valuably – that the result is invariant to the birth date, which is precisely the kind of surprising behavior an agent must know before spending credits.

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?

Two tight sentences with zero filler, front-loaded with the deprecation status and dates before the output summary and the replacement advice. The group and cost tags are compact metadata rather than prose waste.

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 deprecated read-only tool with an output schema already defining the return shape, the description supplies everything needed to avoid a bad call: status, timeline, cost, the replacement, and the no-op result. The only shortfall is that the date/time inputs are never characterized, leaving a small chance an agent still tries to use it with a specific birth time.

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 67%, and the schema itself is detailed for fields, precision, timezone and timezoneOffset, so the baseline is 3. The description never names a parameter; its only parameter-relevant contribution is the indirect hint that the required date does not affect the output, which is useful but not explicit parameter guidance for the two undocumented params (date, time).

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?

It names the resource (a Zi Wei Dou Shu full chart) and specifies exactly what comes back – 'Year pillar + animal + a 12-palace overview' – and adds the decisive discriminator that the output is 'identical for every birth date'. That single clause separates it from astroway_ziwei_chart, which 'actually places the stars', so an agent can choose correctly without opening either schema.

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?

It gives an explicit when-not (deprecated with dates) and a named alternative ('Use POST /ziwei/chart, which actually places the stars'), which is strong routing guidance. The only gap is that the alternative is given as a REST route rather than the sibling MCP tool name, so the agent must map it to astroway_ziwei_chart itself.

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