Cazimi: retrograde planets

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world, and the description adds substantive context beyond that: UTC timing to the minute, provenance (JPL DE421 ephemeris) and a stated validity window of 2025–2030, which tells the agent when results may not cover a requested date. It stops short of saying what happens for out-of-range dates or how a missing/ambiguous date is handled, which keeps it off a 5.

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?

Purpose is front-loaded in the first clause, with supporting detail following, and there is no filler. The parenthetical enumeration of the five cycle moments is long but carries real information, though it makes the middle of the sentence dense to parse.

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 one-optional-parameter read tool with full schema coverage and complete annotations, the description covers purpose, units, data source, temporal validity and return content, so an agent can call it correctly without an output schema. The missing piece is sibling routing, which matters here because six other tools return overlapping retrograde information.

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 100%, so the single 'date' parameter is already fully documented including the YYYY-MM-DD read-as-noon-UTC behavior and the now-default. The description reinforces the UTC convention ('Times are UTC, to the minute') but adds no new parameter-level semantics; 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 gives a specific verb and resource ('Says whether Mercury is retrograde on a date') and even enumerates the phase values it can return, so its function is unambiguous. What it does not do is distinguish itself from siblings such as is_planet_retrograde (the all-planet version), mercury_retrograde_dates, or retrograde_planets_today, so an agent still has to infer why this one is Mercury-specific.

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?

There is no explicit when-to-use or when-not-to-use guidance, and none of the seven overlapping siblings are named, including the near-identical is_planet_retrograde and retrograde_planets_today. The only usage signal is implicit in the verb phrase 'on a date', which an agent must extrapolate into a routing decision.

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 only declare the safety profile (readOnly, idempotent, closed-world); the description goes well beyond that by naming the data source and coverage window (JPL DE421, 2025–2030), the time standard and precision (UTC, to the minute), and the default-date behavior. It also enumerates the returned fields (sign, pre-shadow, station retrograde, cazimi/opposition, station direct, post-shadow end, days to next transition) and disclaims astrological interpretation, which is meaningful scoping for a niche tool.

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?

Two sentences, front-loaded with the core answer, then the field enumeration and provenance. The long parenthetical lists (planets, phases) are dense but each token carries information; no filler sentences.

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 naming the fields returned and their time basis, which is enough for an agent to decide if the response fits its need. The remaining gap is a precise statement of failure behavior outside the 2025–2030 ephemeris window, which is only hinted at.

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 coverage is 100% — both parameters are documented, including the YYYY-MM-DD-as-12:00-UTC rule and the enum of eight planets — so the baseline is 3. The description adds only the UTC-to-the-minute framing and repeats the planet list; it contributes no new syntax or constraint beyond the 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?

States a specific verb and resource ('Says whether Mercury, Venus, ... Pluto is retrograde on a date') plus the secondary output (phase). The eight-planet, single-date scope implicitly separates it from is_mercury_retrograde and retrograde_planets_today, but no sibling is named explicitly.

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?

Usage is implied: use it to check one planet on one date. There is no explicit 'use X instead when...' routing to the six sibling tools, nor any statement about what happens for dates outside the 2025–2030 range beyond the parenthetical source note.

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?

The annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds valuable context beyond that: returned markers, UTC minute precision, ephemeris source, and inclusion of periods that overlap the year.

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?

Two compact sentences, with purpose and scope front-loaded. The source details and the astronomical-not-horoscope boundary each add useful information without filler.

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 one-parameter read-only tool with no output schema, the description covers the year range, returned fields, time precision, source, and overlap rule. It stops short of specifying output structure or explicit sibling routing, but it is otherwise complete enough to call 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 schema already fully documents the year parameter and its 2025–2030 range. The description adds a useful boundary rule by saying periods that 'fall in or overlap' the year are included, which clarifies cross-year behavior.

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 gives a specific verb and resource: it lists every Mercury retrograde period for a year. Its annual, Mercury-specific scope clearly separates it from siblings such as next_mercury_retrograde, is_mercury_retrograde, and planet_retrograde_dates, even without naming them.

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?

Usage is implied by the annual list scope, but there is no explicit when-to-use or when-not-to-use guidance. It also does not route the agent to alternatives like next_mercury_retrograde or is_mercury_retrograde.

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 cover read-only, idempotent, closed-world, non-destructive, but the description adds materially: the 17′ window, that the previous cazimi is also returned, the 12-hour 'today's' convention, minute-level UTC precision, and a source/coverage constraint (JPL DE421, 2025–2030) that tells the agent the result is bounded in time. That ephemeris range is exactly the kind of caveat structured fields cannot express.

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?

Front-loaded with the core answer (what is returned) and then the qualifiers, with no filler sentences. It is dense — the list of return components plus the ephemeris parenthesis packs a lot into a few clauses — but essentially every clause carries information an agent needs.

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 carries the burden of describing return values and does so: UTC minute, degree, 17′ window, and the previous cazimi. Combined with the source and date-range limits, an agent has enough to call it and interpret results without further documentation.

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 coverage is 100% and the single parameter is fully documented, so the baseline is 3. The description adds beyond that by explaining how the boundary is interpreted — a cazimi within 12 hours counts as today's and is returned as the previous one — which materially changes how an agent should pass and read 'from'.

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?

States a specific verb and resource ('Returns the next Mercury cazimi') and immediately defines the term ('exact Sun–Mercury conjunction during a retrograde'), which distinguishes it from the sibling retrograde tools without the agent needing to open a schema. It also disambiguates scope with 'This is astronomical timing, not a horoscope.'

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 'after a date' framing and the 12-hour rule make the selection context reasonably clear, and the definition of cazimi inherently separates it from next_mercury_retrograde and the other siblings. However, it never explicitly says 'use next_mercury_retrograde instead if you want the retrograde station' or states any exclusion, so routing still requires inference.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description layers on real behavioral context: times are UTC to the minute, derived from JPL DE421 ephemeris, bounded to 2025–2030, and inclusive of an in-progress retrograde. It also preempts a likely misinterpretation by stating this is astronomical timing, not a horoscope.

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?

Three tight sentences: the core behavior and its returned fields come first, then the precision/source caveat, then a one-line scope disclaimer. No filler, and the returned field list is front-loaded where an agent will read it.

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 correctly enumerates the return contents (sign, pre-shadow, station retrograde, cazimi, station direct, post-shadow end). For a one-optional-parameter read tool, nothing an agent needs to call or interpret the result is missing, including the data-range limitation.

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 coverage is 100% and the single 'from' parameter is fully documented there, including the YYYY-MM-DD format, the 12:00 UTC default reading, and the now-default. The description only restates that this date is the anchor for 'next', adding little beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource (returns the next Mercury retrograde) and nails the scope boundary: the next one after a given date, or the one currently in progress until it stations direct. That phrasing naturally separates it from siblings like is_mercury_retrograde (current-state check) and mercury_retrograde_dates (list of dates) without needing to name them.

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?

Usage is implied rather than prescribed: the 'after a date' framing tells an agent this is a forward-lookup tool, and the in-progress clause resolves the most obvious ambiguity. However, no sibling is named and there is no explicit 'use X instead when...' guidance, so the agent must infer the routing from the surrounding tool list.

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 cover read-only, idempotent, non-destructive, closed-world semantics, so the description is not burdened with the safety profile. It adds genuinely non-obvious behavior: UTC to-the-minute times derived from JPL DE421, and a stated 2025–2030 ephemeris window, which tells the agent the tool's validity horizon. It does not say what happens for out-of-range dates, but the added context is substantial.

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?

Two sentences, front-loaded with the action and scope before the result content and provenance. Dense but nearly every clause carries information; the parenthetical about in-progress retrogrades is well placed. Slightly crowded noun lists ('sign, shadows, cazimi or opposition, and stations') reduce readability a touch.

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 carries the return-value burden and does so by naming the fields returned and their time basis. It also discloses the ephemeris source and date range, which is exactly the kind of limitation an agent needs for a timing tool. The only gap is undefined behavior outside the 2025–2030 window.

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 100% and both the 'from' default/time interpretation and the planet enum are already documented in the schema. The description adds detail about what comes back in the result (sign, shadows, cazimi/opposition, stations) rather than new meaning for the two input parameters, so the baseline 3 applies.

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?

States a specific verb and resource ('Returns the next retrograde of [eight named planets]') plus scope ('after a date, or the one in progress'). The planet-general framing distinguishes it from the Mercury-specific siblings like next_mercury_retrograde and is_mercury_retrograde without needing the 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?

Gives clear context: use it to get the next retrograde after a date or the currently in-progress one, and explicitly frames the result as astronomical timing rather than a horoscope. It stops short of naming when to prefer the sibling tools (e.g., planet_retrograde_dates for full date lists, or the Mercury-only variants).

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?

With readOnlyHint, idempotentHint and destructiveHint already declaring a safe, repeatable read, the description still adds real context: the JPL DE421 ephemeris source, the UTC-to-the-minute precision, and the fact that a year with no retrogrades reports that and names the next one. Only the ordering and pagination/shape of the returned period list is left unstated.

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?

A single dense sentence pair, front-loaded with the verb and scope, then precision and provenance, then the domain caveat. Every clause carries information an agent needs; nothing is padding.

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 two-parameter read tool with no output schema, the description covers the returned content (sign, shadows, cazimi/opposition, stations), precision, source, and the empty-result case. The only gap is the structural form of the response, which is minor at this 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?

Schema coverage is 100%, so the baseline is 3, but 'in or overlaps a year' adds genuine filtering semantics beyond the schema — a period beginning in the prior year still counts, which the bare 'Year, 2025–2030' description does not convey. The planet enum and range are restated but not enriched.

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 opens with a specific verb and resource ('Lists every retrograde period') and enumerates the eight supported planets plus the year window, so the scope is unmistakable. It does not explicitly distinguish itself from the near-identical sibling mercury_retrograde_dates, leaving the agent to infer that this is the all-planet variant.

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?

Usage is implied rather than stated: the 2025–2030 window and 'astronomical timing, not a horoscope' frame the intended context, and the empty-year behavior tells the agent what a null result looks like. There is no explicit guidance on when to prefer this over mercury_retrograde_dates, retrograde_planets_today, or is_planet_retrograde.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds real context beyond them: data source (JPL DE421), validity window 2025–2030, UTC-to-the-minute precision, and the 'astronomical timing, not a horoscope' framing. It does not say what happens for dates outside 2025–2030, which is the one behavioral gap.

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?

Front-loaded with the use-case trigger, then the return payload, then scope/provenance caveats — a sensible order. The middle sentence is dense (phase, sign, cycle moments, two flag types, summary sentence) but every element maps to an actual return field, so nothing is wasted.

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 carries the return-value burden and does so thoroughly, enumerating phases, sign, cycle timestamps, cazimi/opposition flags, and the summary sentence. Missing only edge-case behavior (out-of-range dates, whether all eight planets are always present).

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 coverage is 100% and the single 'date' parameter is fully documented there (format, 12:00 UTC reading, defaults to now). The description only says 'on a date' and 'Times are UTC,' adding no format or default details beyond the schema, so the baseline 3 applies.

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?

States a specific verb+resource ('returns the phase... for Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune and Pluto on a date'), which makes it clearly the all-planets bulk lookup. It does not explicitly name the single-planet siblings (is_planet_retrograde, is_mercury_retrograde) as the narrower alternative, so the differentiation is implied rather than stated.

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?

Opens with an explicit trigger: 'Use for "which planets are retrograde" questions,' which maps directly to the user intent. It gives no when-not guidance or named alternative for single-planet queries, so an agent must infer the boundary from the enumerated planet list.

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