Shao Zi Life Number

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

Annotations only declare readOnlyHint=true, so the description carries most of the burden and does add real context: no records are saved, the computation is pinned to a product-frozen modern table, and the tool explicitly disclaims being the unique Shao Zi canonical rule. The rejection behavior for direct four-pillar input and the fixed use of chart_trace.input.corrected_local_time are behavioral facts not derivable from annotations. Missing is any statement about response shape or failure modes beyond the one rejection case.

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?

It is a single front-loaded block that opens with the computation basis and then adds constraints and exclusions, with no filler sentences. The sentences are very long and packed with domain jargon (河洛 v4, 晚子时, 三元边界), which hurts scannability, but every clause carries information rather than repetition.

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 read-only computation tool with no output schema, the description covers inputs, engine dependencies, exclusions, and disclaimers well. It does not describe what the returned 命数 actually looks like, nor does it explain the question/focus_area parameters that a caller would reasonably assume affect output. Those two gaps are what keep it at minimum-viable rather than complete.

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%, so the description must compensate, and it partially does: '当前用户本人资料或其命盘记录' maps directly onto the use_profile vs record_id oneOf in the subject object. However, notes, locale, question, and focus_area receive no mention at all, leaving four of five parameters unexplained in both schema and prose. The subject-level clarification is valuable but insufficient given zero schema documentation.

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 resource and operation — computing 人命数 (human life number) from the user's own profile or a stored chart record, reusing the bazi main chart and Heluo v4 calendar rules. It is distinguishable from the sibling divination.preview_heluo by the explicit dependency on that engine plus the frozen modern teaching table. It stops short of a crisp one-line statement, burying the verb inside a long clause chain.

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 states the accepted input sources (the current user's own profile or their chart record) and gives an explicit refusal condition: direct four-pillar input is rejected because the three-yuan year cannot be determined. It also enumerates what the tool will not produce (流年声序, 六亲, 阶段运势, 6144 条文), which effectively scopes usage. It does not name a sibling to use instead when the request is rejected.

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