@openephemeris/mcp-server 4.7.0 → 4.8.1

package/dist/tools/index.d.ts

@@ -57,7 +57,11 @@ export interface ToolDefinition {
  * multi-tenant HTTP server cannot vary it per session, and an unregistered
  * tool becomes uncallable rather than merely hidden.
  */
-export type ToolSurface = "core" | "full";
+export type ToolSurface = "core" | "full" | ToolsetSurface;
+/** A caller-chosen set of traditions, e.g. `?profile=hd,bazi`. */
+export interface ToolsetSurface {
+    readonly toolsets: readonly string[];
+}
 /**
  * The default advertised surface: everyday astrology work, one tool per job.
  *
@@ -80,6 +84,28 @@ export type ToolSurface = "core" | "full";
  * explore_natal_chart are present. Do not remove those four.
  */
 export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * Tool surfaces grouped by tradition, so a caller pays context only for the
+ * work they actually do: `?profile=hd,bazi` on HTTP, `OPENEPHEMERIS_TOOLS=hd`
+ * on stdio. BASE_TOOLSET is always included.
+ *
+ * This is the same *view* filter as `core`/`full` — nothing is unregistered,
+ * every tool stays callable by name — so a toolset is a context-budget choice,
+ * never a capability one.
+ *
+ * Why this exists: the core surface is re-sent on every model pass and sat at
+ * its ceiling with ~0 headroom, and the only levers left were deleting the
+ * disambiguation prose that makes tool selection work. Grouping by tradition
+ * is the structural fix — a Human Design user should not pay for Venus Star
+ * Points on every message.
+ *
+ * Names here are asserted against the registry by a test; a typo fails the
+ * build rather than silently narrowing someone's surface.
+ */
+export declare const TOOLSETS: Readonly<Record<string, readonly string[]>>;
+export declare const TOOLSET_NAMES: readonly string[];
+/** Resolve a toolset selection to the tool names it advertises. */
+export declare function toolsetSelectionNames(names: readonly string[]): Set<string>;
 /**
  * Returns tools that should be exposed to Claude in the ListTools response.
  * Filters out tools that have visibility restricted to the UI (app-only),
@@ -87,8 +113,21 @@ export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
  * "core" — everything outside CORE_TOOL_NAMES.
  */
 export declare function modelVisibleTools(transport?: "stdio" | "http", surface?: ToolSurface): ToolDefinition[];
-/** Parses a caller-supplied surface hint. Anything unrecognised means "core". */
+/**
+ * Parses a caller-supplied surface hint.
+ *
+ *   "full"          -> every model-visible tool
+ *   "hd" | "hd,bazi" -> those traditions plus BASE_TOOLSET
+ *   anything else   -> "core" (the curated default)
+ *
+ * Unknown names in a comma list are ignored rather than rejected: a typo
+ * degrades to a smaller surface, never to an error at `initialize` that would
+ * leave the connector dead. If NO name in the list is recognised, fall back to
+ * "core" so a mistyped profile can't strand a caller on BASE alone.
+ */
 export declare function parseToolSurface(raw: unknown): ToolSurface;
+/** Stable label for logs/analytics — an object surface has no useful toString. */
+export declare function describeSurface(surface: ToolSurface): string;
 export declare const toolRegistry: Record<string, ToolDefinition>;
 export declare function registerTool(tool: ToolDefinition): void;
 export type ToolProfile = "dev" | "legacy";

package/dist/tools/index.js

@@ -12,6 +12,9 @@ export const SERVER_VERSION = (() => {
         return "0.0.0-unknown";
     }
 })();
+function isToolsetSurface(s) {
+    return typeof s === "object" && Array.isArray(s.toolsets);
+}
 /**
  * The default advertised surface: everyday astrology work, one tool per job.
  *
@@ -53,6 +56,13 @@ export const CORE_TOOL_NAMES = new Set([
     "ephemeris_transits",
     "ephemeris_synastry",
     "ephemeris_retrograde_status",
+    // Promoted 2026-08-02 on usage: both were reachable only via profile=full,
+    // yet ephemeris_aspect_check drew 19 calls from 3 users over 90 days (more
+    // than 20 of the tools already in this set) and ephemeris_angles_points drew
+    // 9. People found them while they were hidden; advertising them is cheap
+    // (202 and 227 tokens) and earns its place.
+    "ephemeris_aspect_check",
+    "ephemeris_angles_points",
     "ephemeris_next_eclipse",
     "ephemeris_relocation",
     "ephemeris_progressed_chart",
@@ -60,13 +70,31 @@ export const CORE_TOOL_NAMES = new Set([
     // Traditions
     "human_design_chart",
     "vedic_chart",
-    "chinese_bazi",
     "bazi_annual_pillar",
+    // chinese_bazi demoted 2026-08-02: explore_bazi_chart POSTs the same
+    // /chinese/bazi at the same 1-credit base and keeps every substantive field
+    // (year/month/day/hour pillars + day_master), dropping only the `metadata`
+    // and `success` envelope keys — verified against a live response, not
+    // inferred from the names. It also degrades to a text summary on hosts that
+    // cannot render the iframe, so nothing is lost without an MCP Apps host.
+    // chinese_bazi drew 0 calls in 90 days while advertised; explore_bazi_chart
+    // drew 3. Still registered and callable by name, and still in profile=full.
+    //
+    // NOTE: this reasoning does NOT extend to the sibling pairs. vedic_chart (1
+    // credit) vs explore_vedic_chart (3), and human_design_chart (2 credits, full
+    // response) vs explore_human_design (4 credits, and buildHdModelPayload drops
+    // activations/design/personality/strategy/variables) are not folds — they
+    // would cost users money and data. Verify in the handler before adding to
+    // this list.
     // Timing
     "ephemeris_electional",
     "electional_moment_analysis",
     "electional_station_tracker",
-    "electional_angle_crossings",
+    // electional_angle_crossings demoted 2026-08-02: 715 tokens (the fattest
+    // non-proxy tool in this set) for 0 calls in 90 days, and at 5 credits it is
+    // advanced-practitioner work rather than an everyday ask. Three electional
+    // entry points remain advertised; this one is a profile=full / skill-named
+    // tool now.
     // Astrocartography
     "acg_power_lines",
     "acg_hits",
@@ -83,6 +111,141 @@ export const CORE_TOOL_NAMES = new Set([
     "auth_status",
     "auth_logout",
 ]);
+/**
+ * Tools every session needs regardless of tradition: turning a place name into
+ * coordinates, checking credits, and the allowlist-gated escape hatch. Always
+ * unioned into a toolset selection — a caller who asks for `hd` still has to be
+ * able to resolve a birthplace, or they are back to recalling coordinates from
+ * memory, which is the bug BASE exists to prevent.
+ */
+const BASE_TOOLSET = [
+    "location_search",
+    "timezone_resolve",
+    "account_usage",
+    "dev_read_api",
+    // The write half of the escape hatch. 26 of the 31 allowlisted operations
+    // are POST — BASE without dev_write_api would strand a toolset caller with
+    // only the 5 GET proxies. (Deliberately NOT advertised in `core`, where the
+    // curated typed tools cover the write surface; a toolset selection has no
+    // such coverage, so it needs the proxy whole.)
+    "dev_write_api",
+    "dev_list_allowed",
+    "auth_login",
+    "auth_status",
+    "auth_logout",
+];
+/**
+ * Tool surfaces grouped by tradition, so a caller pays context only for the
+ * work they actually do: `?profile=hd,bazi` on HTTP, `OPENEPHEMERIS_TOOLS=hd`
+ * on stdio. BASE_TOOLSET is always included.
+ *
+ * This is the same *view* filter as `core`/`full` — nothing is unregistered,
+ * every tool stays callable by name — so a toolset is a context-budget choice,
+ * never a capability one.
+ *
+ * Why this exists: the core surface is re-sent on every model pass and sat at
+ * its ceiling with ~0 headroom, and the only levers left were deleting the
+ * disambiguation prose that makes tool selection work. Grouping by tradition
+ * is the structural fix — a Human Design user should not pay for Venus Star
+ * Points on every message.
+ *
+ * Names here are asserted against the registry by a test; a typo fails the
+ * build rather than silently narrowing someone's surface.
+ */
+export const TOOLSETS = {
+    /** Western natal/predictive work — the default tradition. */
+    astrology: [
+        "ephemeris_natal_chart",
+        "explore_natal_chart",
+        "ephemeris_planet_position",
+        "ephemeris_house_cusps",
+        "ephemeris_angles_points",
+        "ephemeris_aspect_check",
+        "ephemeris_transits",
+        "ephemeris_natal_transits",
+        "explore_transit_timeline",
+        "ephemeris_synastry",
+        "explore_bi_wheel",
+        "bi_wheel_synopsis",
+        "ephemeris_retrograde_status",
+        "ephemeris_progressed_chart",
+        "ephemeris_solar_return",
+        "ephemeris_lunar_return",
+        "ephemeris_planetary_return",
+        "ephemeris_relocation",
+        "ephemeris_dignities",
+        "ephemeris_midpoints",
+        "ephemeris_hermetic_lots",
+        "ephemeris_fixed_stars",
+        "ephemeris_composite",
+        "ephemeris_composite_midpoint",
+        "ephemeris_overlay",
+        "ephemeris_chart_wheel",
+        "ephemeris_bi_wheel",
+        "ephemeris_natal_batch",
+    ],
+    /** Lunar phase, void-of-course and eclipse work. */
+    moon: [
+        "ephemeris_moon_phase",
+        "explore_moon_phase",
+        "ephemeris_next_lunar_phase",
+        "ephemeris_next_eclipse",
+    ],
+    /** Human Design. */
+    hd: [
+        "human_design_chart",
+        "explore_human_design",
+        "explore_human_design_transit",
+        "explore_human_design_connection",
+        "human_design_bodygraph",
+        "human_design_composite",
+        "human_design_penta",
+        "hd_opposition",
+        "hd_planetary_return",
+    ],
+    /** Chinese BaZi / Four Pillars. */
+    bazi: [
+        "explore_bazi_chart",
+        "chinese_bazi",
+        "bazi_chart",
+        "bazi_ten_gods",
+        "bazi_element_balance",
+        "bazi_luck_pillars",
+        "bazi_annual_pillar",
+        "bazi_compatibility",
+    ],
+    /** Vedic / Jyotish. */
+    vedic: ["vedic_chart", "explore_vedic_chart"],
+    /** Astrocartography. */
+    acg: ["acg_hits", "acg_power_lines"],
+    /** Electional timing. */
+    electional: [
+        "ephemeris_electional",
+        "electional_moment_analysis",
+        "electional_station_tracker",
+        "electional_angle_crossings",
+        "electional_aspect_search",
+    ],
+    /** Venus Star Point / synodic-cycle work. */
+    venus: [
+        "venus_star_points",
+        "venus_star_points_conjunctions",
+        "venus_phase",
+        "venus_elongations",
+        "venus_stations",
+        "venus_eight_year_star",
+    ],
+};
+export const TOOLSET_NAMES = Object.keys(TOOLSETS);
+/** Resolve a toolset selection to the tool names it advertises. */
+export function toolsetSelectionNames(names) {
+    const out = new Set(BASE_TOOLSET);
+    for (const n of names) {
+        for (const t of TOOLSETS[n] ?? [])
+            out.add(t);
+    }
+    return out;
+}
 /**
  * Returns tools that should be exposed to Claude in the ListTools response.
  * Filters out tools that have visibility restricted to the UI (app-only),
@@ -90,6 +253,9 @@ export const CORE_TOOL_NAMES = new Set([
  * "core" — everything outside CORE_TOOL_NAMES.
  */
 export function modelVisibleTools(transport = "stdio", surface = "full") {
+    const allowed = isToolsetSurface(surface)
+        ? toolsetSelectionNames(surface.toolsets)
+        : null;
     return Object.values(toolRegistry).filter((t) => {
         if (transport === "http" && t.stdioOnly)
             return false;
@@ -97,14 +263,45 @@ export function modelVisibleTools(transport = "stdio", surface = "full") {
         // If visibility is explicitly ["app"] (no "model"), hide from model
         if (vis && !vis.includes("model") && vis.includes("app"))
             return false;
+        if (allowed)
+            return allowed.has(t.name);
         if (surface === "core" && !CORE_TOOL_NAMES.has(t.name))
             return false;
         return true;
     });
 }
-/** Parses a caller-supplied surface hint. Anything unrecognised means "core". */
+/**
+ * Parses a caller-supplied surface hint.
+ *
+ *   "full"          -> every model-visible tool
+ *   "hd" | "hd,bazi" -> those traditions plus BASE_TOOLSET
+ *   anything else   -> "core" (the curated default)
+ *
+ * Unknown names in a comma list are ignored rather than rejected: a typo
+ * degrades to a smaller surface, never to an error at `initialize` that would
+ * leave the connector dead. If NO name in the list is recognised, fall back to
+ * "core" so a mistyped profile can't strand a caller on BASE alone.
+ */
 export function parseToolSurface(raw) {
-    return typeof raw === "string" && raw.toLowerCase() === "full" ? "full" : "core";
+    if (typeof raw !== "string")
+        return "core";
+    const value = raw.trim().toLowerCase();
+    if (value === "full")
+        return "full";
+    if (value === "" || value === "core")
+        return "core";
+    const requested = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const known = requested.filter((n) => Object.hasOwn(TOOLSETS, n));
+    if (known.length === 0)
+        return "core";
+    return { toolsets: known };
+}
+/** Stable label for logs/analytics — an object surface has no useful toString. */
+export function describeSurface(surface) {
+    return isToolsetSurface(surface) ? surface.toolsets.join("+") : surface;
 }
 export const toolRegistry = {};
 export function registerTool(tool) {

package/dist/tools/specialized/account.js

@@ -27,7 +27,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Account Usage", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Account Usage", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const params = {};
         if (args?.month)
@@ -39,7 +39,11 @@ registerTool({
         }
         catch (error) {
             if (error instanceof BackendError && error.status === 401) {
+                // A real auth failure must carry isError — a success-shaped response
+                // teaches the model the call worked and it stops trying to fix auth.
+                // The guidance text is kept so hosts still show the user a way forward.
                 return {
+                    isError: true,
                     content: [{
                             type: "text",
                             text: `**Not signed in.** To check usage, connect an OpenEphemeris account first.\n\n` +

package/dist/tools/specialized/acg.js

@@ -60,7 +60,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Astrocartography Lines", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Astrocartography Lines", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude"]);
         const body = {
@@ -157,7 +157,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Astrocartography Location Hits", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Astrocartography Location Hits", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude", "query_latitude", "query_longitude"]);
         const body = {

package/dist/tools/specialized/bazi.js

@@ -158,7 +158,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
-    annotations: { title: "BaZi Four Pillars Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "BaZi Four Pillars Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const body = { ...parseBaziArgs(args) };
         applyVisualConfig(body, args);
@@ -195,7 +195,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
-    annotations: { title: "BaZi Ten Gods", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "BaZi Ten Gods", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const body = { ...parseBaziArgs(args) };
         applyVisualConfig(body, args);
@@ -230,7 +230,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
-    annotations: { title: "BaZi Element Balance", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "BaZi Element Balance", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const body = { ...parseBaziArgs(args) };
         applyVisualConfig(body, args);
@@ -273,7 +273,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
-    annotations: { title: "BaZi Luck Pillars", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "BaZi Luck Pillars", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         if (!args.gender) {
             throw new Error("gender is required for luck pillar calculation. " +
@@ -316,7 +316,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
-    annotations: { title: "BaZi Annual Pillar", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "BaZi Annual Pillar", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         if (!args.year) {
             throw new Error("year is required. Provide a Gregorian year (1–9999), e.g. year=2025.");
@@ -385,7 +385,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
-    annotations: { title: "BaZi Compatibility", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "BaZi Compatibility", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const chartAComponents = parseBaziArgs({
             year: args.chart_a_year,
@@ -447,7 +447,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
-    annotations: { title: "BaZi Chart (Visual)", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "BaZi Chart (Visual)", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const { year, month, day, hour } = parseBaziArgs(args);
         const body = {

package/dist/tools/specialized/bi_wheel.js

@@ -40,7 +40,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE,
-    annotations: { title: "Bi-Wheel Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Bi-Wheel Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     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");

package/dist/tools/specialized/chart_wheel.js

@@ -45,7 +45,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE,
-    annotations: { title: "Chart Wheel SVG", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Chart Wheel SVG", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         assertZonedDatetime("datetime", args.datetime, args.timezone);

package/dist/tools/specialized/comparative.js

@@ -51,7 +51,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Davison Relationship Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Davison Relationship Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -99,7 +99,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Midpoint Composite Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Midpoint Composite Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -147,7 +147,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Synastry House Overlay", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Synastry House Overlay", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -193,7 +193,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Transits to Natal Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Transits to Natal Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude"]);
         assertPersonZoned("natal", args);

package/dist/tools/specialized/eclipse.js

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

package/dist/tools/specialized/electional.js

@@ -59,7 +59,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Electional Timing Window", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Electional Timing Window", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["start_date", "end_date", "latitude", "longitude"]);
         const query = {
@@ -110,7 +110,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Moment Quality Analysis", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Moment Quality Analysis", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const query = {};
         if (args.date)
@@ -164,7 +164,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Retrograde Station Tracker", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Retrograde Station Tracker", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const query = {};
         // Map human-readable planet names to IDs if needed
@@ -224,7 +224,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Active Aspects Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Active Aspects Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const query = {};
         if (args.date)
@@ -302,7 +302,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Angle Crossing Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Angle Crossing Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["latitude", "longitude"]);
         const query = {

package/dist/tools/specialized/ephemeris_core.js

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

package/dist/tools/specialized/ephemeris_extended.js

@@ -56,7 +56,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Natal Batch Charts", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Natal Batch Charts", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["subjects"]);
         args.subjects.forEach((s, i) => assertZonedDatetime(`subjects[${i}].datetime`, s?.datetime, s?.timezone, `subjects[${i}].timezone`));
@@ -82,7 +82,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Essential Dignities", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Essential Dignities", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         return await getActiveClient().post("/ephemeris/dignities", {
@@ -122,7 +122,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Retrograde Status", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Retrograde Status", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         const client = getActiveClient();
@@ -173,7 +173,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Midpoints", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Midpoints", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/midpoints", {
@@ -219,7 +219,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Fixed Stars", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Fixed Stars", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         // A lone latitude would silently drop the angles from the scan, which is
@@ -262,7 +262,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Hermetic Lots", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Hermetic Lots", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/hermetic-lots", {
@@ -290,7 +290,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Angles & Points", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Angles & Points", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/angles-points", {
@@ -319,7 +319,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Aspect Check", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Aspect Check", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["longitude_1", "longitude_2"]);
         // Backend field names are longitude1 / longitude2 (no underscore)

package/dist/tools/specialized/hd_bodygraph.js

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

package/dist/tools/specialized/hd_cycles.js

@@ -58,7 +58,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "HD Planetary Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "HD Planetary Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["planet", "datetime", "return_year"]);
         return await getActiveClient().request("POST", "/human-design/cycles/return", {
@@ -112,7 +112,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "HD Opposition Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "HD Opposition Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["planet", "datetime", "target_year"]);
         return await getActiveClient().request("POST", "/human-design/cycles/opposition", {