@openephemeris/mcp-server 4.15.1 → 4.17.0

package/dist/tools/specialized/acg.js

@@ -10,17 +10,14 @@ const ACG_BODY_DESCRIPTION = "List of celestial bodies for line calculation. " +
 // POST /acg/power-lines — OE-018
 registerTool({
     name: "acg_power_lines",
-    description: "Calculate Astrocartography power lines (MC, IC, AC/ASC, DC/DSC) for a natal chart. " +
-        "Returns GeoJSON LineStrings tracing each planetary angle line around the globe. " +
-        "These are the latitudinal lines where a planet was rising (AC), setting (DC), " +
-        "culminating (MC), or anti-culminating (IC) at birth.\n\n" +
-        "❌  NOT FOR: 'Is [city] good for me?' or 'What planets affect me in Tokyo?' " +
-        "→ For a specific city/location analysis, use acg_hits instead (faster and more relevant).\n" +
-        "✅  USE FOR: Getting the full global GeoJSON line geometry for map rendering or bulk geographic analysis.\n\n" +
-        "CREDIT COST: 10 credits per call.\n\n" +
-        "EXAMPLE: Saturn and Jupiter power lines for a chart born 1990-04-15 at 2:30 PM in Chicago:\n" +
-        "  birth_datetime='1990-04-15T14:30:00', timezone='America/Chicago',\n" +
-        "  birth_latitude=41.8781, birth_longitude=-87.6298, bodies=['Saturn', 'Jupiter']",
+    description: "Use this when the user asks 'show my astrocartography map', 'where are my Jupiter lines', 'where " +
+        "in the world is my Sun on the MC', or wants the whole-world list of their lines. Returns, per " +
+        "planet, its MC, IC, AC and DC lines (where it was culminating, anti-culminating, rising or " +
+        "setting at birth) with sign and equator-crossing longitude — geometry stripped, not for map " +
+        "rendering.\n\n" +
+        "CREDIT COST: 10 credits per call. Pro tier.\n\n" +
+        "Do not use for 'is [city] good for me' or 'what lines run through Paris' — use acg_hits (faster " +
+        "and more relevant); for house changes in a new city use ephemeris_relocation.",
     inputSchema: {
         type: "object",
         properties: {
@@ -104,16 +101,14 @@ registerTool({
 // POST /acg/hits — OE-018
 registerTool({
     name: "acg_hits",
-    description: "Find all Astrocartography lines (power lines + aspect lines) passing near a specific location. " +
-        "Returns features sorted by distance, making it easy to interpret planetary influences at a place.\n\n" +
-        "✅  USE THIS TOOL FOR: 'Is [city] good for me?', 'What planets affect me in Tokyo?', " +
-        "'What ACG lines run through Paris for my chart?', 'Which cities are under my Jupiter line?'\n" +
-        "❌  NOT FOR: Full global map geometry → use acg_power_lines for that instead.\n\n" +
-        "CREDIT COST: 10 credits per call.\n\n" +
-        "EXAMPLE: All ACG lines within 3° of Paris for a chart born 1990-04-15 in Chicago:\n" +
-        "  birth_datetime='1990-04-15T14:30:00', timezone='America/Chicago',\n" +
-        "  birth_latitude=41.8781, birth_longitude=-87.6298,\n" +
-        "  query_latitude=48.8566, query_longitude=2.3522, radius_deg=3",
+    description: "Use this when the user asks 'is Tokyo good for me', 'where should I live according to my chart' " +
+        "(needs a candidate place — ask for one), 'what planets affect me in Paris', 'which of my lines " +
+        "run through Lisbon' or 'should I move to Austin'. Returns every astrocartography line (power " +
+        "lines and aspect lines) within radius_deg of a query location, sorted by distance, for a given " +
+        "birth chart.\n\n" +
+        "CREDIT COST: 10 credits per call. Pro tier.\n\n" +
+        "Do not use for the whole global map — use acg_power_lines; for a relocated chart use " +
+        "ephemeris_relocation.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/bazi.js

@@ -385,19 +385,14 @@ registerTool({
 // ─────────────────────────────────────────────────────────────────────────────
 registerTool({
     name: "bazi_annual_pillar",
-    description: "Look up the sexagenary pillar for any Gregorian year (1–9999). Returns the Heavenly Stem, " +
-        "Earthly Branch, Chinese characters, zodiac animal, element, polarity, and NaYin (纳音) " +
-        "poetic resonance image.\n\n" +
-        "NaYin maps each pair in the 60-cycle sexagenary sequence to one of 30 elemental images " +
-        "(e.g. '海中金 Metal in the Sea', '炉中火 Fire in the Furnace'). It is traditionally " +
-        "applied to the Year and Day pillars to reveal deeper elemental character.\n\n" +
-        "Use this to:\n" +
-        "  • Identify the energetic quality of any given year\n" +
-        "  • Determine a person's birth year pillar for compatibility context\n" +
-        "  • Find the NaYin element for year or day interpretations\n\n" +
+    description: "Use this when the user asks 'what element is the year of the Snake', 'what's the pillar, stem " +
+        "and branch or NaYin for my birth year' or 'what's the energy of this year' — a single-year " +
+        "lookup beyond the animal. Returns the year's Heavenly Stem, Earthly Branch, Chinese characters, " +
+        "zodiac animal, element, polarity and NaYin (纳音) resonance image for any Gregorian year 1-9999.\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
-        "EXAMPLE: Year pillar for 2025:\n" +
-        "  year=2025",
+        "Do not use for just the zodiac animal — dev_read_api path='/chinese/zodiac' (1 credit, all " +
+        "tiers); for a Jan-Feb birth the animal turns at Lunar New Year, so use explore_bazi_chart; for a " +
+        "person's full Four Pillars use explore_bazi_chart.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/eclipse.js

@@ -3,20 +3,13 @@ import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 registerTool({
     name: "ephemeris_next_eclipse",
-    description: "Find the next solar or lunar eclipse. " +
-        "Returns the eclipse type, date/time of maximum, magnitude, and duration of totality (if any).\n\n" +
-        "📍 LOCATION OPTIONAL:\n" +
-        "  • WITH latitude+longitude → returns local contact times and visibility for that specific location.\n" +
-        "  • WITHOUT latitude+longitude → returns the next global eclipse of that type (no location needed).\n\n" +
-        "USE THIS TOOL FOR: 'When is the next solar eclipse?', 'When is the next total lunar eclipse?', " +
-        "'Will there be an eclipse visible from Tokyo?'\n\n" +
+    description: "Use this when the user asks 'when is the next eclipse', 'when is the next solar / lunar " +
+        "eclipse', 'is there an eclipse visible from Tokyo' or 'when is the next total lunar eclipse'. " +
+        "Returns the eclipse type, date/time of maximum, magnitude and duration of totality; with " +
+        "latitude+longitude it adds local contact times and visibility for that place, without them it " +
+        "returns the next global eclipse of that type.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: Next solar eclipse globally (no location needed):\n" +
-        "  eclipse_type='solar'\n\n" +
-        "EXAMPLE: Next solar eclipse visible from New York:\n" +
-        "  eclipse_type='solar', latitude=40.7128, longitude=-74.006\n\n" +
-        "EXAMPLE: Next lunar eclipse from London:\n" +
-        "  eclipse_type='lunar', latitude=51.5074, longitude=-0.1278",
+        "Do not use for ordinary new/full moon dates — use ephemeris_next_lunar_phase.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/electional.js

@@ -6,13 +6,13 @@ import { DATETIME_DESC, WINDOW_DATE_DESC, localToUtcIso, timezoneProperty } from
 // GET /electional/find-window — already existed, keeping it
 registerTool({
     name: "ephemeris_electional",
-    description: "Find optimal planetary timing windows (electional astrology). Scans a date range to find the " +
-        "best times for an event based on essential dignity, aspect quality, sect, and void-of-course " +
-        "moon penalties. Evaluates every hour and clusters the best continuous windows.\n\n" +
-        "CREDIT COST: 5 credits per call (heavy calculation).\n\n" +
-        "EXAMPLE: Find the best time to launch a business in early March 2026.\n" +
-        "  start_date='2026-03-01', end_date='2026-03-10', latitude=40.7128, longitude=-74.0060,\n" +
-        "  avoid_voc=true, lunar_phase='waxing'",
+    description: "Use this when the user asks 'when is the best time to launch / sign / marry / start X' within a " +
+        "date range, 'find me a good day next month' or 'pick an auspicious window'. Returns the best " +
+        "continuous timing windows in the range, scored hourly on essential dignity, aspect quality, sect " +
+        "and void-of-course Moon penalties, with optional filters (avoid_voc, lunar_phase).\n\n" +
+        "CREDIT COST: 5 credits per call. Pro tier.\n\n" +
+        "Do not use to score one specific moment or 'right now' — use electional_moment_analysis; for " +
+        "retrograde dates use electional_station_tracker.",
     inputSchema: {
         type: "object",
         properties: {
@@ -100,12 +100,14 @@ registerTool({
 // omits them gets a wrong-half-of-the-day score that is at least labelled.
 registerTool({
     name: "electional_moment_analysis",
-    description: "Analyze the astrological quality of a specific moment: planet positions, aspects, " +
-        "void of course status, lunar phase, day ruler, sect, and an overall electional score (0-100). " +
-        "Perfect for evaluating whether 'right now' or a specific date/time is good for action.\n\n" +
+    description: "Use this when the user asks 'is now a good time to …', 'what's the sky doing today', 'what's the " +
+        "astrological weather', 'how is this date astrologically' — or has no birth data (it works with " +
+        "no arguments). Returns planet positions, " +
+        "aspects, void-of-course status, lunar phase, day ruler, sect and an overall electional score " +
+        "(0-100) for one moment.\n\n" +
         "CREDIT COST: 5 credits per call.\n\n" +
-        "EXAMPLE: Analyze March 21, 2026 at noon in New York:\n" +
-        "  date='2026-03-21T12:00:00Z', latitude=40.7128, longitude=-74.0060",
+        "Do not use to search a date range for the best window — use ephemeris_electional; for the Moon " +
+        "alone use explore_moon_phase.",
     inputSchema: {
         type: "object",
         properties: {
@@ -153,18 +155,14 @@ registerTool({
 });
 registerTool({
     name: "electional_station_tracker",
-    description: "Find all upcoming retrograde and direct stations for planets in a date range. " +
-        "Returns exact station times, longitudes, and signs.\n\n" +
-        "USE THIS TOOL FOR: 'When does Mercury go retrograde?', 'Is Venus retrograde this year?', " +
-        "'What planets station this month?', 'When does Mars go direct?'\n\n" +
-        "❌  NOT FOR: 'Is Mercury retrograde right now?' — that is the state at a single instant, " +
-        "so use ephemeris_retrograde_status (1 credit for one planet, vs 5 here).\n\n" +
-        "All required fields have smart defaults (searches the next 90 days from today).\n\n" +
+    description: "Use this when the user asks 'when does Mercury go retrograde', 'when does Mercury retrograde " +
+        "end', 'when does Mars go direct', 'when does Pluto go direct', 'is Venus retrograde this year', " +
+        "'Mercury retrograde dates for 2026' or 'what planets station this month'. Returns every " +
+        "retrograde and direct station in the range with exact time, longitude and sign — Mercury " +
+        "through Pluto; default range the next 90 days, maximum one year.\n\n" +
         "CREDIT COST: 5 credits per call.\n\n" +
-        "EXAMPLE: Mercury and Venus stations in the next 3 months (all defaults):\n" +
-        "  (no args required, will auto-scan next 90 days for all inner planets)\n\n" +
-        "EXAMPLE: Outer planet stations in 2026:\n" +
-        "  start_date='2026-01-01', end_date='2026-12-31', planets='jupiter,saturn,uranus,neptune,pluto'",
+        "Do not use for 'is Mercury retrograde right now' — that is one instant, use " +
+        "ephemeris_retrograde_status (1 credit).",
     inputSchema: {
         type: "object",
         properties: {
@@ -178,9 +176,9 @@ registerTool({
             },
             planets: {
                 type: "string",
-                description: "Comma-separated planet names to track. " +
-                    "E.g. 'mercury,venus,mars' or 'jupiter,saturn,uranus,neptune,pluto'. " +
-                    "Defaults to Mercury through Saturn (inner + classical planets).",
+                description: "Comma-separated planet names from: mercury, venus, mars, jupiter, saturn, " +
+                    "uranus, neptune, pluto. Defaults to Mercury through Saturn; name outer " +
+                    "planets explicitly.",
             },
             format: {
                 type: "string",
@@ -195,24 +193,19 @@ registerTool({
     annotations: { title: "Retrograde Station Tracker", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const query = {};
-        // Map human-readable planet names to IDs if needed
-        const PLANET_NAME_MAP = {
-            mercury: "2", venus: "3", mars: "4",
-            jupiter: "5", saturn: "6", uranus: "7",
-            neptune: "8", pluto: "9",
-        };
         if (args.start_date)
             query.start_date = args.start_date;
         if (args.end_date)
             query.end_date = args.end_date;
         if (args.planets) {
-            // Accept both names ('mercury,venus') and numeric IDs ('2,3')
+            // The engine matches lowercase NAMES (elePlanetList in
+            // handlers/handler_electional.go) and silently falls back to the
+            // whole Mercury-Saturn set when nothing matches — so numeric IDs,
+            // which this used to send, made the filter a no-op.
             query.planets = args.planets
                 .split(",")
-                .map((p) => {
-                const name = p.trim().toLowerCase();
-                return PLANET_NAME_MAP[name] ?? p.trim();
-            })
+                .map((p) => p.trim().toLowerCase())
+                .filter(Boolean)
                 .join(",");
         }
         if (args.format)

package/dist/tools/specialized/ephemeris_core.js

@@ -5,19 +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" +
-        "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; " +
-        "that is correct. Id 11 is the analytical true node. Neither is a classical mean node.\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: {
@@ -60,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/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: {