@openephemeris/mcp-server 3.23.1 → 4.0.0

package/dist/tools/specialized/hd_cycles.js

@@ -1,16 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-/**
- * Ensure a datetime string has a timezone offset for Go's time.Time parsing.
- */
-function ensureTimezone(dt) {
-    if (!dt)
-        return dt;
-    if (/[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt) || /[+-]\d{4}$/.test(dt))
-        return dt;
-    return dt + "Z";
-}
+import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
 registerTool({
     name: "hd_planetary_return",
     description: "Calculate a Human Design planetary return chart — full HD chart " +
@@ -35,8 +26,9 @@ registerTool({
             },
             datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime in UTC, e.g. '1990-04-15T19:30:00Z'.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             return_year: {
                 type: "integer",
                 description: "Year to find the return near (e.g. 2020 for a Saturn return at ~age 29).",
@@ -57,7 +49,7 @@ registerTool({
         return await getActiveClient().request("POST", "/human-design/cycles/return", {
             data: {
                 planet: args.planet,
-                birth_datetime_utc: ensureTimezone(args.datetime),
+                birth_datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
                 return_year: args.return_year,
                 format: args.format,
                 include_chiron: args.include_chiron,
@@ -87,8 +79,9 @@ registerTool({
             },
             datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime in UTC, e.g. '1983-07-15T12:00:00Z'.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             target_year: {
                 type: "integer",
                 description: "Year to search for the opposition near.",
@@ -109,7 +102,7 @@ registerTool({
         return await getActiveClient().request("POST", "/human-design/cycles/opposition", {
             data: {
                 planet: args.planet,
-                birth_datetime_utc: ensureTimezone(args.datetime),
+                birth_datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
                 target_year: args.target_year,
                 format: args.format,
                 include_chiron: args.include_chiron,

package/dist/tools/specialized/hd_group.js

@@ -1,25 +1,31 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, localToUtcIso, timezoneProperty } from "../datetime.js";
 // POST /human-design/composite — OE-027
 registerTool({
     name: "human_design_composite",
     description: "Calculate a Human Design composite chart for two people. Merges both bodygraphs " +
         "to show shared channels, authority dynamics, and relationship type.\n\n" +
         "CREDIT COST: 4 credits per call.\n\n" +
-        "EXAMPLE:\n" +
-        "  person_a_datetime='1990-04-15T14:30:00Z', person_b_datetime='1988-09-22T08:15:00Z'",
+        "EXAMPLE (local times + zones):\n" +
+        "  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',\n" +
+        "  person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles'\n" +
+        "EXAMPLE (already in UTC):\n" +
+        "  person_a_datetime='1990-04-15T19:30:00Z', person_b_datetime='1988-09-22T15:15:00Z'",
     inputSchema: {
         type: "object",
         properties: {
             person_a_datetime: {
                 type: "string",
-                description: "Person A birth datetime as ISO 8601 UTC (e.g. '1990-04-15T14:30:00Z').",
+                description: DATETIME_DESC,
             },
+            person_a_timezone: timezoneProperty("Person A's birth location"),
             person_b_datetime: {
                 type: "string",
-                description: "Person B birth datetime as ISO 8601 UTC.",
+                description: DATETIME_DESC,
             },
+            person_b_timezone: timezoneProperty("Person B's birth location", "America/Los_Angeles"),
             format: {
                 type: "string",
                 enum: ["json", "llm"],
@@ -35,10 +41,10 @@ registerTool({
         validateRequired(args, ["person_a_datetime", "person_b_datetime"]);
         const body = {
             subject_1: {
-                birth_datetime_utc: args.person_a_datetime,
+                birth_datetime_utc: localToUtcIso("person_a_datetime", args.person_a_datetime, args.person_a_timezone, "person_a_timezone"),
             },
             subject_2: {
-                birth_datetime_utc: args.person_b_datetime,
+                birth_datetime_utc: localToUtcIso("person_b_datetime", args.person_b_datetime, args.person_b_timezone, "person_b_timezone"),
             },
         };
         if (args.format)
@@ -52,12 +58,12 @@ registerTool({
     description: "Calculate a Human Design Penta (group) chart for 3-5 people. Shows functional " +
         "attributes, leadership dynamics, channels, redundancies, and a group stability score.\n\n" +
         "CREDIT COST: 6 credits per call.\n\n" +
-        "EXAMPLE (3 people):\n" +
+        "EXAMPLE (3 people — each datetime states its zone):\n" +
         "  group_name='Team Alpha',\n" +
         "  members=[\n" +
-        "    {id: 'alice', name: 'Alice', datetime: '1990-04-15T14:30:00Z'},\n" +
-        "    {id: 'bob',   name: 'Bob',   datetime: '1988-09-22T08:15:00Z'},\n" +
-        "    {id: 'carol', name: 'Carol', datetime: '1995-01-10T11:00:00Z'}\n" +
+        "    {id: 'alice', name: 'Alice', datetime: '1990-04-15T14:30:00', timezone: 'America/Chicago'},\n" +
+        "    {id: 'bob',   name: 'Bob',   datetime: '1988-09-22T15:15:00Z'},\n" +
+        "    {id: 'carol', name: 'Carol', datetime: '1995-01-10T11:00:00+00:00'}\n" +
         "  ]",
     inputSchema: {
         type: "object",
@@ -73,7 +79,8 @@ registerTool({
                     properties: {
                         id: { type: "string", description: "Unique member ID." },
                         name: { type: "string", description: "Member's name." },
-                        datetime: { type: "string", description: "Birth datetime as ISO 8601 UTC." },
+                        datetime: { type: "string", description: DATETIME_DESC },
+                        timezone: timezoneProperty("this member's birth location"),
                     },
                     required: ["id", "name", "datetime"],
                 },
@@ -94,11 +101,11 @@ registerTool({
     annotations: { title: "HD Penta Group Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["group_name", "members"]);
-        const members = args.members.map((m) => ({
+        const members = args.members.map((m, i) => ({
             id: m.id,
             name: m.name,
             birth_data: {
-                birth_datetime_utc: m.datetime,
+                birth_datetime_utc: localToUtcIso(`members[${i}].datetime`, m.datetime, m.timezone, `members[${i}].timezone`),
             },
         }));
         const body = {

package/dist/tools/specialized/human_design.js

@@ -1,18 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
-/**
- * Ensure a datetime string has a timezone offset for Go's time.Time parsing.
- * Go's encoding/json only accepts RFC 3339 (must have Z or +HH:MM offset).
- */
-function ensureTimezone(dt) {
-    if (!dt)
-        return dt;
-    // Already has timezone indicator
-    if (/[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt) || /[+-]\d{4}$/.test(dt))
-        return dt;
-    return dt + "Z";
-}
+import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
 registerTool({
     name: "human_design_chart",
     description: "Calculate a full Human Design I Ching hexagram chart from birth data. Returns the person's Type " +
@@ -23,19 +12,24 @@ registerTool({
         "CREDIT COST: 2 credits per call.\n\n" +
         "Human Design uses two calculation moments: the birth time (Personality) and ~88° of Sun motion " +
         "before birth (~3 months prior, the Design calculation). The API handles this automatically.\n\n" +
-        "IMPORTANT: The datetime should be in UTC. If you have local birth time, convert to UTC first.\n\n" +
-        "EXAMPLE: Get the Human Design chart for someone born April 15, 1990 at 7:30 PM UTC:\n" +
+        "The datetime must state its zone — pass an offset/'Z', or pass local time plus timezone. " +
+        "A zone-less datetime is rejected rather than assumed to be UTC: Human Design is minute-sensitive, " +
+        "and an hour of error changes the Profile and the Design Sun line.\n\n" +
+        "EXAMPLE (local birth time + zone): someone born 15 April 1990 at 14:30 in Chicago:\n" +
+        "  datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298\n" +
+        "EXAMPLE (already in UTC):\n" +
         "  datetime='1990-04-15T19:30:00Z', latitude=41.8781, longitude=-87.6298",
     inputSchema: {
         type: "object",
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime in UTC, e.g. '1990-04-15T19:30:00Z'. Must include 'Z' or timezone offset.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
-                description: "Latitude of birth location in decimal degrees (positive = North).",
+                description: "Latitude of birth location in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -71,7 +65,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         const body = {
-            birth_datetime_utc: ensureTimezone(args.datetime),
+            birth_datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
         };
         if (args.latitude != null)
             body.latitude = args.latitude;

package/dist/tools/specialized/moon.js

@@ -1,6 +1,7 @@
 import { registerTool, validateCoordinates } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
 registerTool({
     name: "ephemeris_moon_phase",
     description: "Get the Moon's current phase angle, illumination, and void-of-course status AT a specific " +
@@ -21,8 +22,11 @@ registerTool({
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 datetime to query. If omitted, returns the current live moon phase (UTC now).",
+                description: "ISO 8601 datetime to query, stating its zone ('2026-03-20T12:00:00Z' or " +
+                    "'2026-03-20T08:00:00-04:00'), or a local time together with `timezone`. " +
+                    "If omitted, returns the current live moon phase (UTC now).",
             },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
                 description: "Observer latitude (optional, used for local void-of-course calculations).",
@@ -42,7 +46,9 @@ registerTool({
         const params = {};
         // Backend requires datetime even though the schema marks it optional.
         // Default to current UTC time when caller omits it.
-        params.datetime = args.datetime ?? new Date().toISOString();
+        params.datetime = args.datetime
+            ? localToUtcIso("datetime", args.datetime, args.timezone)
+            : new Date().toISOString();
         if (args.latitude != null)
             params.latitude = args.latitude;
         if (args.longitude != null)

package/dist/tools/specialized/natal.js

@@ -1,8 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON } 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";
 /** Map human-readable house system names to standard single-letter codes */
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
@@ -17,8 +16,9 @@ registerTool({
         "essential dignities, retrograde status, house system data, and major aspect grid. Asteroids are automatically included. " +
         "Returns raw JSON. For a user-facing visual chart, use explore_natal_chart instead.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: Calculate the natal chart for someone born April 15, 1990 at 2:30 PM 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 — pass the local time and name the zone:\n" +
+        "  datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298\n" +
+        "Equivalently, put the zone on the datetime: datetime='1990-04-15T14:30:00-05:00' (or the UTC instant '1990-04-15T19:30:00Z').",
     inputSchema: {
         type: "object",
         properties: {
@@ -26,13 +26,10 @@ 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).",
+                description: "Geographic latitude of birth location in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -79,6 +76,7 @@ registerTool({
     annotations: { title: "Natal Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
+        assertZonedDatetime("datetime", args.datetime, args.timezone);
         const body = {
             subject: {
                 name: "MCP Request",

package/dist/tools/specialized/progressed.js

@@ -1,27 +1,27 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, WINDOW_DATE_DESC, assertZonedDatetime } from "../datetime.js";
 registerTool({
     name: "ephemeris_progressed_chart",
     description: "Calculate a Secondary Progressed (or Solar Arc / Tertiary) chart. " +
         "Advances the natal chart symbolically — 1 day = 1 year (secondary), or using solar arc motion. " +
         "Returns progressed planet positions, house cusps, aspects, and retrograde status.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: Secondary progressions for someone born 1985-06-21, progressed to 2026-01-01:\n" +
-        "  birth_datetime='1985-06-21T14:00:00', birth_latitude=51.5, birth_longitude=-0.12,\n" +
-        "  target_datetime='2026-01-01', method='secondary'",
+        "EXAMPLE: Secondary progressions for someone born 1985-06-21 at 2:00 PM in London, progressed to 2026-01-01:\n" +
+        "  birth_datetime='1985-06-21T14:00:00', timezone='Europe/London',\n" +
+        "  birth_latitude=51.5, birth_longitude=-0.12, target_datetime='2026-01-01', method='secondary'",
     inputSchema: {
         type: "object",
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 natal birth date/time. MUST include a UTC offset (or 'Z'), " +
-                    "e.g. '1990-05-15T14:30:00-05:00'. A naive datetime (no offset) is " +
-                    "interpreted as UTC and will shift the progressed positions.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             birth_latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees.",
+                description: "Birth latitude in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             birth_longitude: {
                 type: "number",
@@ -29,7 +29,7 @@ registerTool({
             },
             target_datetime: {
                 type: "string",
-                description: "Target date to progress the chart to (ISO 8601).",
+                description: "Date to progress the chart to. " + WINDOW_DATE_DESC,
             },
             method: {
                 type: "string",
@@ -63,6 +63,8 @@ registerTool({
     annotations: { title: "Progressed Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude", "target_datetime"]);
+        assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);
+        assertZonedDatetime("target_datetime", args.target_datetime);
         const body = {
             subject: {
                 name: "Progressed Subject",
@@ -70,6 +72,8 @@ registerTool({
                 birth_location: {
                     latitude: { decimal: args.birth_latitude },
                     longitude: { decimal: args.birth_longitude },
+                    // The server resolves the IANA zone, so historical DST stays correct.
+                    ...(args.timezone ? { timezone: { iana_name: args.timezone } } : {}),
                 },
             },
             target_datetime: { iso: args.target_datetime },

package/dist/tools/specialized/relocation.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 { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime } from "../datetime.js";
 registerTool({
     name: "ephemeris_relocation",
     description: "Calculate a relocation chart — the same natal planetary positions re-cast for a different " +
@@ -8,18 +9,20 @@ registerTool({
         "and angles, without changing the planetary longitudes in the chart.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: How does moving from Chicago to London change someone's chart?\n" +
-        "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.8781, natal_longitude=-87.6298,\n" +
+        "  natal_datetime='1990-04-15T14:30:00', timezone='America/Chicago',\n" +
+        "  natal_latitude=41.8781, natal_longitude=-87.6298,\n" +
         "  relocation_latitude=51.5074, relocation_longitude=-0.1278",
     inputSchema: {
         type: "object",
         properties: {
             natal_datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime (local time at birth location).",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             natal_latitude: {
                 type: "number",
-                description: "Latitude of birth location in decimal degrees.",
+                description: "Latitude of birth location in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             natal_longitude: {
                 type: "number",
@@ -51,6 +54,7 @@ registerTool({
     annotations: { title: "Relocation Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "relocation_latitude", "relocation_longitude"]);
+        assertZonedDatetime("natal_datetime", args.natal_datetime, args.timezone);
         const body = {
             natal: {
                 subject: {
@@ -59,6 +63,8 @@ registerTool({
                     birth_location: {
                         latitude: { decimal: args.natal_latitude },
                         longitude: { decimal: args.natal_longitude },
+                        // The server resolves the IANA zone, so historical DST stays correct.
+                        ...(args.timezone ? { timezone: { iana_name: args.timezone } } : {}),
                     },
                 },
             },

package/dist/tools/specialized/returns.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
-import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
+import { OUTPUT_SCHEMA_IMAGE_AND_JSON, OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, localToUtcIso } from "../datetime.js";
 // POST /predictive/returns/solar
 registerTool({
     name: "ephemeris_solar_return",
@@ -18,8 +19,9 @@ registerTool({
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 birth date/time. Include offset or Z (e.g. '1985-06-21T14:00:00-05:00').",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             target_datetime: {
                 type: "string",
                 description: "Date/time near which to find the Solar Return (ISO 8601 with offset or Z). " +
@@ -64,11 +66,13 @@ registerTool({
     annotations: { title: "Solar Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime"]);
+        assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);
+        assertZonedDatetime("target_datetime", args.target_datetime, args.timezone);
         // Default target to current year if not provided
         const targetDt = args.target_datetime ?? new Date().toISOString();
         const body = {
-            birth_datetime: { iso: args.birth_datetime },
-            target_datetime: { iso: targetDt },
+            birth_datetime: { iso: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone) },
+            target_datetime: { iso: localToUtcIso("target_datetime", targetDt, args.timezone) },
         };
         if (args.birth_latitude != null && args.birth_longitude != null) {
             body.location = {
@@ -110,8 +114,9 @@ registerTool({
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 birth date/time. Include offset or Z.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             target_datetime: {
                 type: "string",
                 description: "Date/time near which to find the Lunar Return (ISO 8601 with offset or Z). " +
@@ -129,14 +134,17 @@ registerTool({
         required: ["birth_datetime"],
         additionalProperties: false,
     },
-    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    // JSON only: this tool never sets include_visual, so it cannot return an image.
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Lunar Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime"]);
+        assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);
+        assertZonedDatetime("target_datetime", args.target_datetime, args.timezone);
         const targetDt = args.target_datetime ?? new Date().toISOString();
         const body = {
-            birth_datetime: { iso: args.birth_datetime },
-            target_datetime: { iso: targetDt },
+            birth_datetime: { iso: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone) },
+            target_datetime: { iso: localToUtcIso("target_datetime", targetDt, args.timezone) },
         };
         if (args.birth_latitude != null && args.birth_longitude != null) {
             body.location = {
@@ -167,15 +175,16 @@ registerTool({
             },
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 birth date/time. MUST include offset or Z.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             target_datetime: {
                 type: "string",
                 description: "Date/time near which to find the return (ISO 8601). MUST include offset or Z. Required.",
             },
             birth_latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees. Required to get a full return chart (house cusps, angles).",
+                description: "Birth latitude in decimal degrees. Required to get a full return chart (house cusps, angles). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             birth_longitude: {
                 type: "number",
@@ -185,10 +194,13 @@ registerTool({
         required: ["body", "birth_datetime", "target_datetime"],
         additionalProperties: false,
     },
-    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    // JSON only: this tool never sets include_visual, so it cannot return an image.
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Planetary Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["body", "birth_datetime", "target_datetime"]);
+        assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);
+        assertZonedDatetime("target_datetime", args.target_datetime, args.timezone);
         const requestBody = {
             body: args.body,
             birth_datetime: { iso: args.birth_datetime },

package/dist/tools/specialized/synastry.js

@@ -1,22 +1,27 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, assertZonedDatetime, timezoneProperty } from "../datetime.js";
 registerTool({
     name: "ephemeris_synastry",
     description: "Calculate a synastry chart comparing two people's natal charts. Returns inter-aspects " +
         "(planetary connections between the two charts), composite points, and relationship indicators. " +
         "Use this for compatibility analysis, relationship timing, or partnership insights.\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
-        "EXAMPLE: Compare two people's charts:\n" +
-        "  person_a_datetime='1990-04-15T14:30:00', person_a_latitude=41.8781, person_a_longitude=-87.6298,\n" +
-        "  person_b_datetime='1988-09-22T08:15:00', person_b_latitude=34.0522, person_b_longitude=-118.2437",
+        "EXAMPLE: Compare two people's charts (local birth times, each with its zone):\n" +
+        "  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',\n" +
+        "  person_a_latitude=41.8781, person_a_longitude=-87.6298,\n" +
+        "  person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles',\n" +
+        "  person_b_latitude=34.0522, person_b_longitude=-118.2437",
     inputSchema: {
         type: "object",
         properties: {
-            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
-            person_a_latitude: { type: "number", description: "Person A birth latitude." },
+            person_a_datetime: { type: "string", description: DATETIME_DESC },
+            person_a_timezone: timezoneProperty("Person A's birth location"),
+            person_a_latitude: { type: "number", description: "Person A birth latitude. Resolve from a place name with location_search; never recall coordinates from memory." },
             person_a_longitude: { type: "number", description: "Person A birth longitude." },
-            person_b_datetime: { type: "string", description: "Person B birth datetime (ISO 8601)." },
+            person_b_datetime: { type: "string", description: DATETIME_DESC },
+            person_b_timezone: timezoneProperty("Person B's birth location", "America/Los_Angeles"),
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
             house_system: {
@@ -58,6 +63,8 @@ registerTool({
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
             "person_b_datetime", "person_b_latitude", "person_b_longitude",
         ]);
+        assertZonedDatetime("person_a_datetime", args.person_a_datetime, args.person_a_timezone, "person_a_timezone");
+        assertZonedDatetime("person_b_datetime", args.person_b_datetime, args.person_b_timezone, "person_b_timezone");
         const body = {
             subject_a: {
                 name: "Person A",
@@ -65,6 +72,9 @@ registerTool({
                 birth_location: {
                     latitude: { decimal: args.person_a_latitude },
                     longitude: { decimal: args.person_a_longitude },
+                    // The server resolves the zone; sending the IANA name keeps
+                    // historical DST correct instead of resolving it here.
+                    ...(args.person_a_timezone ? { timezone: { iana_name: args.person_a_timezone } } : {}),
                 },
             },
             subject_b: {
@@ -73,6 +83,7 @@ registerTool({
                 birth_location: {
                     latitude: { decimal: args.person_b_latitude },
                     longitude: { decimal: args.person_b_longitude },
+                    ...(args.person_b_timezone ? { timezone: { iana_name: args.person_b_timezone } } : {}),
                 },
             },
         };

package/dist/tools/specialized/transits.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 { DATETIME_DESC, WINDOW_DATE_DESC, timezoneProperty } from "../datetime.js";
 registerTool({
     name: "ephemeris_transits",
     description: "Search for astrological transit events affecting a natal chart over a date range. " +
@@ -22,11 +23,12 @@ registerTool({
         properties: {
             natal_datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime for the natal chart.",
+                description: DATETIME_DESC,
             },
+            natal_timezone: timezoneProperty("the natal birth location"),
             natal_latitude: {
                 type: "number",
-                description: "Latitude of birth location in decimal degrees.",
+                description: "Latitude of birth location in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             natal_longitude: {
                 type: "number",
@@ -34,11 +36,11 @@ registerTool({
             },
             start_date: {
                 type: "string",
-                description: "Start of the transit search window, ISO 8601 date or datetime (e.g. '2026-01-01').",
+                description: "Start of the transit search window. " + WINDOW_DATE_DESC,
             },
             end_date: {
                 type: "string",
-                description: "End of the transit search window, ISO 8601 date or datetime (e.g. '2026-06-30').",
+                description: "End of the transit search window. " + WINDOW_DATE_DESC,
             },
             transiting_planets: {
                 type: "array",
@@ -72,7 +74,9 @@ registerTool({
                 birth_datetime: { iso: args.natal_datetime },
                 birth_location: {
                     latitude: { decimal: args.natal_latitude },
-                    longitude: { decimal: args.natal_longitude }
+                    longitude: { decimal: args.natal_longitude },
+                    // The server resolves the IANA zone, so historical DST stays correct.
+                    ...(args.natal_timezone ? { timezone: { iana_name: args.natal_timezone } } : {}),
                 },
             },
         };

package/dist/tools/specialized/vedic.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired, validateCoordinates } 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";
 registerTool({
     name: "vedic_chart",
     description: "Calculate a Vedic (Jyotish) natal chart with sidereal positions. Returns planet placements " +
@@ -15,11 +16,12 @@ registerTool({
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime in UTC, e.g. '1990-01-15T08:30:00Z'. Include 'Z' or timezone offset.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees (north positive).",
+                description: "Birth latitude in decimal degrees (north positive). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -40,7 +42,7 @@ registerTool({
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         validateCoordinates(args, "latitude", "longitude");
         const body = {
-            datetime_utc: args.datetime,
+            datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
             latitude: args.latitude,
             longitude: args.longitude,
         };