Open Ephemeris

Interactive Bi-Wheel Explorer

explore_bi_wheel

Read-onlyIdempotent

Generate an interactive bi-wheel to compare two natal charts for synastry, transits, returns, progressions, or composite/Davison relationships.

Instructions

Use this when the user asks 'are we compatible', 'synastry with my partner', 'what's my horoscope for today', 'what's hitting my chart right now' or 'what's my solar return chart this year' — any two-ring comparison they should SEE — or 'our composite chart' / 'our Davison chart' for a couple's single relationship wheel. Returns an interactive bi-wheel (inline in Claude and ChatGPT; text summary elsewhere): inner wheel Person 1's natal chart, outer ring by mode — synastry (Person 2's natal; needs their birthplace), transit (a date; today for a daily horoscope), progressed, solar_arc (target date), solar_return (target year), lunar_return (target month) — with cross-aspects drawn and every planet, aspect line and cusp clickable. composite and davison instead return ONE wheel derived from both births (Person 2's birth datetime and birthplace required; composite is the midpoint method with no angles or houses, davison has real ones). Birthplaces may be place names (location, person2_location).

CREDIT COST: 2 credits per call for most modes (1 per wheel; +1 to resolve a place name); solar_return/lunar_return modes cost 6; composite/davison cost 3. house_system (placidus default; whole_sign) sets both rings' houses.

Input Schema

Name	Required	Description
`mode`	No	Default synastry.
`location`	No	Person 1 place name, e.g. 'New York, NY'; geocoded. Coordinates win if given.
`house_system`	No	Default placidus; both rings.
`person1_name`	No	Person 1 display name.
`person2_name`	No	Person 2 display name.
`person1_datetime`	Yes	Person 1 / natal birth. ISO 8601; zone required (`Z`/offset, or local time plus `timezone`).
`person1_latitude`	No	Person 1 latitude (+N). Optional with `location`.
`person1_timezone`	No	IANA zone for Person 1's birth location (local datetime).
`person2_datetime`	Yes	Outer wheel: Person 2 birth (synastry/composite/davison), target date (transit/progressed/solar_arc), or a date in the target year/month (returns). ISO 8601; zone required (`Z`/offset, or local time plus `timezone`).
`person2_latitude`	No	Person 2 latitude. Required in synastry unless `person2_location`; other modes default to Person 1.
`person2_location`	No	Person 2 / outer-chart place name; coordinates win.
`person2_timezone`	No	IANA zone for Person 2 / the outer chart (local datetime).
`person1_longitude`	No	Person 1 longitude (+E). Optional with `location`.
`person2_longitude`	No	Person 2 longitude; same rule as latitude.

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedv4.29.0Oct 28, 2026

changedInput schema / properties / house_system / description

Previous value: -"House system the wheel draws and labels. Use whole_sign for Hellenistic / traditional readings. Defaults to placidus. Applies to every mode, both rings."New value: +"Default placidus; both rings."

changedInput schema / properties / location / description

Previous value: -"Person 1 / Natal location as a plain place name like 'New York, NY'; resolved to coordinates and timezone, and ambiguous names are rejected with a disambiguation hint. Supplied person1_latitude/person1_longitude take precedence."New value: +"Person 1 place name, e.g. 'New York, NY'; geocoded. Coordinates win if given."

changedInput schema / properties / mode / description

Previous value: -"Chart comparison mode. Defaults to 'synastry'."New value: +"Default synastry."

changedInput schema / properties / person1_datetime / description

Previous value: -"Birth datetime for Person 1 / Natal chart. 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: +"Person 1 / natal birth. ISO 8601; zone required (`Z`/offset, or local time plus `timezone`)."

changedInput schema / properties / person1_latitude / description

Previous value: -"Birth latitude for Person 1 (decimal degrees, positive = North). Optional if `location` is a place name — the resolver fills it in."New value: +"Person 1 latitude (+N). Optional with `location`."

changedInput schema / properties / person1_longitude / description

Previous value: -"Birth longitude for Person 1 (decimal degrees, positive = East). Optional if `location` is a place name."New value: +"Person 1 longitude (+E). Optional with `location`."

changedInput schema / properties / person1_name / description

Previous value: -"Display name for Person 1 / Natal chart (e.g. 'Alice'). Used in the badge and summary."New value: +"Person 1 display name."

changedInput schema / properties / person1_timezone / description

Previous value: -"IANA timezone for Person 1's birth location (e.g. `America/New_York`); required when the datetime is naive."New value: +"IANA zone for Person 1's birth location (local datetime)."

changedInput schema / properties / person2_datetime / description

Previous value: -"Datetime for the outer wheel. Meaning depends on mode: synastry/composite/davison = Person 2 birth datetime; transit/progressed/solar_arc = target date; solar_return/lunar_return = any date within the target year/month. 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: +"Outer wheel: Person 2 birth (synastry/composite/davison), target date (transit/progressed/solar_arc), or a date in the target year/month (returns). ISO 8601; zone required (`Z`/offset, or local time plus `timezone`)."

changedInput schema / properties / person2_latitude / description

Previous value: -"Birth latitude for Person 2. REQUIRED in synastry unless `person2_location` is given — never inferred from Person 1. Other modes default to Person 1's coords."New value: +"Person 2 latitude. Required in synastry unless `person2_location`; other modes default to Person 1."

changedInput schema / properties / person2_location / description

Previous value: -"Person 2 / outer-chart place name, resolved like `location`. person2_latitude/person2_longitude win."New value: +"Person 2 / outer-chart place name; coordinates win."

changedInput schema / properties / person2_longitude / description

Previous value: -"Birth longitude for Person 2. REQUIRED in synastry unless `person2_location` is given. Other modes default to Person 1's coords."New value: +"Person 2 longitude; same rule as latitude."

changedInput schema / properties / person2_name / description

Previous value: -"Display name for Person 2 (synastry mode). Used in the badge and summary."New value: +"Person 2 display name."

changedInput schema / properties / person2_timezone / description

Previous value: -"IANA timezone for Person 2 / the outer chart (e.g. `America/Chicago`); required when the datetime is naive."New value: +"IANA zone for Person 2 / the outer chart (local datetime)."

Changed6 schema fields changedv4.24.2Oct 24, 2026

addedInput schema / properties / house_system

Added value: +{
+  "description": "House system the wheel draws and labels. Use whole_sign for Hellenistic / traditional readings. Defaults to placidus. Applies to every mode, both rings.",
+  "enum": [
+    "placidus",
+    "whole_sign",
+    "equal",
+    "koch",
+    "campanus",
+    "regiomontanus"
+  ],
+  "type": "string"
+}

changedInput schema / properties / location / description

Previous value: -"Person 1 / Natal location. Prefer a plain place name like 'New York, NY' — resolved via the same lookup `location_search` uses; ambiguous names throw with a disambiguation hint. Supplied person1_latitude/person1_longitude win."New value: +"Person 1 / Natal location as a plain place name like 'New York, NY'; resolved to coordinates and timezone, and ambiguous names are rejected with a disambiguation hint. Supplied person1_latitude/person1_longitude take precedence."

changedInput schema / properties / mode / enum

Previous value: -[
-  "synastry",
-  "transit",
-  "progressed",
-  "solar_return",
-  "lunar_return",
-  "solar_arc"
-]New value: +[
+  "synastry",
+  "transit",
+  "progressed",
+  "solar_return",
+  "lunar_return",
+  "solar_arc",
+  "composite",
+  "davison"
+]

changedInput schema / properties / person1_datetime / description

Previous value: -"Birth datetime for Person 1 / Natal chart. 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: +"Birth datetime for Person 1 / Natal chart. 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 / person1_latitude / description

Previous value: -"Birth latitude for Person 1 (decimal degrees, positive = North). Optional if `location` is a place name — the resolver fills it in. Never recall coordinates from memory."New value: +"Birth latitude for Person 1 (decimal degrees, positive = North). Optional if `location` is a place name — the resolver fills it in."

changedInput schema / properties / person2_datetime / description

Previous value: -"Datetime for the outer wheel. Meaning depends on mode: synastry = Person 2 birth datetime; transit/progressed/solar_arc = target date; solar_return/lunar_return = any date within the target year/month. 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: +"Datetime for the outer wheel. Meaning depends on mode: synastry/composite/davison = Person 2 birth datetime; transit/progressed/solar_arc = target date; solar_return/lunar_return = any date within the target year/month. 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."

Addedv4.8.0Aug 3, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With readOnlyHint/idempotentHint already declared, the description still adds substantial non-obvious behavior: credit cost per mode (2, 6, and 3 credits respectively), the +1 charge for geocoding a place name, that the result renders inline in Claude/ChatGPT but as a text summary elsewhere, and that every planet/aspect line/cusp is clickable. It also discloses that composite carries no angles or houses while davison has real ones — a genuine semantic difference rather than a restatement of annotations.

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?

It is front-loaded with the recognition phrases an agent needs before anything else, and the mode-by-mode payload sentence carries high information density. It is nonetheless a long em-dash-chained paragraph, and the credit-cost sentence sits inside the same block rather than being separately skimmable, costing some structural clarity.

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 14-parameter, eight-mode tool with no output schema, the description covers the missing pieces: what the returned visual contains, what varies per mode, which inputs each mode requires, the house-system default, and the billing implication of calling it. An agent has enough to choose a mode, populate required fields, and predict the result without further probing.

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 adds cross-parameter meaning the schema only states piecewise: person2_datetime is repurposed per mode (birth, target date, or a date inside the target year/month), synastry specifically needs Person 2's birthplace, and house_system governs both rings' houses. Those are real clarifications of how parameters interact, though a few points (location/person2_location as place names) merely echo the schema.

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?

The description opens with a concrete verb+resource ('Returns an interactive bi-wheel') and immediately enumerates the exact artifact produced for each mode (inner natal wheel, outer ring varying by synastry/transit/progressed/solar_arc/returns). It explicitly separates the two-ring modes from composite/davison, which return 'ONE wheel derived from both births', so an agent can distinguish behavior inside this single tool without ambiguity.

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?

It provides unusually explicit trigger phrasing ('are we compatible', 'synastry with my partner', 'what's hitting my chart right now', 'our composite chart') and maps each to a mode, which is strong when-to-use guidance. It does not, however, route against sibling tools that overlap heavily (ephemeris_synastry, ephemeris_solar_return, ephemeris_progressed_chart, explore_natal_chart), so mode selection within this tool is covered but tool selection across the catalog is not.

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

Deploy Server

Interactive Bi-Wheel Explorer

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools