Planetary Return Chart - Saturn return, Jupiter return, and inner planet cycles

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered and the bar is lower. The description adds that the output is a full tropical chart with planetary positions, house cusps, and aspects, which is useful behavioral context, but that largely duplicates the output schema rather than revealing anything new about computation or constraints.

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 core sentences are front-loaded and informative, but the trailing keyword block ('Planetary return chart API, Saturn return calculator, Jupiter return chart, Mars return forecast') is SEO filler that carries no meaning for an agent. That waste pulls an otherwise efficient description down.

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 10-parameter read-only tool with full schema coverage, complete parameter descriptions, annotations covering safety, and an existing output schema, the description supplies adequate purpose and output context. Only the missing when-to-use guidance against sibling return tools keeps it from a 5.

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 100%, so every parameter is already documented in the schema, including the retrograde-loop behavior of approximateDate and the timezone/coordinate ranges. The description restates cycle lengths for the planet parameter but adds no syntax or semantics beyond the schema, so the baseline 3 applies.

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?

States a specific verb (Generate) and resource (planetary return chart) and enumerates exactly which planets qualify (Mercury, Venus, Mars, Jupiter, Saturn), which cleanly separates it from the luminary-return siblings like solar_return and lunar_return. An agent can identify the tool without opening the schema.

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 defines what a planetary return is and gives cycle lengths, which implies the use case, but never states when to pick this over sibling tools such as post_astrology_solar_return, post_astrology_lunar_return, or post_astrology_natal_chart. Usage is left to inference.

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