Group Chart Compare

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description goes further by disclosing the exact evidence classes returned (day master, day branch, cross-chart stems/branches, shensha) and by explicitly enumerating what is deliberately NOT computed — scores, rankings, role assignment, support/pressure chains, uncomputed annual-fate points. That negative-space disclosure is genuinely useful and not derivable from the 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?

A single dense sentence that front-loads the action and scope before the return/negative clauses. Every clause carries information, though the run-on structure makes it harder to scan than a short bulleted split between 'does' and 'does not do'.

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 no output schema, the description carries the burden of describing return values, and it does so at the level of evidence categories plus an explicit exclusion list. The remaining gap is that scene_type's three enum values and scenario_label's effect on output are never explained, which leaves a caller guessing about optional inputs.

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 carry parameter meaning. It does clarify the cardinality of members (2–8) and the key semantic that at most one entry may be a self profile, which maps directly to the use_profile field. It says nothing about alias, role_label, scene_type, or scenario_label, leaving half the surface undocumented.

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 (structural comparison of all unordered member pairs across a group of 2–8 bazi records) and pins the scope to the current user's own records. '全部无序成员对' plus the 2–8 range effectively separates it from the pairwise sibling bazi.compare_charts, though that sibling is never named 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?

The membership constraints (2–8 members, at most one self profile) imply when the tool applies, and the negative-space list tells the agent what not to expect from it. However, there is no explicit routing guidance such as 'use compare_charts for exactly two people' or when scene_type should be set, so the agent must infer the boundary.

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