Stellarhound — stargazing forecasts, dark-sky sites & aurora

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

Discloses the ranking logic (grouped by drivability, scored by weather window, darkness, drive time), notes drive times are approximate, and instructs to include the methodology note when presenting results. Adds transparency beyond the read-only/non-destructive 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?

Well-structured with clear sections: purpose, usage, ranking methodology, args. Concise yet comprehensive, no redundant 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?

Comprehensive for its complexity: covers purpose, usage, ranking, output structure (tiers, nearest_km, uncertainty_note, attribution), and instructs to include methodology note. No gaps in understanding how to use and interpret results.

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 'Args' section fully explains lat, lon, and limit, including ranges and default, which the input schema lacks. Adds meaningful parameter meaning.

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?

Clearly states the tool recommends dark-sky sites near a location, ranked by drive worth. Differentiates from siblings by focusing on recommending specific sites rather than providing forecasts or conditions.

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 an explicit usage example ('where should I drive to stargaze near X') and explains the ranking methodology, making it clear when to use this tool over alternatives.

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 destructiveHint=false. Beyond the annotations, the description adds behavioral context by detailing the return structure (kp_forecast array with time/kp/flag fields), the firmness labels (observed|estimated|predicted), and an explicit instruction to preserve those labels when presenting. It stops short of covering update cadence or edge cases like daytime/polar-night behavior, but the description clearly earns its space.

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 and front-loaded: a strong one-liner purpose statement, followed by the use-case guidance, then focused Args and Returns sections. Every sentence adds value—especially the note about keeping firmness labels, which is actionable. No fluff or 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?

For a simple 2-parameter tool with no output schema, the description does a good job of documenting the return contract ({kp_forecast:[...], visibility assessment fields, attribution}) and the forecast's time dimension ('and when'). A few gaps remain: the forecast lookahead window (how many hours/days ahead) and a specific definition of 'visibility assessment fields' could be clarified. But overall, the description is sufficiently complete for this tool's complexity.

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 no descriptions (0% coverage), so the burden is on the description. The description compensates by specifying decimal degrees format and valid ranges for lat (-90..90) and lon (-180..180). This adds genuine semantic value beyond merely restating titles like 'Lat' and 'Lon'. Ranges and format are fairly standard for geospatial parameters, but they are explicitly documented and accurate.

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 opening line, 'Get the aurora (n/s lights) outlook for a location,' is a specific verb+resource+context statement that also clarifies the domain. The description further differentiates from siblings by explaining the mechanistic combination of the Kp-index forecast with geomagnetic latitude, which is distinct from sibling tools like get_stargazing_conditions or get_light_pollution.

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 usage guidance via the quoted use case, "Use for 'any chance of aurora tonight near X'", which clear signals intent and context of invocation. However, it doesn't name or exclude alternatives (e.g., when to prefer get_stargazing_conditions instead), leaving the when-not-to-use guidance implicit rather than explicit.

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 indicate readOnlyHint=true and destructiveHint=false, so the description doesn't repeat safety info. It adds value by clarifying the estimate is satellite-based and the ceiling is a plain-language summary, which is behavioral context beyond annotations. No contradictions.

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 clear sections, a usage example, and parameter list. A bit verbose in the returns section but every sentence adds value. Could be slightly tighter, but overall 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?

For a simple two-param tool with good annotations, the description covers purpose, usage, and return structure. It lacks output schema but provides a literal return example. It's adequately complete, only missing edge cases like invalid coordinates, which are likely handled by schema validation.

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 0%, but the description explains the two parameters (lat, lon) with ranges and types, adding meaning beyond the schema's bare type definitions. This fully compensates for the low coverage, though it could mention error handling or precision.

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 specifies the tool's function: estimating light pollution at a given point, returning Bortle class and visibility. It differentiates from siblings by focusing on a point-specific estimate, contrasting with tools like find_dark_sky_sites or get_tonight_agenda.

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 clear use cases ('how dark is the sky at X', 'can I see the Milky Way from X') and explicitly states it's a satellite estimate, not a field measurement. However, it does not explicitly mention when not to use it or alternatives, though sibling names suggest context.

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, openWorldHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond that: how scores are computed (three-layer cloud-cover, moon illumination, darkness window), the inclusion of a light-pollution estimate, and the uncertainty caveat ('forecasts beyond ~7 nights are increasingly uncertain'). It also instructs the agent to 'Present scores/verdicts verbatim' and notes that skies beyond 7 days are provisional, which are valuable behavioral traits.

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 and appropriately sized for the tool's complexity. It opens with the core purpose, follows with usage examples and calculation details, then provides a clear Args section and a compact Return structure. No sentence is wasted, and it remains readable despite its length.

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?

With no output schema, the description compensates by listing the return fields ({timezone, light_pollution, nights:[...], best_window, uncertainty_note, attribution}). It also covers edge cases like uncertainty, provisional data, and the instruction to present scores verbatim. This makes the tool fully understandable in 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?

The schema has no descriptions (0% coverage), so the description must fully explain parameters. It does: lat as 'decimal degrees (-90..90)', lon similarly, and nights with range, default, and uncertainty note. This gives the agent all necessary semantic information beyond the raw 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 the tool's function: 'Score the next nights for stargazing at a location (0-100 per night).' It uses a specific verb ('score') and identifies the resource ('stargazing conditions') and scope ('at a location'). It distinguishes itself from sibling tools by emphasizing per-night scoring that combines cloud cover, moon, and darkness window, while siblings handle site finding, aurora, or light pollution.

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 usage scenarios: 'Use for "when should I stargaze this week near X", "is Saturday any good for the Milky Way", trip planning.' This gives clear context for when to use the tool. However, it does not explicitly mention alternatives or conditions when not to use it, so it falls short of a 5.

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 destructiveHint=false, so the agent knows this is a safe read. The description adds context about returning a ranked agenda and 'report as returned' but does not detail aspects like network calls, timezone handling, or any limitations. With good annotations, a 3 is appropriate, adding some value beyond 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 compact and well-structured, with a brief summary, usage context, args, and return format. Each section adds value. It could be slightly more concise but is not verbose.

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 2 simple params, no output schema, and annotations cover safety, the description provides a clear return structure including the fields returned. It adequately explains the input and high-level output, but it does not elaborate on the 'weather' or 'darkness' fields or the agenda possibilities, leaving some ambiguity for a tool that returns complex structured data.

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 has 0% description coverage, but the description provides clear meaning for lat and lon ('Latitude in decimal degrees (-90..90)') and 'Longitude in decimal degrees (-180..180)'. This goes beyond the schema, which only names them. Given only two simple params, this is adequate, though it doesn't add additional format details 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?

The description uses a specific verb ('Get'), a clear resource ('tonight's stargazing plan'), and includes the key elements: sky score, darkness window, and observing targets. It distinguishes from siblings by focusing on the 'tonight' agenda for a location, but it does not explicitly differentiate from similar siblings like get_stargazing_conditions.

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: when the user asks 'what can I see tonight' or 'is tonight worth going out'. This clearly differentiates from siblings, which likely focus on broader conditions or forecasts. No exclusions provided but context is sufficient.

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