@openephemeris/mcp-server 3.24.0 → 4.1.0

package/dist/tools/specialized/bazi.js

@@ -1,17 +1,16 @@
 import { registerTool } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
-function parseBaziArgs(args) {
+export function parseBaziArgs(args, datetimeField = "datetime") {
     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();
-        }
+    const datetime = args[datetimeField];
+    if (datetime && (!year || !month || !day)) {
+        const parts = baziLocalComponents(datetime, args.timezone, datetimeField);
+        year = parts.year;
+        month = parts.month;
+        day = parts.day;
+        if (hour == null)
+            hour = parts.hour;
     }
     if (!year || !month || !day) {
         throw new Error("Provide year/month/day fields, or a datetime ISO string. " +
@@ -22,6 +21,49 @@ function parseBaziArgs(args) {
         out.hour = hour;
     return out;
 }
+/**
+ * Extract the LOCAL calendar/clock components a BaZi chart is built from.
+ *
+ * BaZi pillars are a function of local wall-clock time at the birth place — the
+ * hour pillar is a two-hour shí block on the local clock — so unlike a western
+ * chart there is no UTC instant to resolve to, and a zone-less datetime is
+ * exactly right here. What was wrong was HOW those components were read: the
+ * previous implementation did `new Date("1987-07-15T14:00:00")`, which JS parses
+ * in the *host process's* timezone, then read `.getUTCHours()`. On any server
+ * not running in UTC that silently shifted the hour pillar, and near midnight
+ * the day pillar too. Reading the components lexically removes the dependency on
+ * where the server happens to be.
+ *
+ * A datetime that carries its own zone (`Z` / `±HH:MM`) is not local wall-clock
+ * time. It is converted into `timezone` when one is supplied; without one, its
+ * own stated zone is taken as the local clock, which is the long-standing
+ * behaviour and the only reading available.
+ */
+function baziLocalComponents(datetime, timezone, field) {
+    const value = String(datetime).trim();
+    const zoned = /([Zz]|[+-]\d{2}:?\d{2})$/.test(value);
+    if (zoned && timezone) {
+        const parts = new Intl.DateTimeFormat("en-US", {
+            timeZone: timezone,
+            hour12: false,
+            year: "numeric", month: "2-digit", day: "2-digit",
+            hour: "2-digit", minute: "2-digit",
+        }).formatToParts(new Date(value));
+        const get = (t) => Number(parts.find((p) => p.type === t)?.value);
+        return { year: get("year"), month: get("month"), day: get("day"), hour: get("hour") % 24 };
+    }
+    const m = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2}))?/.exec(value);
+    if (!m) {
+        throw new Error(`\`${field}\` is "${value}", which is not an ISO 8601 date or datetime. ` +
+            "Example: '1987-07-15T14:00:00' (local time at the birth place).");
+    }
+    return {
+        year: Number(m[1]),
+        month: Number(m[2]),
+        day: Number(m[3]),
+        hour: m[4] != null ? Number(m[4]) : undefined,
+    };
+}
 // Shared datetime input schema fragment — used across all BaZiRequest tools.
 const DATETIME_PROPERTIES = {
     year: {
@@ -43,8 +85,17 @@ const DATETIME_PROPERTIES = {
     },
     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.",
+        description: "Alternative to year/month/day: ISO 8601 datetime read as LOCAL wall-clock time at the " +
+            "birth place — BaZi pillars are local by definition, so a zone-less value like " +
+            "'1987-07-15T14:00:00' is correct here and is NOT converted to UTC. " +
+            "If you pass an instant instead ('1987-07-15T19:00:00Z' or with an offset), also pass " +
+            "`timezone` so the local hour can be derived. Use this OR the individual fields.",
+    },
+    timezone: {
+        type: "string",
+        description: "IANA timezone name for the birth place, e.g. 'Asia/Shanghai'. Only needed when " +
+            "`datetime` carries a 'Z' or ±HH:MM offset, to convert that instant back to the local " +
+            "clock the pillars are built from.",
     },
 };
 // Shared visual input schema fragment — mirrors natal.ts pattern.
@@ -93,10 +144,9 @@ registerTool({
         "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" +
+        "For deep analysis — Ten Gods (十神) per pillar, weighted Wu Xing (五行) element balance, " +
+        "Da Yun 10-year luck cycles — dedicated tools are available on the full tool surface " +
+        "(`?profile=full` on HTTP, OPENEPHEMERIS_TOOLS=full on stdio).\n\n" +
         "EXAMPLE: BaZi chart for someone born July 15, 1987 at 2 PM:\n" +
         "  year=1987, month=7, day=15, hour=14",
     inputSchema: {
@@ -132,7 +182,7 @@ registerTool({
         "  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" +
+        "CREDIT COST: 3 credits (5 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",
@@ -167,7 +217,7 @@ registerTool({
         "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" +
+        "CREDIT COST: 3 credits (5 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",
@@ -204,7 +254,7 @@ registerTool({
         "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" +
+        "CREDIT COST: 3 credits 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: {
@@ -251,7 +301,7 @@ registerTool({
         "  • 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" +
+        "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE: Year pillar for 2025:\n" +
         "  year=2025",
     inputSchema: {
@@ -292,7 +342,7 @@ registerTool({
         "  -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" +
+        "CREDIT COST: 3 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",
@@ -306,7 +356,14 @@ registerTool({
             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.",
+                description: "Chart A alternative: ISO 8601 datetime read as LOCAL wall-clock time at the birth " +
+                    "place — a zone-less value is correct here and is not converted to UTC. If it carries " +
+                    "a 'Z' or offset, also pass chart_a_timezone. Extracts year/month/day/hour automatically.",
+            },
+            chart_a_timezone: {
+                type: "string",
+                description: "IANA timezone for Chart A's birth place, e.g. 'Asia/Shanghai'. Only needed when " +
+                    "chart_a_datetime carries a 'Z' or ±HH:MM offset.",
             },
             // Chart B
             chart_b_year: { type: "integer", description: "Chart B birth year." },
@@ -315,7 +372,14 @@ registerTool({
             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.",
+                description: "Chart B alternative: ISO 8601 datetime read as LOCAL wall-clock time at the birth " +
+                    "place — a zone-less value is correct here and is not converted to UTC. If it carries " +
+                    "a 'Z' or offset, also pass chart_b_timezone. Extracts year/month/day/hour automatically.",
+            },
+            chart_b_timezone: {
+                type: "string",
+                description: "IANA timezone for Chart B's birth place, e.g. 'Asia/Shanghai'. Only needed when " +
+                    "chart_b_datetime carries a 'Z' or ±HH:MM offset.",
             },
         },
         additionalProperties: false,
@@ -329,6 +393,7 @@ registerTool({
             day: args.chart_a_day,
             hour: args.chart_a_hour,
             datetime: args.chart_a_datetime,
+            timezone: args.chart_a_timezone,
         });
         const chartBComponents = parseBaziArgs({
             year: args.chart_b_year,
@@ -336,6 +401,7 @@ registerTool({
             day: args.chart_b_day,
             hour: args.chart_b_hour,
             datetime: args.chart_b_datetime,
+            timezone: args.chart_b_timezone,
         });
         return await getActiveClient().request("POST", "/chinese/bazi/compatibility", {
             data: {

package/dist/tools/specialized/bi_wheel.js

@@ -1,8 +1,7 @@
 import { registerTool, validateRequired, pickEnum } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE } from "../output-schemas.js";
-const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
-    "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
+import { DATETIME_DESC, assertZonedDatetime, timezoneProperty } from "../datetime.js";
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R", porphyry: "O",
@@ -19,11 +18,11 @@ registerTool({
         type: "object",
         properties: {
             datetime_a: { type: "string", description: DATETIME_DESC },
-            timezone_a: { type: "string", description: "IANA timezone name for subject A, e.g. 'America/Denver'." },
+            timezone_a: timezoneProperty("subject A's location", "America/Denver"),
             latitude_a: { type: "number", description: "Latitude for subject A" },
             longitude_a: { type: "number", description: "Longitude for subject A" },
             datetime_b: { type: "string", description: DATETIME_DESC },
-            timezone_b: { type: "string", description: "IANA timezone name for subject B, e.g. 'Europe/London'." },
+            timezone_b: timezoneProperty("subject B's location", "Europe/London"),
             latitude_b: { type: "number", description: "Latitude for subject B" },
             longitude_b: { type: "number", description: "Longitude for subject B" },
             house_system: {
@@ -44,6 +43,8 @@ registerTool({
     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"]);
+        assertZonedDatetime("datetime_a", args.datetime_a, args.timezone_a, "timezone_a");
+        assertZonedDatetime("datetime_b", args.datetime_b, args.timezone_b, "timezone_b");
         const body = {
             subject_a: {
                 name: "Subject A",

package/dist/tools/specialized/chart_wheel.js

@@ -1,8 +1,7 @@
 import { registerTool, validateRequired, pickEnum } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE } from "../output-schemas.js";
-const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
-    "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime } from "../datetime.js";
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R", porphyry: "O",
@@ -13,8 +12,8 @@ registerTool({
     description: "Generate a classic astrological Chart Wheel image (SVG) for a person/event. This draws a standard circular chart wheel with planets, aspects, and house cusps. The tool returns a native SVG image that Claude displays inline in the conversation — no external tools needed.\n\n" +
         "For a user-facing interactive chart wheel, use explore_natal_chart instead.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
-        "EXAMPLE: Generate a natal chart wheel for someone born April 15, 1990 in Chicago:\n" +
-        "  datetime='1990-04-15T14:30:00', latitude=41.8781, longitude=-87.6298",
+        "EXAMPLE: born 15 April 1990 at 2:30 PM local time in Chicago:\n" +
+        "  datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298",
     inputSchema: {
         type: "object",
         properties: {
@@ -22,10 +21,7 @@ registerTool({
                 type: "string",
                 description: DATETIME_DESC,
             },
-            timezone: {
-                type: "string",
-                description: "IANA timezone name, e.g. 'America/Denver'. Use this if passing local time without a UTC offset in the datetime string.",
-            },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
                 description: "Geographic latitude of birth location in decimal degrees (positive = North).",
@@ -52,6 +48,7 @@ registerTool({
     annotations: { title: "Chart Wheel SVG", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
+        assertZonedDatetime("datetime", args.datetime, args.timezone);
         const body = {
             subject: {
                 name: "Chart Wheel Request",

package/dist/tools/specialized/comparative.js

@@ -1,6 +1,11 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, assertZonedDatetime, localToUtcIso, timezoneProperty } from "../datetime.js";
+/** Reject a zone-less person datetime here, before a credit is spent on it. */
+function assertPersonZoned(prefix, args) {
+    assertZonedDatetime(`${prefix}_datetime`, args[`${prefix}_datetime`], args[`${prefix}_timezone`], `${prefix}_timezone`);
+}
 function buildSubject(name, datetime, lat, lon, timezone) {
     const subj = {
         name,
@@ -22,17 +27,19 @@ registerTool({
         "uses midpoints of each planet pair to derive a single relationship chart.\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE: Composite for two people:\n" +
-        "  person_a_datetime='1990-04-15T14:30:00', person_a_latitude=41.88, person_a_longitude=-87.63,\n" +
-        "  person_b_datetime='1988-09-22T08:15:00', person_b_latitude=34.05, person_b_longitude=-118.24",
+        "  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',\n" +
+        "  person_a_latitude=41.88, person_a_longitude=-87.63,\n" +
+        "  person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles',\n" +
+        "  person_b_latitude=34.05, person_b_longitude=-118.24",
     inputSchema: {
         type: "object",
         properties: {
-            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
-            person_a_timezone: { type: "string", description: "IANA timezone name for Person A, e.g. 'America/Denver'." },
+            person_a_datetime: { type: "string", description: DATETIME_DESC },
+            person_a_timezone: timezoneProperty("Person A's birth location", "America/Denver"),
             person_a_latitude: { type: "number", description: "Person A birth latitude." },
             person_a_longitude: { type: "number", description: "Person A birth longitude." },
-            person_b_datetime: { type: "string", description: "Person B birth datetime (ISO 8601)." },
-            person_b_timezone: { type: "string", description: "IANA timezone name for Person B, e.g. 'Europe/London'." },
+            person_b_datetime: { type: "string", description: DATETIME_DESC },
+            person_b_timezone: timezoneProperty("Person B's birth location", "Europe/London"),
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
             format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
@@ -50,6 +57,8 @@ registerTool({
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
             "person_b_datetime", "person_b_latitude", "person_b_longitude",
         ]);
+        assertPersonZoned("person_a", args);
+        assertPersonZoned("person_b", args);
         const query = {};
         if (args.format)
             query.format = args.format;
@@ -73,12 +82,12 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
-            person_a_timezone: { type: "string", description: "IANA timezone name for Person A, e.g. 'America/Denver'." },
+            person_a_datetime: { type: "string", description: DATETIME_DESC },
+            person_a_timezone: timezoneProperty("Person A's birth location", "America/Denver"),
             person_a_latitude: { type: "number", description: "Person A birth latitude." },
             person_a_longitude: { type: "number", description: "Person A birth longitude." },
-            person_b_datetime: { type: "string", description: "Person B birth datetime (ISO 8601)." },
-            person_b_timezone: { type: "string", description: "IANA timezone name for Person B, e.g. 'Europe/London'." },
+            person_b_datetime: { type: "string", description: DATETIME_DESC },
+            person_b_timezone: timezoneProperty("Person B's birth location", "Europe/London"),
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
             format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
@@ -96,6 +105,8 @@ registerTool({
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
             "person_b_datetime", "person_b_latitude", "person_b_longitude",
         ]);
+        assertPersonZoned("person_a", args);
+        assertPersonZoned("person_b", args);
         const query = {};
         if (args.format)
             query.format = args.format;
@@ -119,12 +130,12 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
-            person_a_timezone: { type: "string", description: "IANA timezone name for Person A, e.g. 'America/Denver'." },
+            person_a_datetime: { type: "string", description: DATETIME_DESC },
+            person_a_timezone: timezoneProperty("Person A's birth location", "America/Denver"),
             person_a_latitude: { type: "number", description: "Person A birth latitude." },
             person_a_longitude: { type: "number", description: "Person A birth longitude." },
-            person_b_datetime: { type: "string", description: "Person B birth datetime (ISO 8601)." },
-            person_b_timezone: { type: "string", description: "IANA timezone name for Person B, e.g. 'Europe/London'." },
+            person_b_datetime: { type: "string", description: DATETIME_DESC },
+            person_b_timezone: timezoneProperty("Person B's birth location", "Europe/London"),
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
             format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
@@ -142,6 +153,8 @@ registerTool({
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
             "person_b_datetime", "person_b_latitude", "person_b_longitude",
         ]);
+        assertPersonZoned("person_a", args);
+        assertPersonZoned("person_b", args);
         const query = {};
         if (args.format)
             query.format = args.format;
@@ -163,16 +176,17 @@ registerTool({
         "are aspecting natal positions. Essential for predictive astrology.\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE: Current transits to someone born 1990-04-15:\n" +
-        "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.88, natal_longitude=-87.63",
+        "  natal_datetime='1990-04-15T14:30:00', natal_timezone='America/Chicago',\n" +
+        "  natal_latitude=41.88, natal_longitude=-87.63",
     inputSchema: {
         type: "object",
         properties: {
-            natal_datetime: { type: "string", description: "Natal birth datetime (ISO 8601)." },
-            natal_timezone: { type: "string", description: "IANA timezone name for Natal, e.g. 'America/Denver'." },
+            natal_datetime: { type: "string", description: DATETIME_DESC },
+            natal_timezone: timezoneProperty("the natal birth location", "America/Denver"),
             natal_latitude: { type: "number", description: "Natal birth latitude." },
             natal_longitude: { type: "number", description: "Natal birth longitude." },
-            transit_datetime: { type: "string", description: "Transit moment (ISO 8601). Defaults to now." },
-            transit_timezone: { type: "string", description: "IANA timezone name for Transit, e.g. 'America/Denver'. Only applicable if transit_datetime is provided without offset." },
+            transit_datetime: { type: "string", description: "Transit moment. Defaults to now. " + DATETIME_DESC },
+            transit_timezone: timezoneProperty("the transit moment", "America/Denver"),
             format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude"],
@@ -182,14 +196,19 @@ registerTool({
     annotations: { title: "Transits to Natal Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude"]);
+        assertPersonZoned("natal", args);
         // Backend expects: { subject: {...}, transit_datetime?: {...} }
         // NOT a subjects[] array — natal-transits is a single-subject endpoint
         const body = {
             subject: buildSubject("Natal", args.natal_datetime, args.natal_latitude, args.natal_longitude, args.natal_timezone),
         };
         if (args.transit_datetime) {
-            // transit_datetime is a DateTimeInput on the backend
-            body.transit_datetime = { iso: args.transit_datetime };
+            // transit_datetime is a DateTimeInput on the backend, and unlike the
+            // subject it has no timezone companion — so , which
+            // was declared but never read, is resolved here.
+            body.transit_datetime = {
+                iso: localToUtcIso("transit_datetime", args.transit_datetime, args.transit_timezone, "transit_timezone"),
+            };
         }
         const query = {};
         if (args.format)

package/dist/tools/specialized/electional.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { WINDOW_DATE_DESC } from "../datetime.js";
 // All electional endpoints are GET endpoints with query params.
 // GET /electional/find-window — already existed, keeping it
 registerTool({
@@ -17,15 +18,15 @@ registerTool({
         properties: {
             start_date: {
                 type: "string",
-                description: "ISO 8601 start date or datetime for the search window (e.g., 2026-03-01).",
+                description: "Start of the search window, e.g. '2026-03-01'. " + WINDOW_DATE_DESC,
             },
             end_date: {
                 type: "string",
-                description: "ISO 8601 end date or datetime for the search window.",
+                description: "End of the search window. " + WINDOW_DATE_DESC,
             },
             latitude: {
                 type: "number",
-                description: "Latitude of location in decimal degrees (positive = North).",
+                description: "Latitude of location in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -89,15 +90,15 @@ registerTool({
     description: "Analyze the astrological quality of a specific moment: planet positions, aspects, " +
         "void of course status, lunar phase, day ruler, and an overall electional score (0-100). " +
         "Perfect for evaluating whether 'right now' or a specific date/time is good for action.\n\n" +
-        "CREDIT COST: 2 credits per call.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
         "EXAMPLE: Analyze March 21, 2026 at noon:\n" +
-        "  date='2026-03-21T12:00:00'",
+        "  date='2026-03-21T12:00:00Z'",
     inputSchema: {
         type: "object",
         properties: {
             date: {
                 type: "string",
-                description: "ISO 8601 datetime to analyze (e.g., '2026-03-21T12:00:00'). Defaults to now.",
+                description: "ISO 8601 datetime to analyze, with a zone (e.g., '2026-03-21T12:00:00Z' or '2026-03-21T08:00:00-04:00'). Defaults to now.",
             },
             format: {
                 type: "string",
@@ -128,8 +129,10 @@ registerTool({
         "Returns exact station times, longitudes, and signs.\n\n" +
         "USE THIS TOOL FOR: 'When does Mercury go retrograde?', 'Is Venus retrograde this year?', " +
         "'What planets station this month?', 'When does Mars go direct?'\n\n" +
+        "❌  NOT FOR: 'Is Mercury retrograde right now?' — that is the state at a single instant, " +
+        "so use ephemeris_retrograde_status (1 credit for one planet, vs 5 here).\n\n" +
         "All required fields have smart defaults (searches the next 90 days from today).\n\n" +
-        "CREDIT COST: 3 credits per call.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
         "EXAMPLE: Mercury and Venus stations in the next 3 months (all defaults):\n" +
         "  (no args required, will auto-scan next 90 days for all inner planets)\n\n" +
         "EXAMPLE: Outer planet stations in 2026:\n" +
@@ -198,15 +201,15 @@ registerTool({
     description: "Find all active aspects between planets at a specific moment. Returns aspect type, " +
         "orb, quality score, and whether it's applying or separating. Great for checking " +
         "the 'weather' of a given day.\n\n" +
-        "CREDIT COST: 2 credits per call.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
         "EXAMPLE: What aspects are active on March 21, 2026?\n" +
-        "  date='2026-03-21T12:00:00'",
+        "  date='2026-03-21T12:00:00Z'",
     inputSchema: {
         type: "object",
         properties: {
             date: {
                 type: "string",
-                description: "ISO 8601 datetime to check. Defaults to now.",
+                description: "Datetime to check. Defaults to now. " + WINDOW_DATE_DESC,
             },
             max_orb: {
                 type: "number",

package/dist/tools/specialized/ephemeris_core.js

@@ -1,14 +1,17 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
 // POST /ephemeris/planet-position — OE-016
 registerTool({
     name: "ephemeris_planet_position",
     description: "Get the precise ecliptic longitude, latitude, distance, speed, and retrograde status " +
         "for a single planet/body at a given date and time. " +
         "Planet IDs: 0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, " +
-        "7=Uranus, 8=Neptune, 9=Pluto, 10=North Node, 11=South Node, 12=Lilith, " +
-        "15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta.\n\n" +
+        "7=Uranus, 8=Neptune, 9=Pluto, 10=North Node (Mean), 11=North Node (True), " +
+        "12=Lilith (Mean), 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta.\n\n" +
+        "SOUTH NODE: there is no South Node id. The South Node is always exactly " +
+        "opposite the North Node — request id 10 or 11 and add 180° (mod 360).\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: Where is Mars on 2026-03-20 at noon UTC?\n" +
         "  planet_id=4, datetime='2026-03-20T12:00:00Z'",
@@ -17,12 +20,13 @@ registerTool({
         properties: {
             planet_id: {
                 type: "integer",
-                description: "Planet/body ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 10=MeanNode, 11=TrueNode, 12=Lilith, 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta).",
+                description: "Planet/body ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 10=North Node (Mean), 11=North Node (True), 12=Lilith (Mean), 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta). There is no South Node id — take the North Node and add 180°.",
             },
             datetime: {
                 type: "string",
-                description: "ISO 8601 date/time in UTC or with offset (e.g. '2026-03-20T12:00:00Z' or '2026-03-20T12:00:00-05:00').",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
                 description: "Observer latitude for topocentric position (optional). Omit for geocentric.",
@@ -41,7 +45,7 @@ registerTool({
         validateRequired(args, ["planet_id", "datetime"]);
         const body = {
             planet_id: args.planet_id,
-            date_time: { iso: args.datetime },
+            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
         };
         if (args.latitude != null)
             body.latitude = args.latitude;
@@ -64,11 +68,12 @@ registerTool({
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 date/time in UTC or with offset (e.g. '2026-03-20T12:00:00Z').",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
-                description: "Observer latitude in decimal degrees.",
+                description: "Observer latitude in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -88,7 +93,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         const body = {
-            date_time: { iso: args.datetime },
+            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
             latitude: args.latitude,
             longitude: args.longitude,
         };