BaZi Chart

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

Beyond readOnlyHint=true, the description discloses a significant behavioral constraint: the server never reads the current time, and even current_snapshot must carry an explicit caller-captured timestamp. It also discloses the differences in output between birth and direct-pillars modes (no date/大运 back-inference), which is real behavioral context an agent could not get from annotations.

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 dense clauses, front-loaded with the core action, then the no-server-time rule, then the per-mode return contract. No filler sentences; density is justified by a 21-parameter tool. The semicolon structure is readable and each clause earns its place.

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 complex tool with no output schema and sparse schema descriptions, the description does useful work by summarizing what birth mode returns and what direct-pillars mode omits. Still, key semantics — the required is_male flag, the zi-hour split convention beyond a mention, and calendar/leap-month handling — remain unexplained, leaving the definition short of fully self-sufficient.

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?

With 21 parameters and only 10% schema description coverage, the description carries most of the burden. It explains the input_mode split, cast_time_source semantics, and the DST/true-time intent, but leaves many parameters (is_male, split_zi_hour, calendar_type, is_leap_month, latitude/longitude pairing rules) undocumented in either place. Partial compensation, not full.

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 opens with a concrete verb+resource: computing the BaZi main chart (八字主盘), and immediately distinguishes the two input modes (explicit civil time vs. direct four pillars). It also makes clear this is the base chart calculator rather than one of the analysis siblings (analyze_wealth, compare_charts), though it never names a sibling explicitly.

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 mode-level guidance: birth mode returns boundary/DST/true-time data, while direct-pillars mode does not back-infer calendrical dates or Dayun, and it warns that current_snapshot requires a caller-supplied time. However, it gives no guidance on choosing this tool versus the many bazi.* siblings (analyze_*, prepare_naming_context, compare_charts), which is left entirely to inference.

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