Qi Men Dun Jia Chart

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

With readOnlyHint=true already covering the safety profile, the description still adds substantive behavior: deterministic chart rules (天禽/中宫寄干 follow 天芮, 小寒 uses 二八五), a well-defined solar-term boundary policy across timezones at the same instant, and an explicit no-defaults/no-backfill rejection policy. What is missing is any hint of what the response contains or its size, which matters given there is no output schema.

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 sentences, front-loaded with purpose, with no filler. But the body crams in implementation minutiae (天禽 following 天芮, 小寒's 二八五, ten-minute segmentation for a non-traditional product) that do not help an agent select or invoke the tool, while the genuinely decision-relevant parameter disambiguation is absent.

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 22-parameter, five-required, no-output-schema tool with zero schema descriptions, this is not enough: the ambiguous boolean pairs and conditional branches (birth requires hour precision, lunar requires full date fields, current/event require question) are enforced by the schema but never explained. An agent can get the top-level shape right but will likely guess wrong on several optional parameters.

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 0% across 22 parameters, so the description must carry the load, and it only gestures at categories (timezone, calendar, precision, coordinates) already visible from the required list. It does not disambiguate the two near-identical booleans use_true_time vs use_true_solar_time, nor explain apply_dst, is_leap_month, focus_area, locale, or the current/event/birth cast_time_source semantics.

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 verb and resource (计算…奇门盘) and pins down the exact school/variant (时家转盘拆补), plus the underlying 三元定局 rule set. An agent can tell this apart from the other chart siblings (bazi, ziwei, qizheng, vedic) by name alone, though the description itself never contrasts with them 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?

Usage is implied through hard prerequisites: it lists the input dimensions that must be present (source, precision, calendar, time, timezone, coordinates) and states it rejects rather than backfilling. That is genuinely useful gating guidance, but there is no statement of when an agent should pick qimen over a sibling divination tool, nor any exclusion cases beyond missing-input rejection.

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