@openephemeris/mcp-server 4.15.0 → 4.16.0

package/dist/tools/apps/transit-timeline-app.js

@@ -92,21 +92,20 @@ function buildSummary(transits, aspectLabel, win) {
 // ── Tool: explore_transit_timeline ───────────────────────────────────────────
 registerTool({
     name: "explore_transit_timeline",
-    description: "Generate an interactive Transit Timeline — a vertical, date-ordered list of " +
-        "upcoming transit hits (transiting planets forming a chosen aspect to natal " +
-        "chart positions) over a date range.\n\n" +
-        "Returns a visual timeline with:\n" +
-        "  • Exact crossing dates grouped by month\n" +
-        "  • Transiting planet glyph, the natal point it contacts, and the aspect\n" +
-        "  • Zodiac position of each crossing and retrograde markers\n" +
-        "  • Click any transit for a focused interpretation\n\n" +
-        "ASPECT ANGLES: 0 = conjunction/return (default), 180 = opposition, 90 = square, " +
-        "120 = trine, 60 = sextile. EFFICIENCY: specify transiting_planets and natal_points " +
-        "to keep compute fast. DEFAULT natal_points: sun, moon, mercury, venus, mars, jupiter, saturn. " +
-        "SEARCH RANGE LIMITS: Explorer/PayG → 1 year; Pro → 5 years; Startup → 10 years.\n\n" +
+    description: "Use this when the user asks 'what transits are coming up for me', 'what's my forecast for the " +
+        "next year', 'when will Saturn hit my chart', 'show my upcoming transits' or 'what's happening " +
+        "astrologically for me in 2027' — a forecast they should SEE. Returns an interactive, " +
+        "date-ordered timeline (inline in Claude and ChatGPT; text summary elsewhere) of exact transit " +
+        "hits grouped by month — transiting planet glyph, the natal point it contacts, the aspect, zodiac " +
+        "position and retrograde markers — each clickable for a focused interpretation.\n\n" +
+        "ASPECT ANGLES: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 " +
+        "= sextile. EFFICIENCY: specify transiting_planets and natal_points to keep compute fast. DEFAULT " +
+        "natal_points: sun, moon, mercury, venus, mars, jupiter, saturn. SEARCH RANGE LIMITS: " +
+        "Explorer/PayG → 1 year; Pro → 5 years; Startup → 10 years.\n\n" +
         "CREDIT COST: 6 credits per call (natal chart + predictive transit search).\n\n" +
-        "Use this for a rich, interactive transit-forecast experience in MCP Apps-capable hosts " +
-        "(Claude Desktop). Falls back to a text summary in other hosts.",
+        "Do not use for transit data as JSON — use ephemeris_transits; for the sky today with no birth " +
+        "data use electional_moment_analysis; to see one date's transits drawn around the natal wheel use " +
+        "explore_bi_wheel (mode='transit').",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/apps/vedic-chart-app.js

@@ -96,14 +96,15 @@ function buildVedicSummary(payload, location) {
 // ── Tool: explore_vedic_chart ────────────────────────────────────────────────
 registerTool({
     name: "explore_vedic_chart",
-    description: "Generate an interactive Vedic (Jyotish) birth chart as a South Indian fixed-sign Rashi grid, " +
-        "with clickable rashis showing sidereal placements, nakshatras, and the Lagna.\n\n" +
-        "CREDIT COST: 3 credits per call (chart calculation + visual render).\n\n" +
-        "Returns an embedded visual explorer that lets you click any rashi cell for its themes and " +
-        "any planets placed there. Shows sidereal (Lahiri by default) planet placements, nakshatra with " +
-        "pada, navamsa, and the Lagna (Ascendant) rashi. Uses NASA JPL DE440 ephemerides. " +
-        "Use this for a rich, interactive Jyotish experience in MCP Apps-capable hosts (Claude Desktop). " +
-        "Falls back to a text summary in other hosts.",
+    description: "Use this when the user asks 'show my Vedic chart', 'my Jyotish chart', 'what's my nakshatra', " +
+        "'my sidereal birth chart', 'my rashi chart' or 'what's my lagna' — the PRIMARY tool for a Vedic " +
+        "chart. Returns an interactive South Indian fixed-sign Rashi grid (inline in Claude and ChatGPT; " +
+        "text summary elsewhere) with sidereal (Lahiri by default) placements, nakshatra with pada, " +
+        "navamsa and the Lagna (Ascendant) rashi; click any rashi cell for its themes and the planets " +
+        "placed there. Birthplace may be a place name (`location`).\n\n" +
+        "CREDIT COST: 3 credits per call (chart + render; +1 to resolve a place name).\n\n" +
+        "Do not use when raw Jyotish data is enough — use vedic_chart (1 credit); for a Western tropical " +
+        "chart use explore_natal_chart.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/auth.js

@@ -8,12 +8,12 @@ const credentialManager = new CredentialManager();
 // ────────────────────────────────────────────────────────
 registerTool({
     name: "auth_login",
-    description: "Start the device authorization flow to connect this MCP server to your OpenEphemeris account " +
-        "(free tier, no credit card needed). " +
-        "Returns a verification URL and code for the user to enter in their browser. " +
-        "The MCP server will then automatically receive credentials and all API calls will be " +
-        "linked to the user's account (tier, credits, rate limits). " +
-        "Only needed if no OPENEPHEMERIS_API_KEY env var is set and no cached credentials exist.",
+    description: "Use this when the user asks to 'connect', 'sign in', 'log in' or 'link my OpenEphemeris " +
+        "account', or when a call fails for lack of credentials and no OPENEPHEMERIS_API_KEY or cached " +
+        "login exists (free tier, no card needed). Returns a verification URL and code for the user to " +
+        "enter in their browser; the server then receives credentials automatically and every call is " +
+        "billed to that account (tier, credits, rate limits). Do not use to check whether you are already " +
+        "signed in — use auth_status; to disconnect use auth_logout.",
     inputSchema: {
         type: "object",
         properties: {},
@@ -96,9 +96,10 @@ registerTool({
 // ────────────────────────────────────────────────────────
 registerTool({
     name: "auth_status",
-    description: "Check the current authentication status of this MCP server. " +
-        "Shows whether the server is authenticated, which account it's linked to, " +
-        "the authentication method (API key, JWT, device auth), and token expiry.",
+    description: "Use this when the user asks 'am I logged in', 'which account is this connected to', 'how am I " +
+        "authenticated' or 'when does my token expire'. Returns whether the server is authenticated, the " +
+        "linked account, the method (API key, JWT, device auth) and token expiry. Do not use for credits, " +
+        "plan or usage — use account_usage; to sign in use auth_login.",
     inputSchema: {
         type: "object",
         properties: {},
@@ -184,9 +185,10 @@ registerTool({
 // ────────────────────────────────────────────────────────
 registerTool({
     name: "auth_logout",
-    description: "Disconnect this MCP server from your OpenEphemeris account by clearing " +
-        "cached credentials. Does NOT revoke the API key if one is set via environment " +
-        "variable — only clears device-auth cached credentials.",
+    description: "Use this when the user asks to 'log out', 'sign out', 'disconnect' or 'switch accounts' on this " +
+        "MCP server. Returns confirmation that cached device-auth credentials were cleared; an " +
+        "OPENEPHEMERIS_API_KEY set in the environment is not revoked. Do not use to check the current " +
+        "login — use auth_status.",
     inputSchema: {
         type: "object",
         properties: {},

package/dist/tools/dev.js

@@ -44,25 +44,12 @@ function isAllowedOperation(method, pathname, allow) {
 // actually make.
 const DEV_API_REFERENCE = "Target API: Open Ephemeris REST API (https://api.openephemeris.com). " +
     "Call dev_list_allowed to see all currently available endpoint paths.\n\n" +
-    "AUTH: Set OPENEPHEMERIS_API_KEY in your environment. See openephemeris.com/dashboard for active plan limits.\n\n" +
-    "CREDIT COSTS:\n" +
-    "  • Standard chart math (natal, progressed, bazi, vedic, iching): 1 credit\n" +
-    "  • Human Design: 2 credits\n" +
-    "  • Visualization rendering (chart-wheel, bi-wheel, charts/*): 2 credits\n" +
-    "  • Comparative math (synastry, composite, overlay): 3 credits\n" +
-    "  • Predictive ops (transits/search, returns): 5 credits\n" +
-    "  • Predictive transit-chart: 1 credit\n" +
-    "  • ACG / astrocartography: 10 credits (acg/hits: 15 credits)\n" +
-    "  • Calendar endpoints: 10 credits\n" +
-    "  • Catalog / metadata / health endpoints: 0 credits\n" +
-    "  • Compute surcharge: requests > 30s add 1 credit per 30s (predictive, acg, calendar, electional)\n" +
-    "  • format=llm (token-optimized output): available on all tiers\n\n" +
-    "BINARY RESPONSES:\n" +
-    "  • Binary/image endpoints return {content_type, content_length, encoding, data_base64}\n" +
-    "    so callers can decode bytes deterministically.\n\n" +
-    "ECLIPSE NOTE: Eclipse endpoints accept format=llm via the query param like other endpoints.\n\n" +
-    "format=llm NOTE: Add query: {format: 'llm'} to natal/synastry/composite/HD endpoints for " +
-    "compact columnar output optimized for LLM token budgets (availability depends on your current plan).";
+    // Prices mirror go-sidecar/internal/api/auth/usage_meter.go; tiers mirror
+    // auth/middleware.go requiredTierForPath. /iching/* aliases /human-design/*.
+    "CREDIT COST: 1 for most GET calls; /calendar/* 10; /acg/* 10 (Pro tier); /electional/* 5 " +
+    "(find-window and aspect-search are Pro tier; moment-analysis and station-tracker are free); " +
+    "/human-design/* and /iching/* 2; catalogs/health 0; requests over 30s add 1 " +
+    "per 30s. Pass query {format: 'llm'} for compact output.\n\n";
 const READ_COMMON_CALLS = "COMMON CALLS:\n" +
     "  GET  /ephemeris/moon/phase             — Current/queried moon phase\n" +
     "  GET  /ephemeris/moon/void-of-course    — Next void-of-course period\n" +
@@ -196,11 +183,12 @@ function makeProxyHandler(allowedMethods, defaultMethod) {
 }
 registerTool({
     name: "dev_read_api",
-    description: "Read from any allowlisted Open Ephemeris API endpoint via HTTP GET. This is the read-only " +
-        "power-user escape hatch — use the typed tools (ephemeris_natal_chart, ephemeris_transits, etc.) " +
-        "first for common operations. Endpoints that compute via POST (natal-chart, synastry, etc.) " +
-        "are covered by the typed tools; the generic POST proxy is only exposed on the full tool " +
-        "surface (`?profile=full`).\n\n" +
+    description: "Use this when the user asks for something no typed tool covers — 'is today a good biodynamic " +
+        "planting day', 'what's the tidal forcing', 'what Chinese zodiac animal is 2026', 'which bodies " +
+        "do you support' — or any other allowlisted GET endpoint. Returns the endpoint's JSON. Read-only " +
+        "HTTP GET; call dev_list_allowed to see every path. Do not use for birth charts, transits, moon " +
+        "phase, eclipses, Human Design, synastry or anything an ephemeris_* / explore_* tool already " +
+        "does. POST endpoints are only on the full tool surface (`?profile=full`).\n\n" +
         DEV_API_REFERENCE + "\n\n" + READ_COMMON_CALLS,
     inputSchema: makeProxyInputSchema(READ_METHODS),
     outputSchema: OUTPUT_SCHEMA_JSON,
@@ -233,11 +221,11 @@ registerTool({
 });
 registerTool({
     name: "dev_list_allowed",
-    description: "List all API operations (method + path) that this MCP instance is authorized to call. " +
-        "Returns endpoint entries grouped by method, plus the active deny rules. " +
-        "Use this to discover what's available before calling dev_read_api, or to verify an endpoint path. " +
-        "Typed shortcut tools (ephemeris_natal_chart, ephemeris_transits, etc.) cover the most common operations — " +
-        "check those first before reaching for the generic proxies.",
+    description: "Use this when the user asks 'what endpoints can you call', 'what else can this server do', 'is " +
+        "/some/path available', or before a dev_read_api call whose path you are unsure of. Returns every " +
+        "allowlisted API operation (method + path) grouped by method, plus the active deny rules; read " +
+        "locally, no API call. Do not use to fetch data — use dev_read_api, or the typed ephemeris_* / " +
+        "explore_* tool when one exists.",
     inputSchema: {
         type: "object",
         properties: {},

package/dist/tools/invocation-status.d.ts

@@ -0,0 +1,25 @@
+/**
+ * invocation-status.ts — the status text ChatGPT shows while a tool runs and
+ * after it completes.
+ *
+ * Wire form (OpenAI Apps SDK reference, "Tool descriptor parameters"):
+ *   _meta["openai/toolInvocation/invoking"]  ≤ 64 chars, shown during the call
+ *   _meta["openai/toolInvocation/invoked"]   ≤ 64 chars, shown when it returns
+ * Both are ChatGPT-only; other hosts ignore the keys. Emitted by buildUiMeta
+ * (src/tools/ui-meta.ts), the one path both transports' tools/list share.
+ *
+ * Copy rules: name the thing being made in the user's words, so the wait reads
+ * as progress rather than plumbing. `explore_*` tools say "ready" (a thing to
+ * look at); `ephemeris_*` tools say "computed" / "found" (numbers) — the same
+ * picture-vs-data split the descriptions make. Never promise a render:
+ * `explore_*` fall back to text in hosts without MCP Apps.
+ *
+ * Every core tool must have an entry (test/invocation-status.test.ts); tools
+ * outside core may have one. Keep both strings under MAX_STATUS_CHARS.
+ */
+export declare const MAX_STATUS_CHARS = 64;
+export interface InvocationStatus {
+    readonly invoking: string;
+    readonly invoked: string;
+}
+export declare const INVOCATION_STATUS: Readonly<Record<string, InvocationStatus>>;

package/dist/tools/invocation-status.js

@@ -0,0 +1,69 @@
+/**
+ * invocation-status.ts — the status text ChatGPT shows while a tool runs and
+ * after it completes.
+ *
+ * Wire form (OpenAI Apps SDK reference, "Tool descriptor parameters"):
+ *   _meta["openai/toolInvocation/invoking"]  ≤ 64 chars, shown during the call
+ *   _meta["openai/toolInvocation/invoked"]   ≤ 64 chars, shown when it returns
+ * Both are ChatGPT-only; other hosts ignore the keys. Emitted by buildUiMeta
+ * (src/tools/ui-meta.ts), the one path both transports' tools/list share.
+ *
+ * Copy rules: name the thing being made in the user's words, so the wait reads
+ * as progress rather than plumbing. `explore_*` tools say "ready" (a thing to
+ * look at); `ephemeris_*` tools say "computed" / "found" (numbers) — the same
+ * picture-vs-data split the descriptions make. Never promise a render:
+ * `explore_*` fall back to text in hosts without MCP Apps.
+ *
+ * Every core tool must have an entry (test/invocation-status.test.ts); tools
+ * outside core may have one. Keep both strings under MAX_STATUS_CHARS.
+ */
+export const MAX_STATUS_CHARS = 64;
+export const INVOCATION_STATUS = {
+    // Interactive apps
+    explore_natal_chart: { invoking: "Casting your birth chart…", invoked: "Birth chart ready" },
+    explore_bi_wheel: { invoking: "Comparing the two charts…", invoked: "Bi-wheel ready" },
+    explore_human_design: { invoking: "Drawing your bodygraph…", invoked: "Bodygraph ready" },
+    explore_human_design_transit: { invoking: "Overlaying the transits on your bodygraph…", invoked: "Transit overlay ready" },
+    explore_human_design_connection: { invoking: "Overlaying both bodygraphs…", invoked: "Connection chart ready" },
+    explore_moon_phase: { invoking: "Reading the Moon…", invoked: "Moon phase ready" },
+    explore_transit_timeline: { invoking: "Searching your upcoming transits…", invoked: "Transit timeline ready" },
+    explore_vedic_chart: { invoking: "Casting your Vedic chart…", invoked: "Vedic chart ready" },
+    explore_bazi_chart: { invoking: "Building your Four Pillars…", invoked: "Four Pillars ready" },
+    // Ephemeris data
+    ephemeris_natal_chart: { invoking: "Computing natal positions…", invoked: "Natal positions computed" },
+    ephemeris_planet_position: { invoking: "Locating the planet…", invoked: "Planet position computed" },
+    ephemeris_house_cusps: { invoking: "Computing house cusps…", invoked: "House cusps computed" },
+    ephemeris_angles_points: { invoking: "Computing chart angles…", invoked: "Chart angles computed" },
+    ephemeris_aspect_check: { invoking: "Measuring the aspect…", invoked: "Aspect measured" },
+    ephemeris_moon_phase: { invoking: "Checking the Moon…", invoked: "Moon phase found" },
+    ephemeris_next_lunar_phase: { invoking: "Finding the next lunar phase…", invoked: "Lunar phase dates found" },
+    ephemeris_next_eclipse: { invoking: "Finding the next eclipse…", invoked: "Eclipse found" },
+    ephemeris_retrograde_status: { invoking: "Checking retrograde motion…", invoked: "Retrograde status checked" },
+    ephemeris_transits: { invoking: "Searching for exact transit dates…", invoked: "Transit dates found" },
+    ephemeris_synastry: { invoking: "Computing synastry aspects…", invoked: "Synastry computed" },
+    ephemeris_relocation: { invoking: "Relocating your chart…", invoked: "Relocated chart computed" },
+    ephemeris_progressed_chart: { invoking: "Progressing your chart…", invoked: "Progressed chart computed" },
+    ephemeris_solar_return: { invoking: "Finding your solar return…", invoked: "Solar return computed" },
+    // Traditions
+    human_design_chart: { invoking: "Computing Human Design data…", invoked: "Human Design data computed" },
+    vedic_chart: { invoking: "Computing Vedic positions…", invoked: "Vedic positions computed" },
+    bazi_annual_pillar: { invoking: "Looking up the year pillar…", invoked: "Year pillar found" },
+    // Timing
+    ephemeris_electional: { invoking: "Scanning for the best timing windows…", invoked: "Timing windows found" },
+    electional_moment_analysis: { invoking: "Scoring this moment…", invoked: "Moment scored" },
+    electional_station_tracker: { invoking: "Finding retrograde and direct stations…", invoked: "Station dates found" },
+    // Astrocartography
+    acg_power_lines: { invoking: "Tracing your planetary lines…", invoked: "Planetary lines traced" },
+    acg_hits: { invoking: "Checking your lines at this location…", invoked: "Location lines found" },
+    // Geocoding
+    location_search: { invoking: "Looking up the place…", invoked: "Place found" },
+    timezone_resolve: { invoking: "Resolving the timezone…", invoked: "Timezone resolved" },
+    // Account + escape hatch
+    account_usage: { invoking: "Checking your account…", invoked: "Usage retrieved" },
+    dev_read_api: { invoking: "Calling the Open Ephemeris API…", invoked: "API response ready" },
+    dev_list_allowed: { invoking: "Listing available endpoints…", invoked: "Endpoints listed" },
+    // Auth (stdio only)
+    auth_login: { invoking: "Connecting your account…", invoked: "Account connected" },
+    auth_status: { invoking: "Checking the connection…", invoked: "Connection status ready" },
+    auth_logout: { invoking: "Disconnecting your account…", invoked: "Account disconnected" },
+};

package/dist/tools/specialized/account.js

@@ -5,16 +5,12 @@ import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 const WALLET_TIERS = new Set(["explorer", "free", "payg", "wallet"]);
 registerTool({
     name: "account_usage",
-    description: "Check the user's OpenEphemeris account usage and remaining credits. " +
-        "Returns their plan tier, billing period, credits used / included / remaining, " +
-        "percent of quota used, total API calls, and subscription status with renewal date.\n\n" +
-        "✅  USE THIS TOOL FOR: 'How many credits do I have left?', 'What's my usage this month?', " +
-        "'Am I close to my limit?', 'What plan am I on?', 'How do I upgrade or top up?'\n\n" +
-        "CREDIT COST: Free (0 credits).\n\n" +
-        "EXAMPLE: Check current usage:\n" +
-        "  (call with no arguments)\n\n" +
-        "EXAMPLE: Check a past month:\n" +
-        "  month='2026-06'",
+    description: "Use this when the user asks 'how many credits do I have left', 'what's my usage this month', 'am " +
+        "I close to my limit', 'what plan am I on' or 'how do I upgrade or top up'. Returns plan tier, " +
+        "billing period, credits used / included / remaining, percent of quota used, total API calls, and " +
+        "subscription status with renewal date; pass month='YYYY-MM' for a past period.\n\n" +
+        "CREDIT COST: 0.\n\n" +
+        "Do not use to sign in or to check the login state — that is auth, not usage.",
     inputSchema: {
         type: "object",
         properties: {

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/bi_wheel.js

@@ -10,7 +10,7 @@ const HOUSE_SYSTEM_MAP = {
 };
 registerTool({
     name: "ephemeris_bi_wheel",
-    description: "Generate a Bi-Wheel (Synastry/Transit) image (SVG) comparing two charts. Draws Subject A's planets on the inside wheel and Subject B's on the outside wheel. Returns a native SVG that Claude displays inline in the conversation.\n\n" +
+    description: "Generate a Bi-Wheel (Synastry/Transit) image (SVG) comparing two charts. Draws Subject A's planets on the inside wheel and Subject B's on the outside wheel. Returns a native SVG the host displays inline in the conversation.\n\n" +
         "For a user-facing interactive bi-wheel, use explore_bi_wheel instead.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
         "EXAMPLE: Compare someone born April 15, 1990 (A) to someone born June 10, 1992 (B):\n" +

package/dist/tools/specialized/chart_wheel.js

@@ -10,7 +10,7 @@ const HOUSE_SYSTEM_MAP = {
 };
 registerTool({
     name: "ephemeris_chart_wheel",
-    description: "Generate a classic astrological Chart Wheel image (SVG) for a person/event. This draws a standard circular chart wheel with planets, aspects, and house cusps. The tool returns a native SVG image that Claude displays inline in the conversation — no external tools needed.\n\n" +
+    description: "Generate a classic astrological Chart Wheel image (SVG) for a person/event. This draws a standard circular chart wheel with planets, aspects, and house cusps. The tool returns a native SVG image the host displays inline in the conversation — no external tools needed.\n\n" +
         "For a user-facing interactive chart wheel, use explore_natal_chart instead.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
         "EXAMPLE: born 15 April 1990 at 2:30 PM local time in Chicago:\n" +

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)