planetary_orbiter_track

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

With no annotations, the description carries the full burden and mostly succeeds: it discloses the 10 drawable bodies, the specific orbiters and mission-name aliases accepted, that retired craft return an impact site in structuredContent.impact_site rather than a current position, that out-of-range elevation/azimuth/dolly return an error instead of silently clamping, and that the returned link must be presented verbatim. It omits any statement of read-only/non-mutating nature and any latency or rate-limit context.

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 summary sentence and example list are correctly front-loaded, but the sites paragraph drifts far off task, spending many words on the McGetchin crater's 222 m diameter, coordinates, and a once-per-132-years formation statistic that an agent does not need in order to call sites="newcrater". The parameter block is otherwise dense and well organized, but the total length is well past what invocation requires.

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 15-parameter, effectively zero-schema-coverage tool with no annotations, the description supplies enough to call it correctly in every mode. With no output schema, the return side is only partially covered — it says an image plus a link come back and that impact data lands in structuredContent.impact_site, but the overall response shape and the non-impact structured fields are not spelled out.

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% and there are 15 parameters, so the description must do everything — and it documents every one: body aliases, orbiter naming forms including negative Horizons IDs, when/minutes/step/ca_hours defaults and maxima, zoom/span_deg rule interaction, out_px cap, flyby center-shifting, sites presets, mode aliases, and the 3D camera triple. It even resolves a schema ambiguity by stating elevation/azimuth/dolly are degrees despite being typed as strings, and that non-numeric input errors rather than clamps.

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 sentence states a specific verb and resource: it returns an image plotting the current position and trajectory of a spacecraft orbiting, flying by, or swinging past an arbitrary body, drawn on that body's map. The orbiting/flyby distinction and the supported body list let an agent separate this from siblings like planetary_rover_location_map or sat_ground_track without opening either schema.

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 provides concrete example queries and explicit mode-selection rules (mode="orbit3d" for orbital inclination/altitude spread/education, sites="map" for bodies without registered sites, flyby=True to auto-search closest approach). What it never does is name a competing sibling tool or state an exclusion (e.g., when Earth-satellite ground tracks belong to sat_ground_track instead).

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