@openephemeris/mcp-server 4.15.0 → 4.16.0

package/dist/tools/specialized/ephemeris_core.js

@@ -5,16 +5,21 @@ import { DATETIME_DESC, TIMEZONE_PROPERTY, toDateTimeInputBody } from "../dateti
 // POST /ephemeris/planet-position — OE-016
 registerTool({
     name: "ephemeris_planet_position",
-    description: "Get the precise ecliptic longitude, latitude, distance, speed, and retrograde status " +
-        "for a single planet/body at a given date and time. " +
-        "Planet IDs: 0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, " +
-        "7=Uranus, 8=Neptune, 9=Pluto, 10=North Node (Mean), 11=North Node (True), " +
-        "12=Lilith (Mean), 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta.\n\n" +
-        "SOUTH NODE: there is no South Node id. The South Node is always exactly " +
-        "opposite the North Node — request id 10 or 11 and add 180° (mod 360).\n\n" +
+    description: "Use this when the user asks 'where is Mars right now', 'what sign is Venus in today', 'what " +
+        "degree is the Sun at', 'where was Jupiter on my birthday', 'where is the North Node' — one body " +
+        "at one moment — or 'what's my star sign / zodiac sign' from a birth date alone (planet_id=0; a " +
+        "bare date resolves to noon UTC, no location needed). Returns ecliptic longitude, latitude, " +
+        "distance, speed and retrograde flag.\n\n" +
+        "PLANET IDS: 0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, " +
+        "9=Pluto, 10=North Node (Mean), 11=North Node (True), 12=Lilith (Mean), 15=Chiron, 17=Ceres, " +
+        "18=Pallas, 19=Juno, 20=Vesta.\n" +
+        "SOUTH NODE: no id — take id 10 or 11 and add 180° (mod 360).\n" +
+        "NODES: despite its name, id 10 returns the osculating TRUE node (DE440, ecliptic of date) — the " +
+        "Human Design node; it wobbles ±1.7° about the mean and can go direct, which is correct. Id 11 is " +
+        "the analytical true node. Neither is a classical mean node.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: Where is Mars on 2026-03-20 at noon UTC?\n" +
-        "  planet_id=4, datetime='2026-03-20T12:00:00Z'",
+        "Do not use for the Moon's phase — use ephemeris_moon_phase; for 'is X retrograde' use " +
+        "ephemeris_retrograde_status; for a whole birth chart use ephemeris_natal_chart.",
     inputSchema: {
         type: "object",
         properties: {
@@ -57,12 +62,14 @@ registerTool({
 // POST /ephemeris/house-cusps — OE-017
 registerTool({
     name: "ephemeris_house_cusps",
-    description: "Calculate house cusps and angles (ASC, MC, DSC, IC) for a given date, time, and location " +
-        "using one or more house systems.\n\n" +
-        "House system codes: P=Placidus, K=Koch, O=Porphyry, R=Regiomontanus, C=Campanus, E=Equal, W=Whole Sign.\n\n" +
+    description: "Use this when the user asks 'what are my house cusps', 'where does my 7th house start', 'show my " +
+        "houses in Whole Sign' or 'compare Placidus and Koch for my chart' — houses and angles only, for " +
+        "a date, time and place. Returns the twelve cusps and ASC/MC/DSC/IC for each requested system.\n\n" +
+        "HOUSE SYSTEM CODES: P=Placidus, K=Koch, O=Porphyry, R=Regiomontanus, C=Campanus, E=Equal, " +
+        "W=Whole Sign.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: Placidus houses for London at 2026-03-20 noon UTC:\n" +
-        "  datetime='2026-03-20T12:00:00Z', latitude=51.5074, longitude=-0.1278, house_systems=['P']",
+        "Do not use for a full birth chart with planets — use ephemeris_natal_chart; for the Vertex and " +
+        "equatorial ascendant use ephemeris_angles_points.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/ephemeris_extended.js

@@ -96,16 +96,15 @@ registerTool({
 // the documented "all planets" behaviour works correctly.
 registerTool({
     name: "ephemeris_retrograde_status",
-    description: "Get retrograde/direct status and speed for ONE planet — or, if you ask for it, all " +
-        "ten — at a given date/time. Returns is_retrograde flag, longitude speed, and station " +
-        "proximity.\n\n" +
-        "✅  Answers 'is X retrograde?' at ONE instant. Pass planet_id for the named planet; " +
-        "'is Mercury retrograde?' is planet_id=2, not a whole-sky sweep. For WHEN a planet turns " +
-        "retrograde or direct, or whether it stations anywhere in a date range, use " +
-        "electional_station_tracker.\n\n" +
-        "CREDIT COST: 1 credit for a single planet (pass planet_id). Omitting planet_id runs the " +
-        "all-planets sweep and costs 10 credits — the backend bills one credit per body and this " +
-        "fans out to 10. Only omit it when the question really is about every planet.",
+    description: "Use this when the user asks 'is Mercury retrograde right now', 'is Venus retrograde today', 'was " +
+        "Mars retrograde when I was born' or 'which planets are retrograde at the moment'. Returns " +
+        "is_retrograde, longitude speed and station proximity for ONE planet at one instant — pass " +
+        "planet_id ('is Mercury retrograde?' is planet_id=2, not a whole-sky sweep) — or for all ten when " +
+        "planet_id is omitted.\n\n" +
+        "CREDIT COST: 1 credit for a single planet. Omitting planet_id fans out to 10 credits (one per " +
+        "body); only omit it when the question really is about every planet.\n\n" +
+        "Do not use for WHEN a planet turns retrograde or direct, or whether it stations in a date range " +
+        "— use electional_station_tracker.",
     inputSchema: {
         type: "object",
         properties: {
@@ -275,11 +274,13 @@ registerTool({
 // POST /ephemeris/angles-points
 registerTool({
     name: "ephemeris_angles_points",
-    description: "Calculate chart angles and sensitive points (ASC, MC, DSC, IC, Vertex, " +
-        "Equatorial Ascendant/Descendant) for a given date/time and location. " +
-        "The equatorial ascendant is also returned under the key `east_point` — " +
-        "a synonym for the same point, not a separate one.\n\n" +
-        "CREDIT COST: 1 credit per call.",
+    description: "Use this when the user asks 'where is my Vertex', 'what's my East Point / equatorial ascendant' " +
+        "or 'what are my chart angles' for a date, time and place. Returns ASC, MC, DSC, IC, Vertex and " +
+        "the Equatorial Ascendant/Descendant; the equatorial ascendant is also returned under " +
+        "`east_point` — a synonym for the same point, not a separate one.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "Do not use for house cusps — use ephemeris_house_cusps; for the full chart use " +
+        "ephemeris_natal_chart.",
     inputSchema: {
         type: "object",
         properties: {
@@ -305,11 +306,13 @@ registerTool({
 // POST /ephemeris/aspect-check
 registerTool({
     name: "ephemeris_aspect_check",
-    description: "Check the aspect between two ecliptic longitudes. Returns the angular separation " +
-        "and any aspects within orb (conjunction, sextile, square, trine, opposition, etc.).\n\n" +
+    description: "Use this when the user asks 'is 15° Aries square 18° Cancer', 'what aspect is between these two " +
+        "positions', 'how many degrees apart are my Sun and Moon' or 'is this within orb'. Returns the " +
+        "angular separation between two ecliptic longitudes (longitude_1, longitude_2) and any aspect " +
+        "within orb (conjunction, sextile, square, trine, opposition, etc.).\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: Check aspect between 15° Aries and 75° Gemini:\n" +
-        "  longitude_1=15, longitude_2=75",
+        "Do not use to find WHEN a transit forms an aspect — use ephemeris_transits; for a whole chart's " +
+        "aspect grid use ephemeris_natal_chart.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/hd_bodygraph.js

@@ -9,7 +9,7 @@ registerTool({
         "Renders the full bodygraph circuit board showing all 9 centers, 36 channels, and 64 gates " +
         "with Personality (conscious) and Design (unconscious) activations color-coded. " +
         "Defined centers are filled with their HD doctrine color; open/undefined centers remain muted. " +
-        "Returns a native SVG that Claude displays inline. Use format='png' to opt into raster output (requires server-side rasterizer).\n\n" +
+        "Returns a native SVG the host displays inline. Use format='png' to opt into raster output (requires server-side rasterizer).\n\n" +
         "For a user-facing interactive bodygraph explorer, use explore_human_design instead.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
         "EXAMPLE (local birth time + zone): born 15 April 1990 at 14:30 in Chicago:\n" +
@@ -42,7 +42,7 @@ registerTool({
             format: {
                 type: "string",
                 enum: ["svg", "png"],
-                description: "Output format. Defaults to 'svg' (pure Go renderer — no external deps, displays natively in Claude). Use 'png' for raster output (requires server-side rasterizer).",
+                description: "Output format. Defaults to 'svg' (pure Go renderer — no external deps, displays inline in any host that renders images). Use 'png' for raster output (requires server-side rasterizer).",
             },
         },
         required: ["datetime"],

package/dist/tools/specialized/human_design.js

@@ -5,21 +5,18 @@ import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
 registerTool({
     name: "human_design_chart",
-    description: "Calculate a full Human Design I Ching hexagram chart from birth data. Returns the person's Type " +
-        "(Generator, Manifesting Generator, Projector, Manifestor, Reflector), Strategy, Authority, " +
-        "Profile (e.g. 1/3, 2/4), defined and undefined Centers, activated Gates and Channels, " +
-        "Incarnation Cross, and both Personality (conscious) and Design (unconscious) planetary positions.\n\n" +
-        "Returns raw JSON. For a user-facing interactive bodygraph, use explore_human_design instead.\n\n" +
+    description: "Use this when the Human Design chart is wanted as data — 'give me my HD activations', 'which " +
+        "planets sit in which gates, design and personality', 'what are my variables', 'my Human Design " +
+        "chart as JSON' — the fields the visual tool omits. Returns Type, Strategy, Authority, Profile, " +
+        "defined and undefined Centers, activated Gates and Channels, Incarnation Cross, and both " +
+        "Personality (birth) and Design (~88° of Sun before birth) planetary positions.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
-        "Human Design uses two calculation moments: the birth time (Personality) and ~88° of Sun motion " +
-        "before birth (~3 months prior, the Design calculation). The API handles this automatically.\n\n" +
-        "The datetime must state its zone — pass an offset/'Z', or pass local time plus timezone. " +
-        "A zone-less datetime is rejected rather than assumed to be UTC: Human Design is minute-sensitive, " +
-        "and an hour of error changes the Profile and the Design Sun line.\n\n" +
-        "EXAMPLE (local birth time + zone): someone born 15 April 1990 at 14:30 in Chicago:\n" +
-        "  datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298\n" +
-        "EXAMPLE (already in UTC):\n" +
-        "  datetime='1990-04-15T19:30:00Z', latitude=41.8781, longitude=-87.6298",
+        "HD is minute-sensitive: pass the local birth time with its zone (or an offset/'Z'); a zone-less " +
+        "datetime is rejected, because an hour of error changes the Profile and the Design Sun line. " +
+        "Takes coordinates, not a place name.\n\n" +
+        "Do not use for 'what's my type / profile / authority' or when the user should SEE a bodygraph — " +
+        "use explore_human_design; for today's transits on their chart use explore_human_design_transit; " +
+        "for two people use explore_human_design_connection.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/moon.js

@@ -5,17 +5,14 @@ import { TIMEZONE_PROPERTY } from "../datetime.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
 registerTool({
     name: "ephemeris_moon_phase",
-    description: "Get the Moon's current phase angle, illumination, sign and void-of-course status AT a " +
-        "specific point in time. Returns phase name (New, Waxing Crescent, etc.), illumination %, " +
-        "the zodiac sign and degree the Moon occupies, and next void-of-course period.\n\n" +
-        "⚠️  THIS TOOL ANSWERS: 'What phase is the moon in right now (or at a given datetime)?' and " +
-        "'What sign is the moon in?'\n" +
-        "❌  THIS TOOL DOES NOT ANSWER: 'When is the next new moon / full moon?'\n" +
-        "→   For upcoming phase DATES use ephemeris_next_lunar_phase instead.\n\n" +
-        "For a user-facing interactive moon-phase dial, use explore_moon_phase instead.\n\n" +
-        "CREDIT COST: 2 credits — phase and void-of-course are metered separately. For " +
-        "phase alone at 1 credit, use dev_read_api path='/ephemeris/moon/phase'.\n\n" +
-        "If no datetime is provided, returns the current (live) moon phase.",
+    description: "Use this when the Moon's state is wanted as data for a specific moment — 'what phase was the " +
+        "Moon on my birthday', 'what sign was the Moon in on 12 May 1990', 'moon phase and illumination " +
+        "as numbers'. Returns phase name, illumination %, the Moon's sign and degree, and the next " +
+        "void-of-course window; omit datetime for right now.\n\n" +
+        "CREDIT COST: 2 credits — phase and void-of-course are metered separately. For phase alone at 1 " +
+        "credit, use dev_read_api path='/ephemeris/moon/phase'.\n\n" +
+        "Do not use for tonight's moon or 'what sign is the Moon in' right now — use explore_moon_phase; " +
+        "for the DATE of the next new or full moon use ephemeris_next_lunar_phase.",
     inputSchema: {
         type: "object",
         properties: {
@@ -64,21 +61,13 @@ registerTool({
 });
 registerTool({
     name: "ephemeris_next_lunar_phase",
-    description: "Find the next occurrence of a specific Moon phase after a given date. " +
-        "Returns the exact UTC datetime of each occurrence.\n\n" +
-        "✅  USE THIS TOOL FOR: 'When is the next new moon?', 'When is the next full moon?', " +
-        "'What date is the next quarter moon?', or any question about UPCOMING phase dates.\n" +
-        "❌  NOT FOR: 'What phase is the moon in right now?' or 'What sign is the moon in?'\n" +
-        "→   For the phase, sign and degree AT a moment, use ephemeris_moon_phase.\n\n" +
-        "CREDIT COST: 1-2 credits per occurrence returned — each occurrence takes one " +
-        "calendar search, plus a second search when the first window misses. So count=3 " +
-        "costs 3-6 credits.\n\n" +
-        "EXAMPLE: Find the next new moon:\n" +
-        "  phase='new_moon'\n\n" +
-        "EXAMPLE: Find the next full moon after a specific date:\n" +
-        "  phase='full_moon', after_date='2026-06-01'\n\n" +
-        "EXAMPLE: Find the next 3 full moons:\n" +
-        "  phase='full_moon', count=3",
+    description: "Use this when the user asks 'when is the next full moon', 'when is the next new moon', 'what " +
+        "date is the next quarter moon' or 'list the next 3 full moons'. Returns the exact UTC datetime " +
+        "of each upcoming occurrence of the requested phase (phase = new_moon | full_moon | first_quarter " +
+        "| last_quarter), optionally after a given date and for count occurrences.\n\n" +
+        "CREDIT COST: 10-20 credits per occurrence (calendar endpoint); keep count=1 unless asked.\n\n" +
+        "Do not use for the phase or sign the Moon is in right now — use ephemeris_moon_phase; for " +
+        "eclipses use ephemeris_next_eclipse.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/natal.js

@@ -24,15 +24,16 @@ const HOUSE_SYSTEM_MAP = {
 };
 registerTool({
     name: "ephemeris_natal_chart",
-    description: "Calculate a full natal (birth) chart for a person. Returns planetary positions, house cusps, " +
-        "aspects, and chart patterns. Use format='llm' for a compact, token-efficient output ideal for " +
-        "interpretation (available on all tiers). The result includes all major planets, Chiron and major asteroids like Ceres, angles (ASC/MC/DSC/IC), " +
-        "essential dignities, retrograde status, house system data, and major aspect grid. Asteroids are automatically included. " +
-        "Returns raw JSON. For a user-facing visual chart, use explore_natal_chart instead.\n\n" +
+    description: "Use this when the birth chart is wanted as data rather than a picture — 'give me my chart as " +
+        "JSON', 'list my natal aspects with orbs', 'what exact degree is my Ascendant', 'my placements as " +
+        "a table' — or as the input to a further calculation. Returns raw JSON: all major planets plus " +
+        "Chiron and the major asteroids (Ceres, Pallas, Juno, Vesta), angles (ASC/MC/DSC/IC), house " +
+        "cusps, dignity condition, retrograde flags and the major aspect grid; pass format='llm' for " +
+        "compact output. Takes coordinates, not a place name — resolve a city with location_search first.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: born 15 April 1990 at 2:30 PM local time in Chicago — pass the local time and name the zone:\n" +
-        "  datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298\n" +
-        "Equivalently, put the zone on the datetime: datetime='1990-04-15T14:30:00-05:00' (or the UTC instant '1990-04-15T19:30:00Z').",
+        "Do not use when the user wants to SEE the chart — use explore_natal_chart; for houses alone use " +
+        "ephemeris_house_cusps; for one planet use ephemeris_planet_position; for a Vedic/sidereal chart " +
+        "use vedic_chart.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/progressed.js

@@ -4,13 +4,13 @@ import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY, WINDOW_DATE_DESC, assertZonedDatetime } from "../datetime.js";
 registerTool({
     name: "ephemeris_progressed_chart",
-    description: "Calculate a Secondary Progressed (or Solar Arc / Tertiary) chart. " +
-        "Advances the natal chart symbolically — 1 day = 1 year (secondary), or using solar arc motion. " +
-        "Returns progressed planet positions, house cusps, aspects, and retrograde status.\n\n" +
+    description: "Use this when the user asks 'what's my progressed chart', 'where is my progressed Moon / Sun', " +
+        "'what sign has my progressed Moon moved into' or 'my solar arc directions'. Returns progressed " +
+        "planet positions, house cusps, aspects and retrograde status for a target date — method = " +
+        "secondary (1 day = 1 year, default), solar_arc or tertiary.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: Secondary progressions for someone born 1985-06-21 at 2:00 PM in London, progressed to 2026-01-01:\n" +
-        "  birth_datetime='1985-06-21T14:00:00', timezone='Europe/London',\n" +
-        "  birth_latitude=51.5, birth_longitude=-0.12, target_datetime='2026-01-01', method='secondary'",
+        "Do not use for this year's birthday chart — use ephemeris_solar_return; to SEE progressions over " +
+        "the natal wheel use explore_bi_wheel (mode='progressed').",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/relocation.js

@@ -4,14 +4,13 @@ import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime } from "../datetime.js";
 registerTool({
     name: "ephemeris_relocation",
-    description: "Calculate a relocation chart — the same natal planetary positions re-cast for a different " +
-        "geographic location. Used to understand how living in a different city shifts house placements " +
-        "and angles, without changing the planetary longitudes in the chart.\n\n" +
+    description: "Use this when the user asks 'how does my chart change if I move to London', 'what's my relocated " +
+        "Ascendant in Tokyo' or 'recast my chart for where I live now'. Returns the natal chart re-cast " +
+        "for a new location — the same planetary longitudes with the houses and angles that place gives " +
+        "them.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: How does moving from Chicago to London change someone's chart?\n" +
-        "  natal_datetime='1990-04-15T14:30:00', timezone='America/Chicago',\n" +
-        "  natal_latitude=41.8781, natal_longitude=-87.6298,\n" +
-        "  relocation_latitude=51.5074, relocation_longitude=-0.1278",
+        "Do not use for 'is this city good for me' or which planetary lines cross a place — use acg_hits; " +
+        "for the full astrocartography map use acg_power_lines.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/returns.js

@@ -5,15 +5,13 @@ import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, toDateTimeInputB
 // POST /predictive/returns/solar
 registerTool({
     name: "ephemeris_solar_return",
-    description: "Calculate the exact Solar Return date/time — when the Sun returns to its natal ecliptic longitude " +
-        "(happens once per year near the birthday). Returns the Solar Return chart for the year ahead.\n\n" +
+    description: "Use this when the user asks 'when exactly is my solar return', 'my solar return positions as " +
+        "data' or 'my solar return for 2027 as JSON'. Returns the exact moment the Sun returns to its " +
+        "natal longitude near the birthday and the Solar Return chart for that year; target_datetime " +
+        "picks the year (defaults to the current one).\n\n" +
         "CREDIT COST: 5 credits per call.\n\n" +
-        "TARGET DATE: Provide target_datetime near the desired birthday year. " +
-        "If omitted, defaults to the current year's solar return.\n\n" +
-        "EXAMPLE: Solar return for someone born 1985-06-21 (current year):\n" +
-        "  birth_datetime='1985-06-21T14:00:00Z'\n\n" +
-        "EXAMPLE: Solar return for 2027 specifically:\n" +
-        "  birth_datetime='1985-06-21T14:00:00Z', target_datetime='2027-01-01T00:00:00Z'",
+        "Do not use when the user should SEE it over their natal chart — use explore_bi_wheel " +
+        "(mode='solar_return'); for progressions use ephemeris_progressed_chart.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/synastry.js

@@ -4,15 +4,14 @@ import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, assertZonedDatetime, timezoneProperty } from "../datetime.js";
 registerTool({
     name: "ephemeris_synastry",
-    description: "Calculate a synastry chart comparing two people's natal charts. Returns inter-aspects " +
-        "(planetary connections between the two charts), composite points, and relationship indicators. " +
-        "Use this for compatibility analysis, relationship timing, or partnership insights.\n\n" +
+    description: "Use this when the relationship comparison is wanted as data — 'list our inter-aspects with " +
+        "orbs', 'what aspects does their Mars make to my Venus', 'our synastry as JSON'. Returns the " +
+        "cross-aspects between the two charts plus both natal charts; needs each person's birth datetime, " +
+        "zone and coordinates.\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
-        "EXAMPLE: Compare two people's charts (local birth times, each with its zone):\n" +
-        "  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',\n" +
-        "  person_a_latitude=41.8781, person_a_longitude=-87.6298,\n" +
-        "  person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles',\n" +
-        "  person_b_latitude=34.0522, person_b_longitude=-118.2437",
+        "Do not use for 'are we compatible' or when the user should SEE the comparison — use " +
+        "explore_bi_wheel (mode='synastry'); for Human Design compatibility use " +
+        "explore_human_design_connection.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/transits.js

@@ -4,20 +4,21 @@ import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, WINDOW_DATE_DESC, timezoneProperty } from "../datetime.js";
 registerTool({
     name: "ephemeris_transits",
-    description: "Search for astrological transit events affecting a natal chart over a date range. " +
-        "Returns exact transit moments — when transiting planets form specified aspects " +
-        "to natal planet positions.\n\n" +
-        "EFFICIENCY TIP: Always specify both transiting_planets and natal_points to keep " +
-        "compute fast. Omitting both sends all outer planets against all core natal positions " +
-        "— a much heavier computation.\n\n" +
-        "ASPECT ANGLES: Use aspect_angle to search for specific aspects:\n" +
-        "  0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine.\n" +
-        "  Example: Saturn Return → transiting_planets=['saturn'], natal_points=['saturn'], aspect_angle=0\n" +
-        "  Example: Uranus Opposition → transiting_planets=['uranus'], natal_points=['uranus'], aspect_angle=180\n" +
-        "  Example: Outer planets to natal Sun/Moon → transiting_planets=['saturn','uranus','neptune','pluto'], natal_points=['sun','moon']\n\n" +
-        "DEFAULT natal_points (when omitted): sun, moon, mercury, venus, mars, jupiter, saturn.\n" +
-        "SEARCH RANGE LIMITS: Explorer/PayG tier → 1 year max; Pro → 5 years; Startup → 10 years.\n" +
-        "CREDIT COST: 5 credits per call.",
+    description: "Use this when the user asks 'when is my Saturn return', 'when does Pluto square my Sun', 'when " +
+        "will Jupiter conjunct my Moon', 'what transits do I have next 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.\n\n" +
+        "ASPECT ANGLES (aspect_angle): 0 = conjunction/return (default), 180 = opposition, 90 = square, " +
+        "120 = trine. Saturn return → transiting_planets=['saturn'], natal_points=['saturn'], " +
+        "aspect_angle=0.\n" +
+        "EFFICIENCY: always pass transiting_planets and natal_points — omitting both sweeps all outer " +
+        "planets against all core points and is slow. DEFAULT natal_points: sun, moon, mercury, venus, " +
+        "mars, jupiter, saturn.\n" +
+        "SEARCH RANGE LIMITS: Explorer/PayG → 1 year; Pro → 5 years; Startup → 10 years.\n" +
+        "CREDIT COST: 6 credits per call (natal chart + search).\n\n" +
+        "Do not use when the user should SEE a forecast — use explore_transit_timeline; for the sky today " +
+        "with no birth data use electional_moment_analysis; for retrograde dates use " +
+        "electional_station_tracker.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/vedic.js

@@ -5,13 +5,14 @@ import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
 registerTool({
     name: "vedic_chart",
-    description: "Calculate a Vedic (Jyotish) natal chart with sidereal positions. Returns planet placements " +
-        "in rashis (sidereal signs), nakshatras with pada, navamsa placements, and bhavas (houses). " +
-        "Uses Whole Sign houses, sidereal zodiac with configurable ayanamsa.\n\n" +
-        "CREDIT COST: 1 credit per call.\n\n" +
+    description: "Use this when the Vedic / Jyotish chart is wanted as data — 'my sidereal placements as JSON', " +
+        "'nakshatra and pada for every planet as a table', 'my navamsa positions'. Takes coordinates, not " +
+        "a place name. Returns sidereal planet placements in rashis, nakshatras with pada, navamsa " +
+        "placements and bhavas (Whole Sign houses).\n\n" +
         "SUPPORTED AYANAMSA: lahiri (default), fagan_bradley, krishnamurti, raman, yukteshwar\n\n" +
-        "EXAMPLE: Vedic chart for someone born Jan 15, 1990 at 8:30 AM UTC in Mumbai:\n" +
-        "  datetime='1990-01-15T08:30:00Z', latitude=19.076, longitude=72.8777",
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "Do not use for 'what's my nakshatra / rashi / lagna' or when the user should SEE the chart — use " +
+        "explore_vedic_chart; for a Western tropical chart use ephemeris_natal_chart.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/ui-meta.d.ts

@@ -0,0 +1,14 @@
+export interface UiMetaSource {
+    name?: string;
+    _meta?: {
+        ui?: {
+            resourceUri?: string;
+            visibility?: Array<"app" | "model">;
+        };
+    };
+}
+/**
+ * Build the `_meta` wrapper for a tool, or `{}` when the tool renders no UI
+ * and has no invocation status. Spread the result into the tools/list entry.
+ */
+export declare function buildUiMeta(tool: UiMetaSource): Record<string, unknown>;

package/dist/tools/ui-meta.js

@@ -0,0 +1,57 @@
+/**
+ * src/tools/ui-meta.ts — the `_meta` block a tool carries when it renders an MCP App.
+ *
+ * One builder, used by both transports (stdio `src/index.ts`, remote
+ * `src/server-sse.ts`), because the two had drifted into copy-paste twins of the
+ * same object literal and only one of them would ever get updated.
+ *
+ * Three wire forms, all describing the same `ui://` resource:
+ *
+ *   1. `_meta.ui.{resourceUri,visibility}` — the canonical MCP Apps form
+ *      (SEP-1865, first official MCP extension 2026-01-26, folded into the
+ *      2026-07-28 spec). This is what the spec says hosts read.
+ *   2. `_meta["ui/resourceUri"]` — the deprecated flat alias. The spec says it
+ *      "will be removed before general availability"; kept only for pre-GA
+ *      hosts still on the older shape. Drop it once those are gone.
+ *   3. `_meta["openai/*"]` — ChatGPT's compatibility aliases. OpenAI co-authored
+ *      SEP-1865 and its own reference documents `openai/outputTemplate` as an
+ *      "optional/compatibility alias for `_meta.ui.resourceUri`", so a fully
+ *      converged ChatGPT host needs nothing here. Emitting it anyway is a few
+ *      bytes and removes the question of which side converged first.
+ *
+ * `openai/widgetAccessible` marks a tool the widget itself may invoke. That is
+ * exactly what `visibility` already encodes: a tool visible to "app" is one the
+ * iframe calls (the `*_recalculate` and `*_on_*_click` handlers), so the flag is
+ * derived rather than hand-maintained on 92 tools.
+ *
+ * The same block also carries ChatGPT's invocation status text
+ * (`openai/toolInvocation/invoking` / `invoked`, from invocation-status.ts)
+ * for any tool that has an entry there, UI or not — so a tool without a
+ * widget still gets a sentence instead of the host's generic spinner.
+ */
+import { INVOCATION_STATUS } from "./invocation-status.js";
+const DEFAULT_VISIBILITY = ["model", "app"];
+/**
+ * Build the `_meta` wrapper for a tool, or `{}` when the tool renders no UI
+ * and has no invocation status. Spread the result into the tools/list entry.
+ */
+export function buildUiMeta(tool) {
+    const meta = {};
+    const resourceUri = tool._meta?.ui?.resourceUri;
+    if (resourceUri) {
+        const visibility = tool._meta?.ui?.visibility ?? DEFAULT_VISIBILITY;
+        // Deprecated flat form — pre-GA hosts only.
+        meta["ui/resourceUri"] = resourceUri;
+        // Canonical MCP Apps form.
+        meta.ui = { resourceUri, visibility };
+        // ChatGPT compatibility aliases.
+        meta["openai/outputTemplate"] = resourceUri;
+        meta["openai/widgetAccessible"] = visibility.includes("app");
+    }
+    const status = tool.name ? INVOCATION_STATUS[tool.name] : undefined;
+    if (status) {
+        meta["openai/toolInvocation/invoking"] = status.invoking;
+        meta["openai/toolInvocation/invoked"] = status.invoked;
+    }
+    return Object.keys(meta).length ? { _meta: meta } : {};
+}

package/dist/ui/bazi.html

@@ -6802,7 +6802,7 @@ function E_(e4, t2, n2 = []) {
     let e5 = document.getElementById("fs-hint-banner");
     e5 && e5.remove();
     let t3 = document.createElement("div");
-    t3.id = "fs-hint-banner", Object.assign(t3.style, { position: "fixed", top: "12px", left: "50%", transform: "translateX(-50%)", background: "oklch(14% 0.012 265 / 0.90)", backdropFilter: "blur(12px)", WebkitBackdropFilter: "blur(12px)", border: "1px solid oklch(72% 0.12 80 / 0.3)", borderRadius: "20px", padding: "6px 16px", fontSize: "11px", fontWeight: "600", color: "oklch(80% 0.08 80)", letterSpacing: "0.04em", zIndex: "9999", pointerEvents: "none", opacity: "0", transition: "opacity 300ms ease", whiteSpace: "nowrap" }), t3.textContent = "Esc \u2014 exit fullscreen & return to Claude chat", document.body.appendChild(t3), requestAnimationFrame(() => {
+    t3.id = "fs-hint-banner", Object.assign(t3.style, { position: "fixed", top: "12px", left: "50%", transform: "translateX(-50%)", background: "oklch(14% 0.012 265 / 0.90)", backdropFilter: "blur(12px)", WebkitBackdropFilter: "blur(12px)", border: "1px solid oklch(72% 0.12 80 / 0.3)", borderRadius: "20px", padding: "6px 16px", fontSize: "11px", fontWeight: "600", color: "oklch(80% 0.08 80)", letterSpacing: "0.04em", zIndex: "9999", pointerEvents: "none", opacity: "0", transition: "opacity 300ms ease", whiteSpace: "nowrap" }), t3.textContent = "Esc \u2014 exit fullscreen & return to chat", document.body.appendChild(t3), requestAnimationFrame(() => {
       t3.style.opacity = "1";
     }), setTimeout(() => {
       t3.style.opacity = "0", setTimeout(() => t3.remove(), 350);
@@ -6856,6 +6856,11 @@ async function V_(e4) {
   }
 }
 async function H_(e4) {
+  let t2 = F_ == null ? void 0 : F_._birth_params;
+  if (t2) {
+    let n2 = String(t2.hour).padStart(2, "0");
+    e4 = "BaZi chart: ".concat(t2.year, "-").concat(String(t2.month).padStart(2, "0"), "-").concat(String(t2.day).padStart(2, "0"), " ").concat(n2, ":00\n\n").concat(e4);
+  }
   try {
     (await P_.sendMessage({ role: "user", content: [{ type: "text", text: e4 }] })).isError && console.error("[BaZi] Host rejected sendMessage");
   } catch (e5) {