@openephemeris/mcp-server 4.15.1 → 4.17.0

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

@@ -120,15 +120,18 @@ function buildNatalBody(datetime, lat, lon, houseSystem, timezone, additionalObj
 // ── Tool: explore_natal_chart ──────────────────────────────────────────────
 registerTool({
     name: "explore_natal_chart",
-    description: "PRIMARY tool for any natal/birth-chart request. Renders an interactive, clickable chart " +
-        "wheel — prefer this over ephemeris_natal_chart when the user wants to SEE a chart. " +
-        "Returns an embedded visual chart explorer that lets you click any planet, house, or aspect " +
-        "line for instant astrological interpretation.\n\n" +
-        "CREDIT COST: 1 credit per call.\n\n" +
-        "Supports house system switching (Placidus, Whole Sign, Equal, Koch). " +
-        "The chart is computed using NASA JPL DE440 ephemerides for sub-arcsecond precision. " +
-        "Renders interactively in MCP Apps-capable hosts (Claude and ChatGPT) and falls back to " +
-        "static SVG in other hosts.",
+    description: "Use this when the user asks 'show me my birth chart', 'what's my rising sign', 'my big 3', " +
+        "'what's my sun, moon and rising', 'what sign is my Moon / Venus / Mars in', 'what does my chart " +
+        "say about my career / love', 'read my chart', or shares birth details and wants to explore them " +
+        "— the PRIMARY tool for any natal / birth-chart / astrology-chart request. Returns an interactive " +
+        "chart wheel rendered inline (Claude and ChatGPT; text summary elsewhere) where any planet, house " +
+        "or aspect line can be clicked for interpretation, with switchable house systems. Pass the " +
+        "birthplace as `location` (a place name — resolved server-side) or coordinates, plus the birth " +
+        "date and local time with its zone.\n\n" +
+        "CREDIT COST: 1 credit per call (+1 to resolve a place name).\n\n" +
+        "Do not use when the chart must be consumed as raw numbers for further computation — use " +
+        "ephemeris_natal_chart; for two charts together use explore_bi_wheel; for Human Design use " +
+        "explore_human_design; for Vedic use explore_vedic_chart.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/apps/location-tools.js

@@ -127,7 +127,16 @@ function offsetAtLocalNoon(timezone, date) {
 }
 registerTool({
     name: "location_search",
-    description: "Resolve a place name to coordinates and IANA timezone — use this first whenever a user gives a birth city rather than latitude/longitude. NEVER recall coordinates from memory; always resolve them here. CREDIT COST: 1 credit per call. Returns display name, region (state/province), latitude, longitude, and IANA timezone. Pass the birth date as `date` to also get `utcOffsetAtDate`, the historically-correct UTC offset for that place on that date (1987 DST rules differ from today's). Post-1970 dates resolve locally and cost no extra credits; a pre-1970 date consults the API's historical correction overlay for the top match (1 extra credit) and returns its provenance — tzRuleSource, tzRuleCitation, tzOverlayVersion. When the result is `ambiguous` (several places share the name, e.g. \"portland\"), ASK the user which one they mean rather than assuming the first. Optional bias params (country/region/near) improve ranking; a trailing \"City, ST\" qualifier in the query is also honored.",
+    description: "Use this when the user gives a birth city or any place name — 'born in Chicago', 'Portland', " +
+        "'Mumbai, India' — and a chart needs coordinates and a timezone. Always resolve here; NEVER " +
+        "recall coordinates from memory. Returns display name, region (state/province), latitude, " +
+        "longitude and IANA timezone. Pass the birth date as `date` to also get `utcOffsetAtDate`, the " +
+        "historically-correct UTC offset for that place on that date; post-1970 dates resolve locally at " +
+        "no extra cost, pre-1970 dates consult the historical overlay for the top match (+1 credit) and " +
+        "return its provenance. When the result is `ambiguous` (several places share the name, e.g. " +
+        "\"portland\"), ASK the user which one they mean rather than assuming the first. A trailing \"City, " +
+        "ST\" qualifier in the query is honored. CREDIT COST: 1 credit per call. Do not use when you " +
+        "already have coordinates and only need the zone — use timezone_resolve.",
     inputSchema: {
         type: "object",
         properties: {
@@ -280,12 +289,16 @@ registerTool({
 });
 registerTool({
     name: "timezone_resolve",
-    description: "Resolve the IANA timezone for a latitude/longitude pair. Use when you have coordinates but need the timezone to interpret a local birth time. Pass `date` to also get the historically-correct UTC offset that applied on that date. CREDIT COST: 1 credit per call. If you are starting from a place name rather than coordinates, use location_search instead — it returns the timezone too, in the same single call.",
+    description: "Use this when you have latitude/longitude but need the IANA timezone to interpret a local birth " +
+        "time, or the user asks 'what timezone is this location in' or 'what was the UTC offset there on " +
+        "that date'. Returns the IANA zone and, with `date`, the historically-correct UTC offset that " +
+        "applied on that date. CREDIT COST: 1 credit per call. Do not use when starting from a place name " +
+        "— use location_search, which returns the timezone too, in the same single call.",
     inputSchema: {
         type: "object",
         properties: {
-            latitude: { type: "number" },
-            longitude: { type: "number" },
+            latitude: { type: "number", description: "Latitude in decimal degrees, -90 to 90 (north positive)." },
+            longitude: { type: "number", description: "Longitude in decimal degrees, -180 to 180 (east positive)." },
             date: {
                 type: "string",
                 description: "Optional birth/event date 'YYYY-MM-DD'. Adds utcOffsetAtDate / utcOffsetMinutes / isDst / tzConfidence. Post-1970 resolves locally (free); pre-1970 consults the API's historical correction overlay (1 extra credit).",

package/dist/tools/apps/moon-phase-app.js

@@ -193,18 +193,19 @@ async function computeMoonData(args) {
 // ── Tool: explore_moon_phase ─────────────────────────────────────────────────
 registerTool({
     name: "explore_moon_phase",
-    description: "Generate an interactive Moon Phase dial showing the current lunar illumination, " +
-        "phase name, zodiac sign, and void-of-course status as a beautiful circular visualization.\n\n" +
-        "Returns a visual dial with:\n" +
-        "  • SVG crescent Moon showing real-time illumination percentage\n" +
-        "  • Phase name and waxing/waning indicator\n" +
-        "  • Current Moon sign with degree\n" +
-        "  • Void-of-Course status with timing details\n" +
-        "  • Lunar age (days in the synodic cycle)\n" +
-        "  • Upcoming New Moon and Full Moon dates\n\n" +
+    description: "Use this when the user asks 'what's the moon phase tonight', 'is tonight a full moon', 'show me " +
+        "the moon right now', 'what sign is the Moon in', 'is the Moon void of course' — or has no birth " +
+        "data and wants somewhere to start; it needs no arguments. Returns an interactive Moon dial " +
+        "(inline in Claude and ChatGPT; text summary elsewhere) with:\n" +
+        "• SVG crescent Moon showing real-time illumination percentage\n" +
+        "• Phase name and waxing/waning indicator\n" +
+        "• Current Moon sign with degree\n" +
+        "• Void-of-Course status with timing details\n" +
+        "• Lunar age (days in the synodic cycle) and days to the next New and Full Moon\n" +
+        "• The tightest applying lunar aspects\n\n" +
         "CREDIT COST: 3 credits per call (phase + void-of-course + aspects, 1 each).\n\n" +
-        "Use this instead of ephemeris_moon_phase for a rich, interactive lunar phase experience in " +
-        "MCP Apps-capable hosts (Claude and ChatGPT). Falls back to a text summary in other hosts.",
+        "Do not use when only the numbers are needed — use ephemeris_moon_phase; for the exact dates of " +
+        "upcoming phases use ephemeris_next_lunar_phase; for eclipses use ephemeris_next_eclipse.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/apps/transit-timeline-app.d.ts

@@ -8,6 +8,9 @@
  * chart to extract real planetary longitudes, searches predictive transits
  * against those targets, then flattens the (planet@target → hits) result map
  * into a single chronological array the iframe renders as a vertical timeline.
+ * The search asks for orb windows (orb_deg) too, so every exact hit carries the
+ * in-orb window it belongs to — when the transit starts and ends, and which
+ * pass it is when a retrograde brings the planet back over the same point.
  *
  * Also exports resource helpers (getTransitTimelineBundle, etc.) for use in
  * index.ts and server-sse.ts.

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

@@ -8,6 +8,9 @@
  * chart to extract real planetary longitudes, searches predictive transits
  * against those targets, then flattens the (planet@target → hits) result map
  * into a single chronological array the iframe renders as a vertical timeline.
+ * The search asks for orb windows (orb_deg) too, so every exact hit carries the
+ * in-orb window it belongs to — when the transit starts and ends, and which
+ * pass it is when a retrograde brings the planet back over the same point.
  *
  * Also exports resource helpers (getTransitTimelineBundle, etc.) for use in
  * index.ts and server-sse.ts.
@@ -67,18 +70,32 @@ function normDeg(d) {
     return ((d % 360) + 360) % 360;
 }
 // ── Summary builder ──────────────────────────────────────────────────────────
-function buildSummary(transits, aspectLabel, win) {
+function shortDate(iso) {
+    return iso ? new Date(iso).toISOString().slice(0, 10) : "?";
+}
+function buildSummary(transits, windows, aspectLabel, orbDeg, win) {
+    const active = windows.filter((w) => w.phase_at_start);
+    const activeLines = active.slice(0, 6).map((w) => "  • " + w.planet_name + " " + (w.aspect ?? aspectLabel) + (w.natal_point ? " natal " + w.natal_point : "") +
+        " — " + w.phase_at_start + ", " + (Math.round((w.orb_at_start ?? 0) * 100) / 100) + "° from exact, in orb until " +
+        shortDate(w.leave));
+    const activeBlock = activeLines.length
+        ? "\n\nAlready in orb (" + orbDeg + "°) at the start:\n" + activeLines.join("\n")
+        : "";
     if (transits.length === 0) {
-        return "**Transit Timeline** — no exact transit hits matched the search window and criteria.";
+        return "**Transit Timeline** — no exact transit hits matched the search window and criteria." + activeBlock;
     }
     const planets = [...new Set(transits.map((t) => t.planet_name).filter(Boolean))];
     const lines = transits.slice(0, 8).map((t) => {
         const asp = t.aspect ?? aspectLabel;
         const natal = t.natal_point ? " natal " + t.natal_point : "";
         const when = new Date(t.date).toISOString().slice(0, 10);
+        const passes = t.pass_count > 1 ? ", pass " + t.pass_index + " of " + t.pass_count : "";
+        const inOrb = t.window_start !== undefined
+            ? " — in orb " + shortDate(t.window_start) + " → " + shortDate(t.window_end) + passes
+            : "";
         return "  • " + when + " — " + t.planet_name + " " + asp + natal +
             (t.zodiac_sign ? " (" + (t.zodiac_degree ?? 0) + "° " + t.zodiac_sign + ")" : "") +
-            (t.is_retrograde ? " ℞" : "");
+            (t.is_retrograde ? " ℞" : "") + inOrb;
     });
     let summary = "**Transit Timeline** — " + transits.length + (transits.length === 1 ? " event" : " events") +
         " from " + win.start_date + " to " + win.end_date +
@@ -86,27 +103,29 @@ function buildSummary(transits, aspectLabel, win) {
         lines.join("\n");
     if (transits.length > 8)
         summary += "\n  … and " + (transits.length - 8) + " more.";
+    summary += activeBlock;
     summary += "\n\nClick any transit for details and interpretation.";
     return summary;
 }
 // ── 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. Every hit carries its " +
+        "in-orb window (when the transit starts and ends, and which pass it is when a retrograde repeats it), " +
+        "and transits already in orb at the start are listed with applying/separating.\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 and ChatGPT). 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: {
@@ -128,6 +147,10 @@ registerTool({
                 type: "number",
                 description: "Aspect angle in degrees. 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 = sextile.",
             },
+            orb_deg: {
+                type: "number",
+                description: "Orb in degrees that defines when a transit starts and ends (the in-orb window around each exact hit). Default 1. Greater than 0, at most 15.",
+            },
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"],
         additionalProperties: false,
@@ -223,10 +246,12 @@ registerTool({
         let endStr = args.end_date;
         if (/^\d{4}-\d{2}-\d{2}$/.test(endStr))
             endStr += "T23:59:59Z";
+        const orbDeg = typeof args.orb_deg === "number" && args.orb_deg > 0 ? Math.min(args.orb_deg, 15) : 1;
         const transitBody = {
             start_date: startStr,
             end_date: endStr,
             target_degrees: effectiveTargets,
+            orb_deg: orbDeg,
         };
         if (args.transiting_planets)
             transitBody.planet_names = args.transiting_planets;
@@ -279,10 +304,53 @@ registerTool({
             }
         }
         transits.sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+        // ── Step 5: orb windows → attach each exact hit to its window ────────────
+        // A window groups every pass the planet makes without leaving the orb, so
+        // a retrograde triple pass is one window with three exacts. Hits are
+        // matched to windows by planet, target degree and exact time.
+        const rawWindows = Array.isArray(transitResult?.windows) ? transitResult.windows : [];
+        const windows = rawWindows.map((w) => {
+            const target = typeof w?.target_longitude === "number" ? w.target_longitude : null;
+            return {
+                planet: String(w?.planet_name ?? "").toLowerCase(),
+                planet_name: String(w?.planet_name ?? ""),
+                natal_point: target != null ? nearestPoint(target) : "",
+                aspect: aspectLabel,
+                target_longitude: target,
+                orb_deg: w?.orb_deg ?? orbDeg,
+                enter: w?.enter ?? null,
+                leave: w?.leave ?? null,
+                exacts: Array.isArray(w?.exacts)
+                    ? w.exacts.map((e) => ({ time: e?.time, is_retrograde: Boolean(e?.is_retrograde) }))
+                    : [],
+                duration_days: w?.duration_days ?? null,
+                phase_at_start: w?.phase_at_start ?? null,
+                orb_at_start: w?.orb_at_start ?? null,
+            };
+        });
+        for (const t of transits) {
+            const hitMs = new Date(t.date).getTime();
+            for (const w of windows) {
+                if (w.planet_name !== t.planet_name || w.target_longitude == null || t.target_longitude == null)
+                    continue;
+                if (Math.abs(w.target_longitude - t.target_longitude) > 0.01)
+                    continue;
+                const idx = w.exacts.findIndex((e) => Math.abs(new Date(e.time).getTime() - hitMs) <= 60_000);
+                if (idx < 0)
+                    continue;
+                t.window_start = w.enter;
+                t.window_end = w.leave;
+                t.pass_index = idx + 1;
+                t.pass_count = w.exacts.length;
+                break;
+            }
+        }
         const win = { start_date: startStr.slice(0, 10), end_date: endStr.slice(0, 10) };
-        const summary = buildSummary(transits, aspectLabel, win);
+        const summary = buildSummary(transits, windows, aspectLabel, orbDeg, win);
         const uiPayload = {
             transits,
+            windows,
+            orb_deg: orbDeg,
             natal_positions: natalPositionMap,
             aspect_angle: aspectAngle,
             aspect_label: aspectLabel,

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 and ChatGPT). " +
-        "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: {