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), so the description only needs to add context. It does add two useful facts: the cost tier (10 credits, Tier 1) and that the computation is keyed to the *solar* year, which is a real behavioral subtlety. However it omits edge cases (birth dates near the Chinese New Year boundary, effect of the time/timezone inputs) and does not say what the returned group field contains.

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 the core computation front-loaded, followed by group/cost metadata tags. No filler or repetition, though the bracketed metadata lines are boilerplate rather than description content.

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 simple birth-data calculation this is roughly minimum viable: the required inputs are implied, annotations cover safety, and an output schema exists so return values need not be described. The gap is input guidance for the seven optional parameters, which are neither explained nor flagged as ignorable for this particular computation.

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 44% across 9 parameters. The description conceptually covers the two required inputs (date via "solar-year digit sum", gender) but says nothing about the seven optional plumbing parameters (time, timezone, timezoneOffset, solarYear, fields, precision, language) or how solarYear relates to date. With low coverage the description should compensate and it does not.

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 computed artifact ("Personal Kua number") and its derivation ("solar-year digit sum + gender"), plus the output grouping (East/West). It is clearly not the same as bagua, flying_star, or annual_stars, though it does not name a sibling to distinguish itself from lucky_directions, which consumes the same grouping.

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?

"Maps to East/West group for direction work" implies the downstream use case, so usage is inferable but never stated. There is no explicit when-to-use, when-not-to-use, or pointer to the sibling (lucky_directions) that consumes this output.

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