@openephemeris/mcp-server 3.13.9 → 3.13.10

package/dist/tools/specialized/bazi.js

@@ -1,68 +1,391 @@
 import { registerTool } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
+function parseBaziArgs(args) {
+    let { year, month, day, hour } = args;
+    if (args.datetime && (!year || !month || !day)) {
+        const dt = new Date(args.datetime);
+        if (!isNaN(dt.getTime())) {
+            year = dt.getUTCFullYear();
+            month = dt.getUTCMonth() + 1;
+            day = dt.getUTCDate();
+            if (hour == null)
+                hour = dt.getUTCHours();
+        }
+    }
+    if (!year || !month || !day) {
+        throw new Error("Provide year/month/day fields, or a datetime ISO string. " +
+            "Example: year=1987, month=7, day=15 OR datetime='1987-07-15T14:00:00'");
+    }
+    const out = { year, month, day };
+    if (hour != null)
+        out.hour = hour;
+    return out;
+}
+// Shared datetime input schema fragment — used across all BaZiRequest tools.
+const DATETIME_PROPERTIES = {
+    year: {
+        type: "integer",
+        description: "Gregorian birth year, e.g. 1987.",
+    },
+    month: {
+        type: "integer",
+        description: "Birth month (1–12).",
+    },
+    day: {
+        type: "integer",
+        description: "Birth day of month (1–31).",
+    },
+    hour: {
+        type: "integer",
+        description: "Birth hour (0–23). Optional, defaults to 12 (noon). " +
+            "Chinese shí hours are 2-hour blocks — precision within a 2-hour window is sufficient.",
+    },
+    datetime: {
+        type: "string",
+        description: "Alternative to year/month/day: ISO 8601 datetime (e.g. '1987-07-15T14:00:00'). " +
+            "year/month/day/hour are extracted automatically. Use this OR the individual fields.",
+    },
+};
+// Shared visual input schema fragment — mirrors natal.ts pattern.
+const VISUAL_PROPERTIES = {
+    include_visual: {
+        type: "boolean",
+        description: "When true, the response includes a rendered SVG chart of the Four Pillars. " +
+            "Costs an extra 2 credits (total 3 credits). Ideal for delivering a visual alongside text analysis.",
+    },
+    visual_config: {
+        type: "object",
+        description: "Optional rendering preferences. Only relevant when include_visual=true.",
+        properties: {
+            theme: {
+                type: "string",
+                enum: ["light", "dark", "mono"],
+                description: "Chart color theme. Defaults to 'light'.",
+            },
+            size: {
+                type: "integer",
+                description: "Chart width in pixels (400–1600). Defaults to 800.",
+            },
+        },
+        additionalProperties: false,
+    },
+};
+// buildVisualBody appends include_visual and visual_config to a request body
+// when the caller passes include_visual=true.
+function applyVisualConfig(body, args) {
+    if (args.include_visual) {
+        body.include_visual = true;
+        body.visual_config = {
+            format: "svg", // always SVG for MCP — no resvg dependency in prod
+            theme: args.visual_config?.theme ?? "light",
+            size: args.visual_config?.size ?? 800,
+        };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// chinese_bazi — base Four Pillars chart
+// ─────────────────────────────────────────────────────────────────────────────
 registerTool({
     name: "chinese_bazi",
-    description: "Calculate a Chinese Ba Zi (Four Pillars of Destiny) chart. Returns the Year, Month, Day, " +
-        "and Hour pillars, each containing a Heavenly Stem and Earthly Branch pair. Also includes " +
-        "the Day Master element, Wu Xing element breakdown, and basic interpretation context.\n\n" +
-        "CREDIT COST: 1 credit per call.\n\n" +
-        "You can provide either a datetime string (which will be decomposed automatically) " +
-        "or explicit year/month/day/hour values.\n\n" +
-        "EXAMPLE: Ba Zi for someone born July 15, 1987 at 2:00 PM:\n" +
+    description: "Calculate a Chinese BaZi (四柱命盘 Four Pillars of Destiny) chart. Returns the Year, Month, Day, " +
+        "and Hour pillars, each with a Heavenly Stem (天干) and Earthly Branch (地支) pair. " +
+        "Includes the Day Master element and basic metadata.\n\n" +
+        "CREDIT COST: 1 credit (3 credits when include_visual=true).\n\n" +
+        "Set include_visual=true to receive a rendered SVG chart alongside the text data.\n\n" +
+        "For deep analysis, follow up with:\n" +
+        "  • bazi_ten_gods()         — Ten Gods (十神) per pillar including hidden stems\n" +
+        "  • bazi_element_balance()  — Weighted Wu Xing (五行) element scores + Yong Shen\n" +
+        "  • bazi_luck_pillars()     — 8 Da Yun 10-year luck cycles\n\n" +
+        "EXAMPLE: BaZi chart for someone born July 15, 1987 at 2 PM:\n" +
+        "  year=1987, month=7, day=15, hour=14",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ...DATETIME_PROPERTIES,
+            ...VISUAL_PROPERTIES,
+        },
+        additionalProperties: false,
+    },
+    annotations: { title: "BaZi Four Pillars Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        const body = { ...parseBaziArgs(args) };
+        applyVisualConfig(body, args);
+        return await getActiveClient().request("POST", "/chinese/bazi", { data: body });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_ten_gods — Ten Gods (十神) analysis
+// ─────────────────────────────────────────────────────────────────────────────
+registerTool({
+    name: "bazi_ten_gods",
+    description: "Calculate the Ten Gods (十神 Shí Shén) for a BaZi chart. Each of the 10 gods describes " +
+        "the relationship between the Day Master (日主, the person's core identity element) and " +
+        "every other Heavenly Stem in the chart — including visible stems and the hidden stems " +
+        "stored within each Earthly Branch.\n\n" +
+        "The 10 gods and their categories:\n" +
+        "  COMPANION: Friend (比肩), Rob Wealth (劫财)\n" +
+        "  OUTPUT:    Eating God (食神), Hurting Officer (伤官)\n" +
+        "  WEALTH:    Indirect Wealth (偏财), Direct Wealth (正财)\n" +
+        "  POWER:     Seven Killings (七杀), Direct Officer (正官)\n" +
+        "  RESOURCE:  Indirect Resource (偏印), Direct Resource (正印)\n\n" +
+        "The Day Pillar itself has no Ten God (it IS the Day Master). " +
+        "Hidden stems in the Day Branch still receive Ten God labels.\n\n" +
+        "CREDIT COST: 1 credit (3 credits when include_visual=true).\n\n" +
+        "Set include_visual=true to receive an SVG Four Pillars chart alongside the Ten Gods data.\n\n" +
+        "EXAMPLE: Ten Gods for someone born July 15, 1987 at 2 PM:\n" +
         "  year=1987, month=7, day=15, hour=14",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ...DATETIME_PROPERTIES,
+            ...VISUAL_PROPERTIES,
+        },
+        additionalProperties: false,
+    },
+    annotations: { title: "BaZi Day Master Analysis", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        const body = { ...parseBaziArgs(args) };
+        applyVisualConfig(body, args);
+        return await getActiveClient().request("POST", "/chinese/bazi/ten-gods", { data: body });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_element_balance — Wu Xing (五行) weighted element analysis
+// ─────────────────────────────────────────────────────────────────────────────
+registerTool({
+    name: "bazi_element_balance",
+    description: "Calculate the weighted Wu Xing (五行 Five Elements) distribution for a BaZi chart. " +
+        "Returns percentage scores for Wood, Fire, Earth, Metal, and Water across all chart positions.\n\n" +
+        "Scoring is weighted — hidden stems inside Earthly Branches count toward element totals:\n" +
+        "  • Visible Heavenly Stems: 1.0 weight each (4 positions)\n" +
+        "  • Hidden Stem main (本气):      1.0 weight\n" +
+        "  • Hidden Stem secondary (中气): 0.6 weight\n" +
+        "  • Hidden Stem residual (余气):  0.3 weight\n\n" +
+        "Also returns:\n" +
+        "  • Day Master strength: 'strong' (旺, ≥50% own+resource elements) or 'weak' (弱)\n" +
+        "  • Yong Shen (用神): the favorable element — what the chart needs most\n\n" +
+        "CREDIT COST: 1 credit (3 credits when include_visual=true).\n\n" +
+        "Set include_visual=true to receive an SVG Four Pillars chart alongside the element data.\n\n" +
+        "EXAMPLE: Element balance for 1987-07-15 at 14:00:\n" +
+        "  year=1987, month=7, day=15, hour=14",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ...DATETIME_PROPERTIES,
+            ...VISUAL_PROPERTIES,
+        },
+        additionalProperties: false,
+    },
+    annotations: { title: "BaZi Clash & Combination", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        const body = { ...parseBaziArgs(args) };
+        applyVisualConfig(body, args);
+        return await getActiveClient().request("POST", "/chinese/bazi/element-balance", { data: body });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_luck_pillars — Da Yun (大运) 10-year luck cycles
+// ─────────────────────────────────────────────────────────────────────────────
+registerTool({
+    name: "bazi_luck_pillars",
+    description: "Calculate the 8 Da Yun (大运) 10-year luck pillar cycles for a BaZi chart. " +
+        "Luck pillars sequence through the sexagenary cycle starting from a person's " +
+        "'starting age' (起运岁数), calculated by counting days from birth to the nearest " +
+        "solar term boundary (Jié 节). Each 3 days = 1 year of starting age (Zi Ping rule).\n\n" +
+        "Direction (forward/backward) depends on gender and year polarity:\n" +
+        "  • Male in Yang year → forward\n" +
+        "  • Male in Yin year → backward\n" +
+        "  • Female in Yang year → backward\n" +
+        "  • Female in Yin year → forward\n\n" +
+        "gender is REQUIRED — the direction of luck pillars is gender-dependent.\n\n" +
+        "Returns: starting_age, direction, direction_reason, and 8 pillars each with:\n" +
+        "  stem, branch, Chinese characters, element, start_age, end_age\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Luck pillars for a female born July 15, 1987 at 2 PM:\n" +
+        "  year=1987, month=7, day=15, hour=14, gender='female'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ...DATETIME_PROPERTIES,
+            gender: {
+                type: "string",
+                enum: ["male", "female"],
+                description: "Required. Determines the direction of Da Yun progression. " +
+                    "Male in Yang year / Female in Yin year → forward. " +
+                    "Male in Yin year / Female in Yang year → backward.",
+            },
+        },
+        required: ["gender"],
+        additionalProperties: false,
+    },
+    annotations: { title: "BaZi Ten Gods", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        if (!args.gender) {
+            throw new Error("gender is required for luck pillar calculation. " +
+                "Provide 'male' or 'female' — the direction of Da Yun depends on gender and year polarity.");
+        }
+        const { year, month, day, hour } = parseBaziArgs(args);
+        const body = { year, month, day, gender: args.gender };
+        if (hour != null)
+            body.hour = hour;
+        return await getActiveClient().request("POST", "/chinese/bazi/luck-pillars", { data: body });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_annual_pillar — sexagenary year pillar + NaYin
+// ─────────────────────────────────────────────────────────────────────────────
+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" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Year pillar for 2025:\n" +
+        "  year=2025",
     inputSchema: {
         type: "object",
         properties: {
             year: {
                 type: "integer",
-                description: "Gregorian birth year, e.g. 1987.",
+                description: "Gregorian year (1–9999). e.g. 2025.",
             },
-            month: {
-                type: "integer",
-                description: "Birth month (1-12).",
+        },
+        required: ["year"],
+        additionalProperties: false,
+    },
+    annotations: { title: "BaZi Luck Pillars", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        if (!args.year) {
+            throw new Error("year is required. Provide a Gregorian year (1–9999), e.g. year=2025.");
+        }
+        return await getActiveClient().request("POST", "/chinese/bazi/annual-pillar", {
+            data: { year: args.year },
+        });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_compatibility — pair chart scoring
+// ─────────────────────────────────────────────────────────────────────────────
+registerTool({
+    name: "bazi_compatibility",
+    description: "Calculate BaZi compatibility between two people by comparing their Four Pillars charts. " +
+        "Returns a score 0–100, an assessment, and a breakdown of the harmony/clash/penalty " +
+        "factors found between the two charts.\n\n" +
+        "Scoring factors include:\n" +
+        "  +5  Six Harmony (六合 Liù Hé) — branch pair bonds\n" +
+        "  +8  Three Harmonies (三合 Sān Hé) — branch trinity formations\n" +
+        "  -8  Six Clash (六冲 Liù Chōng) — opposing branch pairs\n" +
+        "  -5  Six Harm (六害 Liù Hài) — branch interference pairs\n" +
+        "  -6  Three Penalties (三刑 Sān Xíng) — branch penalty formations\n\n" +
+        "Assessment grades:\n" +
+        "  90–100: excellent | 70–89: good | 50–69: moderate | below 50: challenging\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: Compatibility between two people:\n" +
+        "  chart_a_year=1987, chart_a_month=7, chart_a_day=15, chart_a_hour=14\n" +
+        "  chart_b_year=1990, chart_b_month=3, chart_b_day=22, chart_b_hour=8",
+    inputSchema: {
+        type: "object",
+        properties: {
+            // Chart A
+            chart_a_year: { type: "integer", description: "Chart A birth year." },
+            chart_a_month: { type: "integer", description: "Chart A birth month (1–12)." },
+            chart_a_day: { type: "integer", description: "Chart A birth day (1–31)." },
+            chart_a_hour: { type: "integer", description: "Chart A birth hour (0–23). Optional." },
+            chart_a_datetime: {
+                type: "string",
+                description: "Chart A alternative: ISO 8601 datetime. Extracts year/month/day/hour automatically.",
             },
-            day: {
-                type: "integer",
-                description: "Birth day of month (1-31).",
+            // Chart B
+            chart_b_year: { type: "integer", description: "Chart B birth year." },
+            chart_b_month: { type: "integer", description: "Chart B birth month (1–12)." },
+            chart_b_day: { type: "integer", description: "Chart B birth day (1–31)." },
+            chart_b_hour: { type: "integer", description: "Chart B birth hour (0–23). Optional." },
+            chart_b_datetime: {
+                type: "string",
+                description: "Chart B alternative: ISO 8601 datetime. Extracts year/month/day/hour automatically.",
             },
-            hour: {
-                type: "integer",
-                description: "Birth hour (0-23). Optional, defaults to 12 (noon). " +
-                    "Chinese hours (shí) are 2-hour blocks, so precision within a 2-hour window is sufficient.",
+        },
+        additionalProperties: false,
+    },
+    annotations: { title: "BaZi Annual Pillars", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        const chartAComponents = parseBaziArgs({
+            year: args.chart_a_year,
+            month: args.chart_a_month,
+            day: args.chart_a_day,
+            hour: args.chart_a_hour,
+            datetime: args.chart_a_datetime,
+        });
+        const chartBComponents = parseBaziArgs({
+            year: args.chart_b_year,
+            month: args.chart_b_month,
+            day: args.chart_b_day,
+            hour: args.chart_b_hour,
+            datetime: args.chart_b_datetime,
+        });
+        return await getActiveClient().request("POST", "/chinese/bazi/compatibility", {
+            data: {
+                chart_a: chartAComponents,
+                chart_b: chartBComponents,
             },
-            datetime: {
+        });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_chart — dedicated Four Pillars SVG chart visual
+// ─────────────────────────────────────────────────────────────────────────────
+registerTool({
+    name: "bazi_chart",
+    description: "Render a self-contained SVG chart of a BaZi Four Pillars chart. " +
+        "Returns a production-quality visualization showing:\n" +
+        "  • All four pillars (Year, Month, Day, Hour) with Heavenly Stems and Earthly Branches\n" +
+        "  • Ten Gods (十神) labels for each non-Day pillar\n" +
+        "  • Wu Xing (五行) element balance bar chart\n" +
+        "  • Day Master identity with element and polarity\n\n" +
+        "The chart is rendered in the Open Ephemeris design system (OKLCH color tokens) " +
+        "and is fully self-contained — suitable for embedding or display without dependencies.\n\n" +
+        "Theme options: 'light' (default), 'dark', 'mono'.\n\n" +
+        "CREDIT COST: 3 credits per call (1 base + 2 visual render).\n\n" +
+        "Use this tool when the user asks to 'show', 'visualize', 'draw', or 'render' " +
+        "a BaZi / Four Pillars chart. For text-only data, use chinese_bazi() instead.\n\n" +
+        "EXAMPLE: Render a chart for someone born July 15, 1987 at 2 PM:\n" +
+        "  year=1987, month=7, day=15, hour=14",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ...DATETIME_PROPERTIES,
+            theme: {
                 type: "string",
-                description: "Alternative: ISO 8601 datetime (e.g. '1987-07-15T14:00:00'). " +
-                    "If provided, year/month/day/hour are extracted automatically. " +
-                    "Use this OR the individual year/month/day fields, not both.",
+                enum: ["light", "dark", "mono"],
+                description: "Chart color theme. Defaults to 'light'.",
+            },
+            size: {
+                type: "integer",
+                description: "Chart width in pixels (400–1600). Defaults to 800.",
             },
         },
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "BaZi Compatibility", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
-        let year = args.year;
-        let month = args.month;
-        let day = args.day;
-        let hour = args.hour;
-        // If datetime provided, extract components
-        if (args.datetime && (!year || !month || !day)) {
-            const dt = new Date(args.datetime);
-            if (!isNaN(dt.getTime())) {
-                year = dt.getUTCFullYear();
-                month = dt.getUTCMonth() + 1;
-                day = dt.getUTCDate();
-                if (hour == null)
-                    hour = dt.getUTCHours();
-            }
-        }
-        if (!year || !month || !day) {
-            throw new Error("Either provide year/month/day fields, or a datetime string. " +
-                "Example: year=1987, month=7, day=15 OR datetime='1987-07-15T14:00:00'");
-        }
-        const body = { year, month, day };
+        const { year, month, day, hour } = parseBaziArgs(args);
+        const body = {
+            year, month, day,
+            visual_config: {
+                format: "svg",
+                theme: args.theme ?? "light",
+                size: args.size ?? 800,
+            },
+        };
         if (hour != null)
             body.hour = hour;
-        return await getActiveClient().request("POST", "/chinese/bazi", { data: body });
+        return await getActiveClient().request("POST", "/chinese/bazi/chart", { data: body });
     },
 });

package/dist/tools/specialized/bi_wheel.js

@@ -38,7 +38,7 @@ registerTool({
         required: ["datetime_a", "latitude_a", "longitude_a", "datetime_b", "latitude_b", "longitude_b"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Bi-Wheel Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime_a", "latitude_a", "longitude_a", "datetime_b", "latitude_b", "longitude_b"]);
         const body = {

package/dist/tools/specialized/chart_wheel.js

@@ -46,7 +46,7 @@ registerTool({
         required: ["datetime", "latitude", "longitude"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Chart Wheel SVG", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         const body = {

package/dist/tools/specialized/comparative.js

@@ -42,7 +42,7 @@ registerTool({
         ],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Davison Relationship Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -87,7 +87,7 @@ registerTool({
         ],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Midpoint Composite Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -132,7 +132,7 @@ registerTool({
         ],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Planet Compatibility Score", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -174,7 +174,7 @@ registerTool({
         required: ["natal_datetime", "natal_latitude", "natal_longitude"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Composite Chart Aspects", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude"]);
         // Backend expects: { subject: {...}, transit_datetime?: {...} }

package/dist/tools/specialized/eclipse.js

@@ -40,7 +40,7 @@ registerTool({
         required: ["eclipse_type"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Eclipse Finder", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["eclipse_type"]);
         validateCoordinates(args, "latitude", "longitude");

package/dist/tools/specialized/electional.js

@@ -56,7 +56,7 @@ registerTool({
         required: ["start_date", "end_date", "latitude", "longitude"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Electional Timing Window", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["start_date", "end_date", "latitude", "longitude"]);
         const query = {
@@ -106,7 +106,7 @@ registerTool({
         required: [],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Moment Quality Analysis", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         const query = {};
         if (args.date)
@@ -157,7 +157,7 @@ registerTool({
         required: [],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Retrograde Station Tracker", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         const query = {};
         // Map human-readable planet names to IDs if needed
@@ -216,7 +216,7 @@ registerTool({
         required: [],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Active Aspects Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         const query = {};
         if (args.date)

package/dist/tools/specialized/ephemeris_core.js

@@ -34,7 +34,7 @@ registerTool({
         required: ["planet_id", "datetime"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Planet Position", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["planet_id", "datetime"]);
         const body = {
@@ -81,7 +81,7 @@ registerTool({
         required: ["datetime", "latitude", "longitude"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "House Cusps", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         const body = {

package/dist/tools/specialized/ephemeris_extended.js

@@ -42,7 +42,7 @@ registerTool({
         required: ["subjects"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Natal Batch Charts", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["subjects"]);
         const items = args.subjects.map((s) => ({
@@ -65,7 +65,7 @@ registerTool({
         required: ["datetime"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Essential Dignities", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         return await getActiveClient().post("/ephemeris/dignities", {
@@ -92,7 +92,7 @@ registerTool({
         required: ["datetime"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Retrograde Status", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         const client = getActiveClient();
@@ -141,7 +141,7 @@ registerTool({
         required: ["datetime", "latitude", "longitude"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Midpoints", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/midpoints", {
@@ -171,7 +171,7 @@ registerTool({
         required: ["datetime"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Fixed Stars", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         const body = {
@@ -231,7 +231,7 @@ registerTool({
         required: ["datetime", "latitude", "longitude"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Hermetic Lots", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/hermetic-lots", {
@@ -257,7 +257,7 @@ registerTool({
         required: ["datetime", "latitude", "longitude"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Angles & Points", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/angles-points", {
@@ -285,7 +285,7 @@ registerTool({
         required: ["longitude_1", "longitude_2"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Aspect Check", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["longitude_1", "longitude_2"]);
         // Backend field names are longitude1 / longitude2 (no underscore)

package/dist/tools/specialized/hd_bodygraph.js

@@ -39,7 +39,7 @@ registerTool({
         required: ["datetime"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Human Design Bodygraph", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         const body = {