Get Satellite Orbital Elements by NORAD ID

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it details exactly what data is returned (the GP element set with specific fields), names the data source (US Space Force 18th Space Control Squadron via CelesTrak), and implies a read-only, non-mutating operation. It does not contradict annotations and adds meaningful detail about the output and provenance.

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: it leads with the core action, then details the return payload, mentions the data source, and closes with use cases and examples. It is somewhat verbose—the mention of '27,000+ catalogued space objects' and the list of element fields could be trimmed—but it is organized and front-loaded with the most important information. No sentence is wasted, though a tighter version could achieve the same effect.

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 read-only lookup tool with a single parameter and an output schema (as indicated by the context), the description is quite complete. It explains what is returned (the full GP element set with specific fields) and names the authoritative source, which is valuable for trust and expectations. It does not mention error handling for non-existent NORAD IDs, but that is a minor gap given the tool's simplicity and the output schema's existence. Overall, it provides sufficient context for an agent to call it 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 already provides a detailed description of the 'catnr' parameter, including examples and the integer range (1-99999). The description adds a few popular NORAD IDs (25544, 20580, 33591) that overlap with schema examples, but it does not introduce any new semantic meaning beyond what the schema already states. With 100% schema coverage, the description adds marginal value for parameter understanding, so a baseline 3 is appropriate.

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 verb ('Retrieve'), resource ('Two-Line Element (TLE) orbital data'), and scope ('for a specific satellite using its NORAD catalog number'). It distinguishes this tool from siblings like celestrak.satellite.search (which likely searches by name) by specifying the unique input method. It also provides concrete use cases (orbital mechanics, pass predictions) that signal its specific role.

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 when to use it (when you have a NORAD ID) but does not explicitly contrast it with sibling tools like celestrak.satellite.search or celestrak.satellite.group. It mentions 'Popular NORAD IDs' and that you can 'Obtain from celestrak.satellite.search or celestrak.satellite.group' in the schema, but the description itself does not say 'use this instead of X when Y'. It gives context but no explicit when-not guidance, leaving some inference to the agent.

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