Na Yin sound-element

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: the endpoint path, the 10-credit Tier 1 cost, the single required input, and the interpretive distinction about the year pillar. It does not disclose whether all four pillars or only a subset are returned, but the safety and cost profile is well covered.

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 dense domain sentences followed by a compact bracketed metadata block; the essential definition is front-loaded and nothing is padded. The metadata lines are formulaic but carry useful routing information.

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?

With 12 parameters at 17% schema coverage and no output-schema burden, the description should explain the consequential optionals (boundary convention, school, true solar time) but does not. The conceptual framing is good while the operational picture an agent needs to call it correctly is thin.

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% (just timezone and timezoneOffset), and the description adds nothing beyond 'Required: date'. Material options such as dayBoundary, stageSchool, trueSolarTime, gender, includeLuck and includeFullTable change the computed result and are left entirely unexplained.

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 clearly that it returns the na yin sound-element for each pillar, and explains the 60 jiazi → 30 names mapping so the agent knows what the value actually is. It also pre-empts a common confusion by noting the year-pillar na yin is not the day master, which helps separate it from astroway_bazi_day_master and astroway_bazi_element_balance, though it does not name those siblings.

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?

The 'popular readings mean by your element' framing implies when a user would want this, but there is no explicit use-this-when / use-X-instead guidance among the many other bazi siblings (year_pillar, element_balance, day_master). Usage must be inferred from the domain description.

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