Astronomy Data

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

Annotations declare readOnlyHint=true, and the description adds behavioral context: GET request, credit cost, selector priority (lat/long > location > ip > caller IP), error conditions (401 on free plan for non-English lang), and specific return fields.

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?

Well-structured with clear paragraphs: purpose, comparison, return fields, selector priority, parameter constraints. Slightly verbose but every sentence adds value.

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?

Completely covers return format, selector priorities, parameter constraints, plan differences, and error conditions. No output schema, but return description is thorough.

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%, but the description adds interdependencies (lat/long together, elevation range 0-10000, date format YYYY-MM-DD, time_zone effect, lang paid-only). Adds value beyond schema.

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?

Description clearly states it's a 'read-only single-date astronomy lookup' via GET /v3/astronomy. It distinguishes itself from sibling get_astronomy_time_series, which is for daily data across a date range.

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?

Explicitly says 'Use for one date or real-time sun/moon position; use get_astronomy_time_series for daily sunrise, moon, and twilight data across a date range.' Also mentions plan limitations (free vs paid, credit cost, 401 on non-English lang).

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