calculate_lunar_return

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior. The description adds meaningful behavioral context beyond annotations: server checks run before successful results, verification references identify the complete checked calculation, psychological interpretations are not checked, and summary mode truncates nested rows while preserving scalar lists.

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?

The description is dense but front-loaded with the tool's purpose and result content. It is somewhat long but most sentences carry operational guidance; a small amount of repetition around verification and detail_level keeps it from a 5.

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 14-parameter tool with no output schema and low schema description coverage, the description covers the main output families and verification workflow well. It is still incomplete because multiple input parameters are undocumented and there is no explanation of the return structure beyond a high-level list.

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 only 14%, so the description must compensate, and it explains key parameters such as target_year, target_month, target_day, residence_location_id, house_system, detail_level, and include. However, it leaves several parameters unexplained, including day, fold, hour, year, month, minute, and location_id, and does not clarify how location_id differs from residence_location_id.

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 states a specific verb/resource implicitly through its name and explicitly describes the output: a lunar return chart for target_year and target_month, including return moment, positions, angles, cusps, aspects, and natal overlay. It is clear what the tool produces, but it does not explicitly distinguish calculate_lunar_return from the sibling render_lunar_return_chart.

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 explicit prerequisites: residence_location_id must come from search_birthplace, house_system must be placidus or whole_sign, target_day resolves two returns in a month, and verify_calculation_claims must be called with the unchanged calculation_reference before interpreting results. It also explains when to use detail_level=summary, include, or neither.

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