next_mercury_retrogradeReturns the next Mercury retrograde after a date (or the one in progress, until it stations direct) with its sign, pre-shadow, station retrograde, cazimi, station direct and post-shadow end. Times are UTC, to the minute, from the ephemeris (JPL DE421, 2025–2030). This is astronomical timing, not a horoscope.
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | Start date as YYYY-MM-DD (read as 12:00 UTC). Defaults to now. |
Changes observed during successful MCP inspections.
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.
Add one secure layer between your agents and this server.