space.satellite

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

With no annotations, the description carries the full burden. It discloses that data comes from fresh Celestrak elements + SGP4 propagation, indicating an external dependency and computational method. It also specifies output: sub-point lat/lon/altitude, speed, and optionally azimuth/elevation/range. However, it does not mention rate limits, authentication needs, or data staleness thresholds.

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 concise (two sentences), front-loaded with the core purpose, and includes key details. It could be slightly improved by separating input versus output clearly, but structure is 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 the complexity (5 parameters, no annotations, no output schema), the description is moderately complete. It covers main input (noradId) and outputs, but leaves 'at' and 'altKm' partially unexplained, and omits error scenarios or data source limitations. Could benefit from a brief note on return format or behavior when no satellite found.

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 description adds meaning to noradId (example, cataloged), and explains lat/lon as observer coordinates for look angles. However, it does not clarify 'at' (time), 'altKm' is ambiguous (appears in input but description implies output), and schema properties lack descriptions (0% coverage). The partial compensation gives a middling score.

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 the current position of any cataloged satellite by NORAD number, gives an example (25544=ISS), and specifies the method (Celestrak + SGP4). It distinguishes itself from siblings like space.skywatch or space.close-approaches by focusing on real-time sub-point coordinates and look angles.

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 implies usage for satellite position queries but does not explicitly state when to use this tool versus alternatives (e.g., space.observe for observational conditions). It mentions optional observer lat/lon for look angles but lacks exclusion criteria or context for when not to use it.

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