Open Ephemeris

Transit Search

ephemeris_transits

Read-onlyIdempotent

Returns exact dates when transiting planets form conjunctions, squares, trines, or oppositions to natal points within a chosen range, answering when transits such as Saturn returns occur.

Instructions

Use this when the user asks 'when is my Saturn return', 'when does Pluto square my Sun', 'what transits do I have this month or next year', 'my biggest transits this year' — any WHEN-does-a-transit-hit question, as data. Returns the exact moments transiting planets form the requested aspect to natal points over a date range; sort=significance adds ranked, the hits scored biggest first.

ASPECT ANGLES (aspect_angle): 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine. Saturn return → transiting_planets=['saturn'], natal_points=['saturn']. Default transiting_planets and natal_points: sun through saturn; naming fewer is faster. MAX SPAN: Explorer/PayG 1y, Pro 5y, Startup 10y, Scale 40y (longer = 400). CREDIT COST: 1 + span price: ≤1y 5, ≤3y 10, ≤5y 15, ≤10y 25, ≤20y 40, ≤40y 70. truncated:true = partial, with the resume point in truncation.resume_from.

Input Schema

Name	Required	Description
`sort`	No	time (default) or significance.
`end_date`	Yes	Window end. ISO 8601 date (whole UTC day) or zoned datetime.
`start_date`	Yes	Window start. ISO 8601 date (whole UTC day) or zoned datetime.
`aspect_angle`	No	Degrees added to each natal longitude: 0 conjunction (default), 90 square, 120 trine, 180 opposition.
`natal_points`	No	E.g. ['sun','moon','asc','mc']. Default all core points.
`natal_datetime`	Yes	ISO 8601; zone required (`Z`/offset, or local time plus `timezone`).
`natal_latitude`	Yes	Birth latitude.
`natal_timezone`	No	IANA zone for the natal birth location (local datetime).
`natal_longitude`	Yes	Birth longitude.
`transiting_planets`	No	E.g. ['saturn','pluto','chiron']. Default Sun through Saturn; outers and Chiron only when named.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv4.29.0Oct 28, 2026

changedInput schema / properties / aspect_angle / description

Previous value: -"Aspect angle in degrees to apply to each natal longitude. 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine. The effective search target becomes (natal_longitude + aspect_angle) mod 360."New value: +"Degrees added to each natal longitude: 0 conjunction (default), 90 square, 120 trine, 180 opposition."

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 whose exact longitudes should be targeted. E.g. ['sun', 'moon', 'asc', 'mc', 'saturn', 'chiron']. Omit for all core points."New value: +"E.g. ['sun','moon','asc','mc']. Default all core points."

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 / 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: -"List of 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."

Changed1 schema field changedv4.27.0Oct 25, 2026

addedInput schema / properties / sort

Added value: +{
+  "description": "time (default) or significance.",
+  "enum": [
+    "time",
+    "significance"
+  ],
+  "type": "string"
+}

Changed5 schema fields changedv4.24.2Oct 24, 2026

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."

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: -"List of transiting planet IDs to search. E.g. ['saturn', 'jupiter', 'uranus', 'pluto', 'chiron']. Omit to search all outer planets."New value: +"List of 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."

Changed5 schema fields changedv4.8.0Aug 3, 2026

changedInput schema / properties / end_date / description

Previous value: -"End of the transit search window, ISO 8601 date or datetime (e.g. '2026-06-30')."New 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."

changedInput schema / properties / natal_datetime / description

Previous value: -"ISO 8601 birth datetime for the natal chart."New 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`."

changedInput schema / properties / natal_latitude / description

Previous value: -"Latitude of birth location in decimal degrees."New value: +"Latitude of birth location in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory."

addedInput schema / properties / natal_timezone

Added value: +{
+  "description": "IANA timezone for the natal birth location (e.g. `America/Chicago`); required when the datetime is naive.",
+  "type": "string"
+}

changedInput schema / properties / start_date / description

Previous value: -"Start of the transit search window, ISO 8601 date or datetime (e.g. '2026-01-01')."New 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."

First observedv0.1.0Apr 24, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-inferable behavior: per-plan maximum spans, credit cost tiers by span, and truncation with a resume point (truncation.resume_from). Those are operational constraints an agent cannot get from the schema and would otherwise trip over.

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?

Front-loaded with the use case before the constraint details, and most sentences earn their place (costs, spans, truncation). A few compressed fragments — '(longer = 400)' and the duplicate statement of defaults in prose versus schema — cost some clarity for space.

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 still conveys the return shape (exact hit moments, `ranked` when sort=significance, truncated/partial results with resume point) and the quota limits that gate success. Nothing critical for a correct first call appears missing.

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 parameter documentation is already handled; the description still adds cross-parameter meaning — the aspect_angle degree convention, the Saturn-return combination of transiting_planets/natal_points, and the performance note that naming fewer planets is faster. The '(longer = 400)' fragment is opaque and doesn't cleanly explain the over-span failure mode.

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

Purpose5/5

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

States a specific verb and resource (returns exact moments transiting planets form an aspect to natal points over a date range) and frames it as the tool for any 'when does a transit hit' question. The example phrasings ('when is my Saturn return', 'when does Pluto square my Sun') make it trivially distinguishable from ephemeris_aspect_check or explore_transit_timeline.

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?

Strong positive routing: 'Use this when the user asks ... any WHEN-does-a-transit-hit question' plus a concrete recipe for the Saturn return case. It does not explicitly state when NOT to use it or name an alternative sibling (e.g. explore_transit_timeline or human_design_transit_timeline), so it falls short of the 5 bar.

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

Deploy Server

Transit Search

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools