calculate_natal_chart

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. Beyond that, the description adds meaningful behavioral context: it warns about ambiguous repeated civil times, forbids guessing an unknown birth time, and establishes a required verification workflow with verify_natal_claims before presenting interpretations.

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 long but front-loaded with the core purpose, then proceeds through ambiguity handling, required verification, and output-shaping options. Most sentences carry specific operational value, though the final verification-reference sentence is somewhat repetitive of the detail_level explanation.

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?

Given 10 parameters, low schema description coverage, no output schema, and complex workflow requirements, the description supplies substantial context: how to source birth data, how to resolve fold ambiguity, required verification before interpretation, and detail_level/include behavior. It still omits full parameter formatting details, so it is strong but not exhaustive.

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 20%, so the description must compensate for undocumented parameters. It adds useful meaning for fold, house_system options, detail_level, and include, but several parameters such as day, month, year, hour, minute, and location_id still lack format/range/usage details. It partially compensates but not enough for a higher score.

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 (calculate), resource (tropical natal chart data table), and required inputs (exact local birth date/time, location_id), which distinguishes it from render-oriented siblings like render_natal_chart. It does not explicitly name sibling tools it should replace, so it stops short of a 5.

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 description provides some procedural guidance (do not guess an unknown birth time, ask about fold 0/1) and mandates a next step for natal interpretation. However, it does not explicitly state when to choose calculate_natal_chart versus render_natal_chart or other calculate tools, leaving the primary tool-selection guidance implied.

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