ephemeris_retrograde_status

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

The description adds significant behavioral context beyond the read-only annotation: it discloses the credit cost difference (1 vs 10 credits), explains the backend fan-out behavior when planet_id is omitted, and mentions the output fields. This goes beyond the annotations and helps the agent understand side effects and costs.

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 and front-loaded: the first sentence states the core purpose, and subsequent sentences provide essential usage and credit details. The use of a bullet introduces the key use case, and the credit-cost paragraph is dense but informative. Every sentence earns its place; no filler or 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?

Given the tool has no output schema, the description adequately covers the return values (is_retrograde flag, longitude speed, station proximity). It also covers the cost model, the distinction from station tracking, and the key behavioral caveat about omitting planet_id. The datetime rule is referenced to server instructions, which is acceptable. The description is complete for an agent to select and invoke this tool correctly within its 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?

While the schema already describes each parameter with 100% coverage, the description adds crucial semantic value for planet_id: 'Pass this whenever the question names a planet — 1 credit. Omit only to sweep all ten — 10 credits.' This explains the behavioral consequence of including or omitting the parameter, which the schema alone does not convey. The datetime and timezone descriptions are already thorough in the schema, so the added value here is primarily for planet_id.

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 specific function: 'Get retrograde/direct status and speed for ONE planet — or, if you ask for it, all ten — at a given date/time.' It specifies the output (is_retrograde flag, longitude speed, station proximity) and distinguishes itself from the sibling tool electional_station_tracker by explicitly noting that for station timing, that tool should be used.

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 explicit usage guidance: 'Answers "is X retrograde?" at ONE instant' and directs to 'electional_station_tracker' for date-range station questions. It also provides practical cost-based guidance on when to pass planet_id versus omitting it, clarifying that omission runs an all-planets sweep at 10 credits.

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