Skip to main content
Glama
Sign In
openephemeris

Open Ephemeris

by openephemeris
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Interactive Transit Timeline

explore_transit_timeline
Read-onlyIdempotent

Generate a date-ordered, month-grouped timeline of exact transit hits to a natal chart, with clickable interpretations for monthly or yearly forecasts.

Instructions

Use this when the user asks 'what's happening in my chart this month', 'what transits are coming up for me', 'what does my year ahead look like', 'when will Saturn hit my chart' or 'what's happening astrologically for me in 2027' — a forecast they should SEE. Returns an interactive, date-ordered timeline (inline in Claude and ChatGPT; text summary elsewhere) of exact transit hits grouped by month — transiting planet, natal point, aspect and retrograde markers — each clickable for a focused interpretation. Every hit carries its in-orb window (when the transit starts and ends, and which pass it is when a retrograde repeats it), and transits already in orb at the start are listed with applying/separating.

ASPECT ANGLES: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 = sextile. EFFICIENCY: searches run faster when transiting_planets and natal_points are given. MAX SPAN: Explorer/PayG 1y, Pro 5y, Startup 10y, Scale 40y (longer = 400). CREDIT COST: 1 + span price: ≤1y 5 (6 total), ≤3y 10, ≤5y 15, ≤10y 25, ≤20y 40, ≤40y 70.

Input Schema

NameRequiredDescriptionDefault
orb_degNoIn-orb window around each hit, degrees. Default 1, max 15.
end_dateYesWindow end. ISO 8601 date (whole UTC day) or zoned datetime.
start_dateYesWindow start. ISO 8601 date (whole UTC day) or zoned datetime.
aspect_angleNoDegrees: 0 conjunction (default), 60, 90, 120, 180.
natal_pointsNoE.g. ['sun','moon','asc','mc']. Default the 7 classical bodies.
natal_datetimeYesISO 8601; zone required (`Z`/offset, or local time plus `timezone`).
natal_latitudeYesBirth latitude.
natal_timezoneNoIANA zone for the natal birth location (local datetime).
natal_longitudeYesBirth longitude.
transiting_planetsNoE.g. ['saturn','pluto','chiron']. Default Sun through Saturn; outers and Chiron only when named.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv4.29.0
    • changedInput schema / properties / aspect_angle / description
      Previous value: -"Aspect angle in degrees. 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 = sextile."New value: +"Degrees: 0 conjunction (default), 60, 90, 120, 180."
    • changedInput schema / properties / end_date / description
      Previous value: -"End of the transit search window. ISO 8601 date (YYYY-MM-DD) or zoned datetime; a naive clock time is rejected. A bare date covers the whole UTC day: start at 00:00, end at 23:59:59."New value: +"Window end. ISO 8601 date (whole UTC day) or zoned datetime."
    • changedInput schema / properties / natal_datetime / description
      Previous value: -"ISO 8601 datetime. A datetime with no zone is rejected; give a `Z` or ±HH:MM suffix, or a local time with the `timezone` argument. Date-only resolves to 12:00 UTC."New value: +"ISO 8601; zone required (`Z`/offset, or local time plus `timezone`)."
    • changedInput schema / properties / natal_latitude / description
      Previous value: -"Latitude of birth location in decimal degrees."New value: +"Birth latitude."
    • changedInput schema / properties / natal_longitude / description
      Previous value: -"Longitude of birth location in decimal degrees."New value: +"Birth longitude."
    • changedInput schema / properties / natal_points / description
      Previous value: -"Natal point IDs to target, e.g. ['sun','moon','asc','mc','saturn']. Omit for the 7 classical bodies."New value: +"E.g. ['sun','moon','asc','mc']. Default the 7 classical bodies."
    • changedInput schema / properties / natal_timezone / description
      Previous value: -"IANA timezone for the natal birth location (e.g. `America/Chicago`); required when the datetime is naive."New value: +"IANA zone for the natal birth location (local datetime)."
    • changedInput schema / properties / orb_deg / description
      Previous value: -"Orb in degrees that defines when a transit starts and ends (the in-orb window around each exact hit). Default 1. Greater than 0, at most 15."New value: +"In-orb window around each hit, degrees. Default 1, max 15."
    • changedInput schema / properties / start_date / description
      Previous value: -"Start of the transit search window. ISO 8601 date (YYYY-MM-DD) or zoned datetime; a naive clock time is rejected. A bare date covers the whole UTC day: start at 00:00, end at 23:59:59."New value: +"Window start. ISO 8601 date (whole UTC day) or zoned datetime."
    • changedInput schema / properties / transiting_planets / description
      Previous value: -"Transiting planet IDs to search, e.g. ['saturn','jupiter','uranus','pluto','chiron']. Omit to search Sun through Saturn; Uranus, Neptune, Pluto and Chiron are searched only when named."New value: +"E.g. ['saturn','pluto','chiron']. Default Sun through Saturn; outers and Chiron only when named."
  2. Changed6 schema fields changedv4.24.2
    • changedInput schema / properties / end_date / description
      Previous value: -"End of the transit search window. ISO 8601 date or zoned datetime; a naive clock time is rejected. Date-only resolves to 12:00 UTC."New value: +"End of the transit search window. ISO 8601 date (YYYY-MM-DD) or zoned datetime; a naive clock time is rejected. A bare date covers the whole UTC day: start at 00:00, end at 23:59:59."
    • changedInput schema / properties / natal_datetime / description
      Previous value: -"ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`."New value: +"ISO 8601 datetime. A datetime with no zone is rejected; give a `Z` or ±HH:MM suffix, or a local time with the `timezone` argument. Date-only resolves to 12:00 UTC."
    • changedInput schema / properties / natal_latitude / description
      Previous value: -"Latitude of birth location in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory."New value: +"Latitude of birth location in decimal degrees."
    • addedInput schema / properties / orb_deg
      Added value: +{
+  "description": "Orb in degrees that defines when a transit starts and ends (the in-orb window around each exact hit). Default 1. Greater than 0, at most 15.",
+  "type": "number"
+}
    • changedInput schema / properties / start_date / description
      Previous value: -"Start of the transit search window. ISO 8601 date or zoned datetime; a naive clock time is rejected. Date-only resolves to 12:00 UTC."New value: +"Start of the transit search window. ISO 8601 date (YYYY-MM-DD) or zoned datetime; a naive clock time is rejected. A bare date covers the whole UTC day: start at 00:00, end at 23:59:59."
    • changedInput schema / properties / transiting_planets / description
      Previous value: -"Transiting planet IDs to search, e.g. ['saturn','jupiter','uranus','pluto','chiron']. Omit to search all outer planets."New value: +"Transiting planet IDs to search, e.g. ['saturn','jupiter','uranus','pluto','chiron']. Omit to search Sun through Saturn; Uranus, Neptune, Pluto and Chiron are searched only when named."
  3. Addedv4.8.0

TDQS

A4.3/5.0
Behavior5/5

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

The annotations already establish read-only, idempotent, closed-world behavior, but the description adds substantial behavior: it returns inline visualization in Claude and ChatGPT versus a text summary elsewhere, every hit is clickable for an interpretation, hits carry in-orb start/end windows and pass numbers under retrograde, and transits already in orb include an applying/separating flag. It also discloses operational constraints the annotations cannot: the MAX SPAN per plan tier and the credit cost ladder. These are exactly the details an agent needs before committing a paid call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The body is front-loaded with the use-case triggers and return-value description, then shifts into labeled reference blocks (ASPECT ANGLES, EFFICIENCY, MAX SPAN, CREDIT COST) that are easy to scan. It is dense and the caps-heavy block formatting reads slightly like a pricing note, but nearly every sentence carries information the agent would otherwise have to guess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with no output schema, the description does the work the schema cannot: it describes the shape of the returned timeline, what each hit contains, the fallback rendering when inline UI is unavailable, and the hard limits of the date window. An agent has enough to decide whether to call it and how to size the request without further inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 the description genuinely adds to it: it restates the aspect-angle code table (0/60/90/120/180) in a compact lookup, discloses the efficiency hint that supplying transiting_planets and natal_points speeds up searches, and ties start_date/end_date to the plan-tier MAX SPAN. Only the birth-coordinate parameters are left entirely to the schema, which is reasonable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete verb and resource: an interactive, date-ordered transit timeline of exact hits with planet, natal point, aspect, and retrograde markers grouped by month. The emphasis on 'a forecast they should SEE' signals that this is visual/UI-oriented, which implicitly distinguishes it from the raw-data sibling queries. It never names a sibling outright (e.g., ephemeris_transits or human_design_transit_timeline), so differentiation is inferred 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The tool's purpose is grounded in five natural-language trigger phrases ('what's happening in my chart this month', 'when will Saturn hit my chart', etc.), which give the agent a clear routing signal. What's missing is the other half of the routing decision: there is no statement of when other tools are the better choice, even though ephemeris_transits and human_design_transit_timeline are obvious candidates.

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

Deploy Server

Other Tools