CycleCalcs Astronomy

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

Annotations already indicate readOnlyHint=true and openWorldHint=false, so the description adds value by describing the computational logic (intersection of astronomical night and Moon down), the ranking across up to 62 nights, and the trend. It also notes the location requirement. This goes beyond the annotation hints without contradicting them.

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 two short sentences, front-loading the definition and then giving usage guidance. Every clause adds value; the alternative tool is named in a single subordinate clause. No waste.

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 tool with 7 parameters and an output schema, the description covers the core purpose, intended use cases, alternative tool, and a key prerequisite. It doesn't explain the output schema, but that's covered by the existing output schema. The only minor omission is the meaning of 'trend', but that is not essential for tool selection.

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?

The schema covers 100% of parameters with detailed descriptions, giving a baseline of 3. The description adds only the high-level note 'Location required' and does not provide additional parameter-level detail, so the schema remains the primary source.

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 clearly states the tool provides 'the genuinely dark, moonless observing window for a night' by intersecting astronomical night with Moon-down periods, and explicitly names its intended use cases ('stargaze / photograph the Milky Way / observe deep-sky objects'). It also differentiates from sibling astro_sun for plain twilight times.

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 an explicit when-to-use: 'The right tool for "when should I stargaze / photograph the Milky Way / observe deep-sky objects".' It also names an alternative: 'For plain twilight times use astro_sun.' The prerequisite 'Location required' is also stated.

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

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

Beyond the readOnlyHint annotation, the description discloses important non-obvious behaviors: the count parameter applies per type (so count=3 with type 'both' can return six events), visible_only requires a location, and using a place name triggers a GeoNames credit requirement. These details help the agent predict tool behavior and avoid surprises.

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 compact: three sentences covering the tool's purpose, optional local enhancements, and a critical caveat. It is front-loaded with the core function and avoids unnecessary verbosity, making it easy to parse and act on.

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's complexity (12 parameters, output schema, multiple modes), the description adequately covers the main scenarios and caveats. It doesn't need to repeat output schema details or every parameter, as those are already structured, and it provides enough behavioral context for correct invocation.

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?

The schema already describes all 12 parameters with full coverage, but the description adds meaningful semantic context beyond the schema, particularly the note about count applying per type and the explicit behavior of visible_only. This extra clarification is valuable even though the schema alone would be sufficient.

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 clearly states what the tool does: it returns solar and lunar eclipses, either the next/previous from a date or all in a range, including type, magnitude, obscuration, Saros series, and global geometry. It also differentiates itself from sibling astronomy tools by focusing specifically on eclipses and their detailed parameters.

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 clear usage context: use it to get upcoming/past eclipses from an anchor date or an explicit window, and optionally supply a location for local circumstances. It does not explicitly mention alternative tools or when not to use it, but the context is sufficiently clear for an agent to select it appropriately among astronomy siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, which covers the safety profile. The description adds valuable context about GeoNames data licensing (CC BY 4.0) and requires preserving the attribution field, which is a behavioral constraint beyond what annotations provide. It does not elaborate on rate limits or response details, but the output schema covers return structure.

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 two sentences, front-loaded with the core purpose, then provides context on licensing and usage. Every sentence earns its place, with no redundant or filler content.

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 output schema exists and the tool is relatively simple, the description is complete. It states the dual functionality, data source, attribution requirement, and explicitly positions it against siblings. No critical information is missing for an agent to decide on and invoke the tool correctly.

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%, with each parameter well-described (ids, lat/lon ranges, defaults, etc.). The description adds context that lat/lon are for reverse lookup and that id fetches an exact place, but this largely restates schema info. The main added value is clarifying the two operational modes, which indirectly helps parameter interpretation, but the schema already does the heavy lifting.

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 clearly states the tool's function: resolving place names to coordinates, region, country, IANA timezone, and a stable place_id, or reverse-look-up from lat/lon. It also explicitly distinguishes it from sibling tools by noting that other tools accept a place argument directly, making this tool only needed for disambiguation, country filtering, or reverse geocoding.

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?

Provides explicit guidance on when to use the tool: 'this is only needed to disambiguate a name, filter by country, or reverse-geocode.' This clearly contrasts with sibling tools that accept a place argument directly, giving the agent a decision rule for selection.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it distinguishes between an instant and a daily series, and notes that supplying a location enriches the output with rise/set and altitude. It does not discuss pagination or date-range errors, but those are covered in the schema descriptions, and the output schema exists.

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?

Two sentences, zero wasted words. The first sentence enumerates the output fields and modes; the second sentence nests the location enhancement and sibling alternatives. Highly scannable and efficient.

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 a rich output schema, full parameter descriptions in the schema, and clear annotations, the description provides all necessary context. It covers the tool's purpose, output variety, optional location behavior, and directs to relevant siblings, making it self-sufficient for an agent.

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?

The schema covers 100% of parameters with detailed descriptions, so the baseline is 3. However, the description adds semantic value by clarifying the relationship between location parameters and additional output fields ('A location adds rise/set and altitude'), and by framing start/end/count as a 'daily series' option.

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 uses a specific verb ('returns') and resource ('the Moon at an instant or as a daily series'), listing concrete output fields like phase, illuminated fraction, distance, and libration. It clearly distinguishes itself from sibling tools by naming astro_moon_phases and astro_positions as alternatives for different needs.

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?

Explicit guidance is provided: 'For a calendar of new and full moons use astro_moon_phases; for the Moon's exact coordinates use astro_positions.' It also indicates that adding a location changes the output (rise/set and altitude), which helps the agent decide when to include location parameters.

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

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

Annotations already include readOnlyHint=true and openWorldHint=false, so the description only needs to add context beyond that. It adds meaningful detail about what each event includes: exact instant, distance, apparent size, supermoon classification under both definitions, traditional full-moon name, and any eclipse. This enriches the behavioral understanding without contradicting the read-only hint.

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?

Two sentences: the first states the tool's scope and output details, the second gives usage guidance and an alternative. It is front-loaded, information-dense, and contains zero filler. Perfectly concise for the complexity.

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 10-parameter schema and output schema, the description covers the essential decision points: window vs. next-few-from-date, supermoon definition nuance, eclipse inclusion, and the relationship to astro_moon. It omits pagination and date-range constraints, but those are documented in the parameter schemas and output schema, so the description remains a complete high-level guide.

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?

The schema covers 100% of parameters with detailed descriptions, so the description doesn't need to repeat parameter semantics. Its mention of 'in a window (or the next few from a date)' aligns with start/end and date/count parameters, but adds no additional parameter-specific meaning beyond the schema. 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?

The description uses a specific verb-resource structure: it lists every new moon, quarter, and full moon in a window or next from a date, with exact instants and associated details (distance, supermoon classification, eclipse). It clearly distinguishes itself from sibling tool astro_moon by stating 'For the Moon's state right now use astro_moon.'

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 states when to use: 'Use for "when is the next full moon" and phase calendars.' It also provides an explicit alternative for the Moon's current state (astro_moon), giving clear direction and a contrast.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral detail: it lists the specific computed fields (retrograde state with next station, worth-looking-tonight assessment, etc.) and stresses 'one call'. This goes beyond the annotation while remaining consistent.

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 exceptionally concise: two sentences, the first front-loading the core purpose and data fields, the second adding use-case and alternative. Every sentence earns its place without redundancy.

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?

Despite the tool having 7 parameters and an output schema, the description covers the essential context: what data is returned, when to use it, and a pointer to an alternative tool. It does not need to explain return values because output schema exists, and the description fully equips an agent to select and invoke the tool correctly.

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?

The input schema provides 100% parameter coverage, so the baseline is 3. The description adds no additional parameter-level information beyond what the schema already states, such as 'optional location'. It does not reference parameters like date, bodies, or sort.

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 clearly states the tool's purpose: 'All eight planets in one call for a date and optional location' and enumerates the exact data fields returned (constellation, magnitude, apparent size, elongation, etc.). It also differentiates from sibling tool astro_positions by noting 'For exact coordinates of specific bodies use astro_positions.'

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 explicitly identifies when to use this tool: 'The right tool for "which planets are visible tonight"' and provides an alternative: 'For exact coordinates of specific bodies use astro_positions.' This gives the agent clear guidance on tool selection.

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

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

Adds important non-obvious behavior beyond readOnlyHint: peak_magnitude is Venus-only and Mercury's peak is unobservable because it is behind the Sun; transits are genuinely rare; conjunction instants use the classical heliocentric convention and are named on each event. This is context an agent needs to interpret results correctly.

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?

Three dense sentences cover the core capability, event list, both operating modes, example use cases, the sibling alternative, and a convention caveat. No wasted words; information is front-loaded.

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 tool with multiple event kinds and two modes, the description captures the main functionality, the no-date live snapshot, event-specific exceptions, and the correct alternative. The output schema and rich input schema descriptions handle remaining details like pagination and date ranges.

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 descriptions are already thorough and cover 100% of parameters. The description complements them by clarifying the behavior of 'kinds' (peak_magnitude only for Venus, transits body-specific) and by tying the 'with no dates' mode to the optional date/start/end parameters. This adds semantic value beyond the 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?

The description states 'The apparition cycle of the inferior planets as dated events' and enumerates specific event types (conjunctions, elongations, peak brightness, transits). It also distinguishes the no-date mode that reports current cycle state, and explicitly contrasts with astro_planet_board.

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 provides use cases: 'The right tool for "when does Venus become the morning star", "when is Venus brightest", or "Mercury's next greatest elongation"' and a direct alternative: 'For tonight's visibility of all eight planets use astro_planet_board.' It also explains the behavior with and without dates.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false. The description adds behavioral context beyond this: it discloses that altitude and azimuth are only available 'with a location' and that refraction is 'stated per field', plus the input constraint 'Do not pass earth'. No contradiction with 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 three sentences that front-load the core purpose, then give usage guidance and sibling alternatives. Every sentence earns its place, with no redundant 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?

For a 10-parameter tool, the description effectively covers the main use case, output richness, and alternatives. Date-range limits and pagination are handled in the schema, and an output schema exists, so the description need not explain return values. It is complete for tool selection and invocation.

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 covers all 10 parameters with detailed descriptions, so the baseline is 3. The description adds minor meaning such as 'Do not pass earth' (relates to bodies) and 'with a location' (explains lat/lon purpose), but does not add significant syntax or format details beyond the 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?

The description clearly states it provides 'Exact positions for up to 20 bodies at an instant or over a time grid' and lists the specific coordinate frames and quantities (RA/DEC in J2000 and of-date, ecliptic longitude/latitude, distance, alt/az). It also distinguishes itself from siblings by explicitly naming astro_rise_set and astro_planet_board for other tasks.

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 explicitly states when to use the tool: 'Use for "where exactly is X"' and provides alternatives: 'For rise and set TIMES use astro_rise_set; for a visibility overview of all planets use astro_planet_board.' It also gives a constraint 'Do not pass earth' which is a clear usage guideline.

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

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

Annotations declare readOnlyHint=true, so safety is already covered. The description adds valuable behavioral context about extreme-latitude handling ('explicit status ... instead of missing values') and radec target support, going beyond the annotations without contradicting them.

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 three tight sentences, front-loaded with the core purpose, and every clause adds value. There is no filler or repetition of schema content.

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 presence of a full output schema and comprehensive parameter descriptions, the description covers scope, edge-case behavior, and alternative tools sufficiently. An agent can confidently select and invoke the tool without missing critical context.

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% with detailed descriptions for all 10 parameters, so the description carries little extra parameter meaning. It mentions 'fixed radec targets' but the schema already documents the 'radec:RA,DEC' format; no additional semantics are provided.

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 clearly states the tool computes 'Rise, upper transit, set and lower transit' for 'one body at one location', which is specific and unambiguous. It also distinguishes from siblings by naming astro_sun and astro_positions as alternatives.

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 explicit guidance on when to use alternatives: 'For the Sun specifically, astro_sun returns richer twilight structure; for positions between events use astro_positions.' This directly helps an agent choose the correct tool.

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

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

annotations already declare readOnlyHint=true, so the description does not need to cover safety. It adds useful behavioral context: sun times are conditional on a location, and planet visibility is filtered to 'worth looking at'. It does not disclose potential errors or edge cases, but these are partially in the schema, so no contradiction.

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 two sentences that are dense with information: the first lists the content, the second provides usage guidance and alternatives. No filler; every clause earns its place.

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?

The description covers what the tool does, when to use it, and names alternatives. Given that an output schema exists and parameter descriptions are comprehensive, the description does not need to explain return values or error handling. It could mention the location-dependent attribution requirement, but that is already in the schema, so the context is sufficiently complete.

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% and each parameter has a thorough description (e.g., date range restrictions, lat/lon ranges, location credit). The tool description adds minimal parameter-level meaning beyond noting that a location enables sun times. This meets the baseline for high schema coverage.

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 'One-call snapshot of the whole sky for a place and moment' and enumerates specific content (moon phase, planets up, next eclipse, sun times). This clearly states the tool's function and scope, and the phrase 'Reach for this first when the question is broad' distinguishes it from specialized siblings.

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 explicitly gives usage guidance: 'Reach for this first when the question is broad' and then names alternatives for specific needs (astro_sun, astro_dark_window, astro_positions). This tells the agent when to use this tool and when to choose a different one.

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

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

Annotations already mark the tool read-only and closed-world, so the bar for transparency is lower. The description adds meaningful behavior: it returns explicit polar day/night status, requires a location, and supports series over whole days. No contradictions with annotations, and it doesn't hide side effects or failure modes.

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?

Three sentences: what it returns, how to request series, and when to prefer alternatives. Every sentence earns its place, front-loaded with the core purpose, and avoids repetition of schema details.

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's moderate complexity (9 params, anyOf location requirement, output schema present), the description covers the full usage envelope: scope of results, how to specify a range, and which sibling tools to use for adjacent needs. The output schema handles return-value details, so nothing essential is missing.

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 the parameter descriptions carry the full semantic load. The tool description adds little beyond noting that location is required and that step is in whole days, both of which are already clear from the schema. This matches the baseline of 3 for high schema coverage.

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 a precise resource and scope: 'The complete solar day for one location' and enumerates specific outputs (sunrise, sunset, solar noon, day length, twilight boundaries, polar day/night). This distinguishes it from siblings like astro_dark_window and astro_sky_today, which are explicitly named as alternatives.

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 gives direct usage context: location is required, series are created with start/end plus a whole-day step, and it explicitly says when NOT to use it ('For "is it dark enough to observe" prefer astro_dark_window; for a broad snapshot prefer astro_sky_today'). This fully satisfies the when-to-use vs alternatives criterion.

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