ephemeris_next_eclipse

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

Annotations already declare readOnly and idempotent, so the bar is lower. The description adds valuable behavioral context: it explains that providing latitude/longitude returns local contact times, while omitting them returns the next global eclipse. It also discloses the return fields (type, date/time, magnitude, duration) and credit cost, which goes well beyond the annotations.

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 well-structured with a clear summary, location optional section, use-case examples, and credit cost. It uses bullets and short paragraphs, front-loading the core purpose. Every sentence adds value, and there is no redundancy or filler.

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 the tool has no output schema, the description compensates by listing return fields (eclipse type, date/time, magnitude, duration). It covers the main parameters through examples, explains the location behavior, and gives credit cost. Although after_date is not mentioned in the description, it is well-documented in the schema, so completeness is not compromised.

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 coverage is 100%, giving a baseline of 3. The description adds significant meaning beyond the schema by explaining the optionality and pairing requirement for latitude/longitude, showing examples for both global and location-based queries, and clarifying the meaning of 'any' for eclipse_type through context. This fully compensates and enriches the parameter understanding.

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 opens with 'Find the next solar or lunar eclipse,' which is a specific verb+resource statement. It clearly distinguishes from sibling tools like moon phase or transit tools by focusing on eclipses and even clarifies the optional location behavior. The examples reinforce the exact purpose.

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 a 'USE THIS TOOL FOR' section with concrete example queries, and explains the two usage modes (global vs location-specific). It does not explicitly exclude sibling tools (e.g., ephemeris_next_lunar_phase), but the natural-language examples and focus on eclipses make it clear when to use this tool.

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