Four Transformations (四化)

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

Annotations cover the safe-read, idempotent profile. Beyond that the description discloses a real behavioral trait: seven stems agree across traditions while 戊/庚/壬 diverge, and every school reading ships in schoolVariants while `school` only switches the headline answer.

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?

Three sentences, front-loaded with the core definition, then the enumeration of the four stars, then the tradition-divergence caveat. Only minor weight from the Chinese-character parentheticals, which aid searchability.

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 an output schema present, return values needn't be described, and the important output nuance (schoolVariants) is covered. The remaining gap is that it never plainly states `date` is the birth date whose year stem is used, which the agent must infer.

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 coverage is 40%, so the description must partly compensate. It explains `school` (headline selection vs schoolVariants) well, but `date` is only implied to be a birth date via 'birth year stem', and `time`/`timezoneOffset` get no treatment in the description; timezone's own schema text carries itself.

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 a specific resource (the four transformations 化禄/化权/化科/化忌) and that they derive from the birth year stem. It also distinguishes itself from the star-placement siblings by noting this is 'the one part of Zi Wei computable without star placement'.

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?

Usage is implied: use it when you want the four transformations for a birth year stem and don't need a full chart. The `school` note gives useful context for one parameter, but there is no explicit when-to-use/when-not versus astroway_ziwei_full_chart or the palace tools.

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