@openephemeris/mcp-server 4.15.1 → 4.16.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.16.0] — 2026-09-21
+
+### Changed
+- **Synastry, composite, bi-wheel, returns, progressions, relocation, HD transit/connection overlays
+  and advanced BaZi are now available on the free tier (credits only).** Tool descriptions no longer
+  say "Pro tier" for any of them; astrocartography and electional window search stay Pro.
+- **Credit-exhausted responses now link directly to a one-tap $5 top-up.** A `402` from the API hands
+  the model a single link (`https://openephemeris.com/topup?pack=payg_5`) that signs the user in if
+  needed and goes straight to checkout, instead of a dashboard wallet tab.
+
+### Added
+- **Listed in the ChatGPT app directory** (approved 2026-09-14). ChatGPT users install Open Ephemeris
+  in one click from [the listing](https://chatgpt.com/plugins/plugin_asdk_app_6a9c2787bc48819197698e71b29ef7c2)
+  — no Developer Mode, no URL to paste. Same server, same interactive charts as Claude.
+
 ## [4.15.1] — 2026-09-10
 
 ### Fixed

package/README.md

@@ -177,7 +177,8 @@ Cursor deeplink payload:
 | Claude Desktop (macOS) | Manual | `~/Library/Application Support/Claude/claude_desktop_config.json` |
 | Claude Desktop (Windows) | Manual | `%APPDATA%\Claude\claude_desktop_config.json` |
 | Windsurf | Manual | `~/.codeium/windsurf/mcp_config.json` (or legacy `~/.codeium/mcp_config.json`) |
-| Claude Web / ChatGPT / remote clients | Hosted URL | `https://mcp.openephemeris.com/mcp` |
+| ChatGPT | One-click | [Open Ephemeris in the ChatGPT app directory](https://chatgpt.com/plugins/plugin_asdk_app_6a9c2787bc48819197698e71b29ef7c2) |
+| Claude Web / remote clients | Hosted URL | `https://mcp.openephemeris.com/mcp` |
 
 ### Client install walkthroughs
 
@@ -198,14 +199,12 @@ Cursor deeplink payload:
 The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable HTTP support (MCP 2025-11-25 spec). Remote-only clients can connect directly — no bridge/proxy required:
 
 - **Claude Web**: Add `https://mcp.openephemeris.com/mcp` as a custom connector URL — leave OAuth Client ID and Secret **blank**. The server uses OAuth 2.1 + PKCE (Dynamic Client Registration), so Claude handles authentication via a browser popup automatically.
-- **ChatGPT**: OpenEphemeris is not in the ChatGPT app directory — you add it yourself.
-  Turn on **Settings → Plugins → Advanced → Developer mode**, then use the **+ (Create app)**
-  button on [chatgpt.com/plugins](https://chatgpt.com/plugins). Server URL:
-  `https://mcp.openephemeris.com/mcp` (append `?profile=core` for the curated 39-tool
-  surface, which still includes every interactive chart). Leave Authentication on **OAuth**;
-  the same PKCE + Dynamic Client Registration flow applies, so there is no client ID or
-  secret to enter. Charts render inline, exactly as they do in Claude. *Developer mode was
-  available on a Free plan when this was last checked (2026-09-04); availability may vary.*
+- **ChatGPT**: Open Ephemeris is an approved app in the ChatGPT app directory. Open
+  [the listing](https://chatgpt.com/plugins/plugin_asdk_app_6a9c2787bc48819197698e71b29ef7c2), click **Install plugin**, approve the sign-in (that also creates your
+  free OpenEphemeris account), then type `@Open Ephemeris` in any chat. Charts render inline,
+  exactly as they do in Claude. Prefer to wire it yourself? **Settings → Plugins → Advanced →
+  Developer mode → + Create app** accepts `https://mcp.openephemeris.com/mcp` with
+  Authentication on **OAuth** — no client ID or secret to enter.
 - **Via Smithery**: Use the [Smithery listing](https://smithery.ai/servers/open-ephemeris/openephemeris) for managed connections with any client
 - **Legacy SSE**: retired in 3.20.0 — use Streamable HTTP at `/mcp`
 
@@ -246,8 +245,8 @@ This matters more than it sounds. A natal chart returned as JSON is a list of nu
 These need a host that supports MCP Apps. **Claude and ChatGPT both do**, and they render
 the same widget — there is no separate ChatGPT build. MCP Apps ([SEP-1865][sep1865]) was
 co-authored by Anthropic and OpenAI and became the first official MCP extension in January
-2026, so one `ui://` resource serves both. In ChatGPT you add the server yourself as a
-custom app (see [Setup](#setup)); OpenEphemeris is not in the ChatGPT app directory.
+2026, so one `ui://` resource serves both. In ChatGPT, install it from
+[the app directory](https://chatgpt.com/plugins/plugin_asdk_app_6a9c2787bc48819197698e71b29ef7c2); in Claude, add the connector (see [Setup](#setup)).
 
 In a client without app support the same tools still work; you get the underlying data
 instead of the picture, so nothing breaks, you just don't get the wheel.
@@ -282,24 +281,24 @@ Screenshots of each are on the way.
 | Moon phase / VOC | `ephemeris_moon_phase` | Explorer |
 | Eclipse next visible | `ephemeris_next_eclipse` | Explorer |
 | Electional window | `ephemeris_electional` | Developer |
-| Moment analysis | `electional_moment_analysis` | Developer |
-| Station tracker | `electional_station_tracker` | Developer |
+| Moment analysis | `electional_moment_analysis` | Explorer |
+| Station tracker | `electional_station_tracker` | Explorer |
 | Aspect search | `electional_aspect_search` | Developer |
 | Human Design chart | `human_design_chart` | Explorer |
-| HD composite | `human_design_composite` | Developer |
-| HD transit overlay | `explore_human_design_transit` | Developer |
-| HD connection (synastry) | `explore_human_design_connection` | Developer |
+| HD composite | `human_design_composite` | Explorer |
+| HD transit overlay | `explore_human_design_transit` | Explorer |
+| HD connection (synastry) | `explore_human_design_connection` | Explorer |
 | HD penta | `human_design_penta` | Explorer |
 | HD return / opposition | `hd_planetary_return`, `hd_opposition` | Explorer |
 | Vedic chart | `vedic_chart` | Explorer |
 | BaZi (Chinese) | `chinese_bazi` | Explorer |
-| Synastry | `ephemeris_synastry` | Developer |
-| Composite chart | `ephemeris_composite` | Developer |
-| Relocation chart | `ephemeris_relocation` | Developer |
+| Synastry | `ephemeris_synastry` | Explorer |
+| Composite chart | `ephemeris_composite` | Explorer |
+| Relocation chart | `ephemeris_relocation` | Explorer |
 | Progressed chart | `ephemeris_progressed_chart` | Explorer |
-| Solar return | `ephemeris_solar_return` | Developer |
-| Lunar return | `ephemeris_lunar_return` | Developer |
-| Planetary return | `ephemeris_planetary_return` | Developer |
+| Solar return | `ephemeris_solar_return` | Explorer |
+| Lunar return | `ephemeris_lunar_return` | Explorer |
+| Planetary return | `ephemeris_planetary_return` | Explorer |
 | Astrocartography lines | `acg_power_lines` | Developer |
 | ACG hits at location | `acg_hits` | Scale |
 | Venus Star Points | `venus_star_points` + 4 more | Explorer |

package/dist/backend/client.d.ts

@@ -24,6 +24,8 @@ export interface BinaryBackendResponse {
 export declare const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=account";
 export declare const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
 export declare const UPGRADE_URL = "https://openephemeris.com/pricing";
+/** One-tap $5 → 150-credit top-up (signs the user in if needed, then redirects to the prefilled Stripe Payment Link). */
+export declare const TOPUP_URL = "https://openephemeris.com/topup?pack=payg_5";
 export declare const WALLET_TOPUP_URL = "https://openephemeris.com/wallet";
 export declare class BackendError extends Error {
     readonly status: number;

package/dist/backend/client.js

@@ -22,6 +22,8 @@ const BINARY_ENDPOINT_PREFIXES = [
 export const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=account";
 export const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
 export const UPGRADE_URL = "https://openephemeris.com/pricing";
+/** One-tap $5 → 150-credit top-up (signs the user in if needed, then redirects to the prefilled Stripe Payment Link). */
+export const TOPUP_URL = "https://openephemeris.com/topup?pack=payg_5";
 export const WALLET_TOPUP_URL = "https://openephemeris.com/wallet";
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -277,7 +279,6 @@ export class BackendClient {
                 // suggest enabling overages; suggest the next tier instead. Keep every
                 // number below in sync with that file; do NOT hand-edit independently.
                 const dataObj = data && typeof data === "object" ? data : {};
-                const walletUrl = dataObj.upgrade?.wallets_url || "https://openephemeris.com/dashboard?tab=wallet";
                 const currentTier = dataObj.upgrade?.current_tier || dataObj.tier || "explorer";
                 // Next-tier upgrade path (SSOT: BILLING_PLANS order in billing-plans.ts).
                 const NEXT_TIER = {
@@ -285,25 +286,29 @@ export class BackendClient {
                     startup: { plan: "scale", label: "Scale ($199/mo, 2,000,000 credits)" },
                     scale: { plan: "enterprise", label: "Enterprise (custom volume)" },
                 };
+                // One direct link, not a dashboard tab: /topup?pack=payg_5 signs the
+                // user in if needed and redirects straight to the prefilled Stripe
+                // Payment Link for the $5 → 150-credit pack.
                 let upsellMsg = "";
+                let actionUrl = TOPUP_URL;
                 if (currentTier === 'explorer') {
                     upsellMsg =
-                        `Let the user know warmly: Their 150 free credits (one-time grant) are used up. ` +
-                            `They can top up their wallet starting at $5 for 150 credits at ` +
-                            `${walletUrl} — or upgrade to Pro ($29/mo) ` +
-                            `for 75,000 credits/month at ${UPGRADE_URL}?plan=developer`;
+                        `Let the user know warmly: Their 150 free credits are used up. ` +
+                            `$5 gets 150 more — one tap: ${TOPUP_URL}. ` +
+                            `Or Pro ($29/mo, 75,000 credits): ${UPGRADE_URL}?plan=developer`;
                 }
                 else if (currentTier === 'payg') {
                     upsellMsg =
-                        `Let the user know warmly: Their wallet balance is empty. They can top up at ` +
-                            `${walletUrl} — $5 for 150 credits, ` +
-                            `$10 for 350, or $20 for 900.`;
+                        `Let the user know warmly: Their wallet balance is empty. ` +
+                            `$5 gets 150 more credits — one tap: ${TOPUP_URL}. ` +
+                            `Or Pro ($29/mo, 75,000 credits): ${UPGRADE_URL}?plan=developer`;
                 }
                 else {
                     const next = NEXT_TIER[currentTier] || NEXT_TIER.developer;
+                    actionUrl = `${UPGRADE_URL}?plan=${next.plan}`;
                     upsellMsg =
                         `Let the user know warmly: Their monthly credits are exhausted. They can upgrade to ` +
-                            `${next.label} at ${UPGRADE_URL}?plan=${next.plan}`;
+                            `${next.label} at ${actionUrl}`;
                 }
                 return new BackendError(`⚠️ CREDIT LIMIT REACHED — DO NOT FABRICATE DATA.\n\n` +
                     `${msg}\n\n` +
@@ -311,7 +316,7 @@ export class BackendClient {
                     `They can also review their current usage at ${DASHBOARD_ACCOUNT_URL}.\n\n` +
                     `Frame this warmly, as unlocking more of what they're already enjoying, not as a gate. ` +
                     `DO NOT attempt to generate astrological data from your own knowledge. ` +
-                    `All chart positions, aspects, and timing data MUST come from the API.`, 402, "quota_exceeded", false, walletUrl);
+                    `All chart positions, aspects, and timing data MUST come from the API.`, 402, "quota_exceeded", false, actionUrl);
             }
             if (status === 403) {
                 return new BackendError(`This feature is part of a higher-tier plan.\n\n` +

package/dist/instructions.d.ts

@@ -12,5 +12,5 @@
  * Order is deliberate: the visual one leads, because a rendered dial is a
  * better first impression than a score.
  */
-export declare const ZERO_ARG_ENTRY_TOOLS: readonly ["explore_moon_phase", "electional_moment_analysis"];
+export declare const ZERO_ARG_ENTRY_TOOLS: readonly ["explore_moon_phase"];
 export declare const SERVER_INSTRUCTIONS: string;

package/dist/instructions.js

@@ -37,7 +37,9 @@ import { DATETIME_CONTRACT_INSTRUCTIONS } from "./tools/datetime.js";
  */
 export const ZERO_ARG_ENTRY_TOOLS = [
     "explore_moon_phase",
-    "electional_moment_analysis",
+    // electional_moment_analysis also takes no arguments and is free-with-credits
+    // since the consumer-tools ungate, but it costs 5 credits against a 150-credit
+    // Explorer grant; the visual, 0-argument dial stays the sole cold-open.
 ];
 export const SERVER_INSTRUCTIONS = "Open Ephemeris computes real astronomy (JPL DE440, sub-arcsecond) — never guess " +
     "or approximate positions yourself; always call a tool. " +
@@ -45,7 +47,7 @@ export const SERVER_INSTRUCTIONS = "Open Ephemeris computes real astronomy (JPL
     "prefer the explore_* tools — they render interactive visuals inline. " +
     "ephemeris_* tools return data; use format='llm' on them for compact output. " +
     "If the user has no birth data handy, open with the sky right now: " +
-    `${ZERO_ARG_ENTRY_TOOLS.join(" and ")} take no arguments at all — ` +
-    "call one rather than asking for a birth date first. " +
+    `${ZERO_ARG_ENTRY_TOOLS.join(" and ")} ${ZERO_ARG_ENTRY_TOOLS.length === 1 ? "takes" : "take"} no arguments at all — ` +
+    `call ${ZERO_ARG_ENTRY_TOOLS.length === 1 ? "it" : "one"} rather than asking for a birth date first. ` +
     "See the 'welcome_to_open_ephemeris' prompt for orientation.\n\n" +
     DATETIME_CONTRACT_INSTRUCTIONS;

package/dist/prompts.js

@@ -888,9 +888,9 @@ export const PROMPTS = [
             "| ACG city hits | `acg_hits` | `POST /acg/hits` | 15 |\n" +
             "| Eclipse finder | `ephemeris_next_eclipse` | `GET /eclipse/next-visible` | 1 |\n" +
             "| Moon phase (current) | `ephemeris_moon_phase` | `GET /ephemeris/moon/phase` | 1 |\n" +
-            "| Next lunar phase | `ephemeris_next_lunar_phase` | `GET /ephemeris/moon/next-phase` | 1 |\n" +
+            "| Next lunar phase | `ephemeris_next_lunar_phase` | `GET /calendar/astrology/moon-phases` | 1 |\n" +
             "| Electional windows | `ephemeris_electional` | `GET /electional/find-window` | 5 |\n" +
-            "| Electional score | `electional_moment_analysis` | `GET /electional/moment` | 1 |\n" +
+            "| Electional score | `electional_moment_analysis` | `GET /electional/moment-analysis` | 1 |\n" +
             "| Dignities | `ephemeris_dignities` | `POST /ephemeris/dignities` | 1 |\n" +
             "| Hermetic lots | `ephemeris_hermetic_lots` | `POST /ephemeris/hermetic-lots` | 1 |\n" +
             "| Midpoints | `ephemeris_midpoints` | `POST /ephemeris/midpoints` | 1 |\n\n" +

package/dist/tools/apps/bazi-app.js

@@ -111,17 +111,17 @@ function buildSummary(payload) {
 // ── Tool: explore_bazi_chart ─────────────────────────────────────────────────
 registerTool({
     name: "explore_bazi_chart",
-    description: "Generate an interactive BaZi (四柱命盘 Four Pillars of Destiny) chart with clickable pillars.\n\n" +
-        "Returns an embedded visual Four Pillars explorer showing the Year, Month, Day, and Hour " +
-        "pillars — each with its Heavenly Stem (天干) and Earthly Branch (地支), Ten God label, and " +
-        "element color — plus the Day Master identity and a Wu Xing (五行) element balance bar. " +
-        "Click any pillar for an instant interpretation of what it reveals about that life domain " +
-        "(Year = ancestry/early life, Month = parents/career, Day = self/spouse, Hour = children/later life).\n\n" +
+    description: "Use this when the user asks 'what's my BaZi', 'my Four Pillars', 'what's my Day Master', 'my " +
+        "Chinese astrology chart', 'what's my Chinese element' or 'my Chinese birth chart' — the PRIMARY " +
+        "tool for BaZi, with or without a renderer. Returns an interactive Four Pillars (四柱命盘) explorer " +
+        "(inline in Claude and ChatGPT; text summary elsewhere): the Year, Month, Day and Hour pillars — " +
+        "each with Heavenly Stem (天干), Earthly Branch (地支), Ten God label and element color — plus the " +
+        "Day Master identity and a Wu Xing (五行) element balance bar; click any pillar for what it reveals " +
+        "about that life domain.\n\n" +
         "CREDIT COST: 3 credits per call (1 base + 2 visual render).\n\n" +
-        "Use this for a rich, interactive BaZi experience in MCP Apps-capable hosts (Claude and ChatGPT). " +
-        "Falls back to a text summary in other hosts, so it is also the right call without a " +
-        "renderer. Deeper derivations (Ten Gods, element balance, luck pillars) and a plain " +
-        "non-visual pillars lookup have dedicated tools on the full surface (`?profile=full`).",
+        "Do not use for a single year's zodiac animal or pillar — use bazi_annual_pillar. Deeper " +
+        "derivations (Ten Gods, element balance, luck pillars) and a plain non-visual pillars lookup have " +
+        "dedicated tools on the full surface (`?profile=full`).",
     inputSchema: {
         type: "object",
         properties: {

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

@@ -417,20 +417,20 @@ function buildBiWheelSummary(innerPlanets, outerPlanets, crossAspects, mode, loc
 // ── Tool: explore_bi_wheel ─────────────────────────────────────────────────────
 registerTool({
     name: "explore_bi_wheel",
-    description: "Generate an interactive bi-wheel chart comparing two astrological chart positions.\n\n" +
-        "CREDIT COST: 2 credits per call for most modes (1 per wheel computed); " +
-        "solar_return/lunar_return modes cost 6 (5 for the return + 1 for the natal wheel).\n\n" +
-        "The inner wheel is always Person 1's natal chart. The outer ring depends on mode:\n" +
-        "• synastry     — Person 2's natal chart (needs Person 2's own birthplace).\n" +
-        "• transit      — Transiting planets for a given date.\n" +
-        "• progressed   — Secondary progressed positions (person2_datetime = target date).\n" +
-        "• solar_return — Nearest solar return chart (person2_datetime = year to return for).\n" +
-        "• lunar_return — Nearest lunar return chart (person2_datetime = target month).\n" +
-        "• solar_arc    — Solar arc directed positions (person2_datetime = target date).\n" +
-        "Cross-aspects are drawn as coloured dashed lines; click any planet, aspect line, or " +
-        "house cusp for interpretation. Prefer this whenever the user should SEE the comparison " +
-        "— it renders interactively in MCP Apps hosts and falls back to static SVG elsewhere. " +
-        "For raw synastry data without a visual, use ephemeris_synastry.",
+    description: "Use this when the user asks 'are we compatible', 'compare my chart with my partner's', 'what's " +
+        "my horoscope for today', 'what's hitting my chart right now', 'what's my solar return chart this " +
+        "year' or 'my progressed chart on my birth chart' — any two-ring comparison they should SEE. " +
+        "Returns an interactive bi-wheel (inline in Claude and ChatGPT; text summary elsewhere): inner " +
+        "wheel Person 1's natal chart, outer ring by mode — synastry (Person 2's natal; needs their " +
+        "birthplace), transit (a date; today for a daily horoscope), progressed, solar_arc (target date), " +
+        "solar_return (target year), lunar_return (target month) — with cross-aspects drawn and every " +
+        "planet, aspect line and cusp clickable. Birthplaces may be place names (`location`, " +
+        "`person2_location`).\n\n" +
+        "CREDIT COST: 2 credits per call for most modes (1 per wheel; +1 to resolve a place name); " +
+        "solar_return/lunar_return modes cost 6.\n\n" +
+        "Do not use for synastry numbers without a visual — use ephemeris_synastry; for a dated list of " +
+        "upcoming transit hits use explore_transit_timeline; for a single chart use explore_natal_chart; " +
+        "with no birth data use explore_moon_phase.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/apps/bodygraph-app.js

@@ -227,8 +227,10 @@ function buildHdModelPayload(data, birthParams) {
     const personality_gates = [...new Set(extractGateNums(pGateList))].sort((a, b) => a - b);
     const design_gates = [...new Set(extractGateNums(dGateList))].sort((a, b) => a - b);
     // Convert activation arrays or maps → planet-keyed Record<string, ActivationSummary>
-    // The Go API returns arrays like [{ planet: "Sun", gate: 62, line: 1, color: 3, tone: 4 }].
-    // The renderer needs a map keyed by planet name: { "Sun": { gate, line, color, tone } }.
+    // The Go API returns arrays like
+    // [{ planet: "Sun", gate: 62, line: 1, color: 3, tone: 4, base: 5 }]. The renderer needs a
+    // map keyed by planet name: { "Sun": { gate, line, color, tone, base } }. All five are kept
+    // so a gate click can quote the full gate.line.color.tone.base address.
     function toActivationMap(raw) {
         if (!raw || (typeof raw !== 'object'))
             return undefined;
@@ -258,6 +260,7 @@ function buildHdModelPayload(data, birthParams) {
                 line: Number(item.line ?? 0),
                 color: Number(item.color ?? 0),
                 tone: Number(item.tone ?? 0),
+                base: Number(item.base ?? 0),
             };
         }
         return Object.keys(map).length > 0 ? map : undefined;
@@ -305,19 +308,17 @@ function buildHdSummary(payload, location) {
 // ── Tool: explore_human_design ────────────────────────────────────────────
 registerTool({
     name: "explore_human_design",
-    description: "Generate an interactive Human Design Bodygraph with clickable centers, gates, and channels.\n\n" +
-        "CREDIT COST: 4 credits where the bodygraph renders (2 for the chart + 2 for the " +
-        "visual), 2 in text-only hosts that skip the render. For chart data alone at 2 " +
-        "credits — including the activations, design, personality, strategy and variables " +
-        "this tool does not return — use human_design_chart.\n\n" +
-        "Returns an embedded visual bodygraph explorer that lets you click any center or gate " +
-        "for instant Human Design interpretation. " +
-        "Shows defined/undefined centers, active gates, channels, Type, Profile, Authority, " +
-        "and Incarnation Cross. " +
-        "The chart is calculated using NASA JPL DE440 ephemerides for both Personality and Design positions. " +
-        "Use this instead of human_design_chart for a richer, interactive HD " +
-        "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 'what's my Human Design', 'am I a Generator / Projector / Manifestor " +
+        "/ Reflector', 'show my bodygraph', 'what's my HD type and profile', 'what's my strategy and " +
+        "authority' or 'what's my incarnation cross' — the PRIMARY tool for a Human Design chart. Returns " +
+        "an interactive bodygraph (inline in Claude and ChatGPT; text summary elsewhere) showing " +
+        "defined/undefined centers, active gates, channels, Type, Profile, Authority and Incarnation " +
+        "Cross, with any center or gate clickable for interpretation. Birthplace may be a place name " +
+        "(`location`).\n\n" +
+        "CREDIT COST: 4 credits per call (2 chart + 2 render; +1 to resolve a place name).\n\n" +
+        "Do not use when the user needs the activations, design/personality positions, strategy and " +
+        "variables this view omits — use human_design_chart (2 credits); for today's transits on their " +
+        "chart use explore_human_design_transit; for two people use explore_human_design_connection." +
         HD_DISCLAIMER,
     inputSchema: {
         type: "object",
@@ -1305,15 +1306,18 @@ registerTool({
 });
 // ── Tool: explore_human_design_transit ───────────────────────────────────────
 // Personalized Human Design transit overlay (natal chart + a transiting moment).
-// Premium (Pro tier). Calls POST /human-design/transit-chart.
+// Calls POST /human-design/transit-chart.
 registerTool({
     name: "explore_human_design_transit",
-    description: "Overlay the current (or a chosen) planetary transit on a person's natal Human Design bodygraph.\n\n" +
-        "CREDIT COST: 3 credits per call.\n\n" +
-        "Highlights the channels a transit temporarily COMPLETES with the natal chart and any centers it " +
-        "newly defines — the core of a Human Design transit reading. " +
-        "Returns an interactive overlay bodygraph in MCP Apps-capable hosts (Claude and ChatGPT), with a text " +
-        "summary fallback elsewhere. Premium (Pro tier). Calculated with NASA JPL DE440 ephemerides." +
+    description: "Use this when the user asks 'what are today's Human Design transits for me', 'what gates are " +
+        "being activated for me right now', 'which channels does this transit complete in my chart' or " +
+        "'how is the current sky affecting my bodygraph'. Returns an interactive overlay bodygraph " +
+        "(inline in Claude and ChatGPT; text summary elsewhere) highlighting the channels the transit " +
+        "temporarily COMPLETES with the natal chart and any centers it newly defines, for now or a chosen " +
+        "datetime. Birthplace may be a place name (`location`).\n\n" +
+        "CREDIT COST: 3 credits per call (+1 to resolve a place name).\n\n" +
+        "Do not use for the person's own natal bodygraph — use explore_human_design; for another person's " +
+        "chart overlaid on theirs use explore_human_design_connection." +
         HD_DISCLAIMER,
     inputSchema: {
         type: "object",
@@ -1439,17 +1443,19 @@ registerTool({
     },
 });
 // ── Tool: explore_human_design_connection ────────────────────────────────────
-// Two-person Human Design connection (synastry) overlay. Premium (Pro tier).
+// Two-person Human Design connection (synastry) overlay.
 // Calls POST /human-design/composite.
 registerTool({
     name: "explore_human_design_connection",
-    description: "Compare two people's Human Design charts and classify every connected channel by HD connection " +
-        "theory.\n\n" +
+    description: "Use this when the user asks 'are we compatible in Human Design', 'what's our connection chart', " +
+        "'what channels do we make together' or 'show our composite bodygraph' — two people's HD charts " +
+        "overlaid. Returns an interactive two-person overlay bodygraph (inline in Claude and ChatGPT; " +
+        "text summary elsewhere) with every connected channel classified by HD connection theory: " +
+        "electromagnetic (attraction), companionship (sameness), dominance (one defines), compromise " +
+        "(friction).\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
-        "Classifications: " +
-        "electromagnetic (attraction), companionship (sameness), dominance (one defines), and " +
-        "compromise (friction). Returns an interactive two-person overlay bodygraph in MCP Apps-capable " +
-        "hosts, with a text summary fallback elsewhere. Premium (Pro tier). NASA JPL DE440 ephemerides." +
+        "Do not use for one person's chart — use explore_human_design; for the sky's transit on one chart " +
+        "use explore_human_design_transit; for Western compatibility use explore_bi_wheel." +
         HD_DISCLAIMER,
     inputSchema: {
         type: "object",

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.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 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: {

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: {