@openephemeris/mcp-server 4.8.0 → 4.8.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.8.1] — 2026-08-02
+
+### Fixed
+- Every tool now declares all four MCP annotation hints explicitly
+  (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
+  Notably `dev_write_api` is `destructiveHint: false` — every allowlisted
+  write is stateless chart computation — so strict clients no longer gate it
+  behind a confirmation, and `openWorldHint` is uniformly `false` (the server
+  reaches only the fixed OpenEphemeris API).
+- `account_usage` reports a real authentication failure as a tool error
+  (`isError: true`) instead of a success-shaped message.
+
 ## [4.8.0] — 2026-08-02
 
 ### Added

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

@@ -204,7 +204,7 @@ registerTool({
         required: ["year", "month", "day"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate BaZi Chart", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate BaZi Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BAZI_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const components = parseBaziArgs(args);

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

@@ -588,7 +588,7 @@ registerTool({
         required: ["mode", "person1_datetime", "person1_latitude", "person1_longitude", "person2_datetime"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Bi-Wheel", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Bi-Wheel", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();
@@ -644,7 +644,7 @@ registerTool({
         required: ["planet1", "planet2", "aspect_type"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Cross-Aspect Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Cross-Aspect Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const p1 = capitalize(String(args.planet1));
@@ -683,7 +683,7 @@ registerTool({
         required: ["planet", "wheel", "longitude"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Bi-Wheel Planet Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Bi-Wheel Planet Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const planet = String(args.planet);
@@ -884,7 +884,7 @@ registerTool({
         required: ["house_number"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Bi-Wheel House Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Bi-Wheel House Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const num = Number(args.house_number);
@@ -944,7 +944,7 @@ registerTool({
         required: ["mode"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Bi-Wheel Synopsis", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Bi-Wheel Synopsis", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app", "model"] } },
     handler: async (args) => {
         const mode = args.mode ?? "synastry";

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

@@ -471,7 +471,7 @@ registerTool({
         required: ["datetime"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Bodygraph", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Bodygraph", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();
@@ -536,7 +536,7 @@ registerTool({
         required: ["center", "defined"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Center Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Center Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const center = String(args.center);
@@ -594,7 +594,7 @@ registerTool({
         required: ["gate"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Gate Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Gate Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const gate = Number(args.gate);
@@ -649,7 +649,7 @@ registerTool({
         required: ["channel"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Channel Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const channelStr = String(args.channel);
@@ -751,7 +751,7 @@ registerTool({
         required: ["channel"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Connection Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Connection Channel Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const channelStr = String(args.channel ?? "");
@@ -807,7 +807,7 @@ registerTool({
         required: ["channel"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Transit Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Transit Channel Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const channelStr = String(args.channel ?? "");
@@ -1135,7 +1135,7 @@ registerTool({
         required: ["planet", "column"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Planet Sidebar Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Planet Sidebar Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const planet = String(args.planet);
@@ -1204,7 +1204,7 @@ registerTool({
         required: ["variable", "direction"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Variable Arrow Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Variable Arrow Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const variable = String(args.variable).toLowerCase();

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

@@ -259,7 +259,7 @@ registerTool({
         required: ["planet", "longitude"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Planet Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Planet Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const planet = String(args.planet);
@@ -294,7 +294,7 @@ registerTool({
         required: ["house_number"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "House Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "House Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const num = Number(args.house_number);
@@ -330,7 +330,7 @@ registerTool({
         required: ["planet1", "planet2"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Aspect Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Aspect Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const p1 = capitalize(String(args.planet1));
@@ -379,7 +379,7 @@ registerTool({
         required: ["datetime", "latitude", "longitude", "house_system"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Chart", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();

package/dist/tools/apps/location-tools.js

@@ -131,7 +131,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Location Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Location Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     // Model-visible as well as app-visible: without this the model had no
     // geocoding tool and every prompt had to route through
     // `dev_read_api /location/autocomplete` instead.
@@ -235,7 +235,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Timezone Resolve", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Timezone Resolve", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: {
         ui: {
             visibility: ["model", "app"],

package/dist/tools/apps/moon-phase-app.js

@@ -295,7 +295,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Moon Phase", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Moon Phase", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: MOON_PHASE_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const { summary, uiPayload } = await computeMoonData(args);

package/dist/tools/apps/vedic-chart-app.js

@@ -240,7 +240,7 @@ registerTool({
         required: ["datetime"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Vedic Chart", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Vedic Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: VEDIC_CHART_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();

package/dist/tools/auth.js

@@ -24,6 +24,10 @@ registerTool({
         title: "Connect Account",
         readOnlyHint: false,
         destructiveHint: false,
+        // Each call starts a fresh device-auth flow with a new code — repeating
+        // it is harmless but not a no-op.
+        idempotentHint: false,
+        openWorldHint: false,
     },
     stdioOnly: true,
     handler: async () => {
@@ -105,6 +109,8 @@ registerTool({
         title: "Auth Status",
         readOnlyHint: true,
         destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     },
     stdioOnly: true,
     handler: async () => {
@@ -191,6 +197,8 @@ registerTool({
         title: "Disconnect Account",
         readOnlyHint: false,
         destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
     },
     stdioOnly: true,
     handler: async () => {

package/dist/tools/dev.js

@@ -196,8 +196,10 @@ registerTool({
         DEV_API_REFERENCE,
     inputSchema: makeProxyInputSchema(READ_METHODS),
     outputSchema: OUTPUT_SCHEMA_JSON,
-    // GET-only: never mutates server state.
-    annotations: { title: "API Read", readOnlyHint: true, openWorldHint: true },
+    // GET-only: never mutates server state. openWorldHint false — the proxy
+    // reaches only the fixed, allowlisted OpenEphemeris API (a closed world),
+    // same as every typed tool.
+    annotations: { title: "API Read", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: makeProxyHandler(READ_METHODS, "GET"),
 });
 registerTool({
@@ -209,8 +211,16 @@ registerTool({
         DEV_API_REFERENCE,
     inputSchema: makeProxyInputSchema(WRITE_METHODS),
     outputSchema: OUTPUT_SCHEMA_JSON,
-    // Issues POST/PUT/PATCH/DELETE — must not be advertised as read-only.
-    annotations: { title: "API Write", readOnlyHint: false, openWorldHint: true },
+    // Issues POST/PUT/PATCH/DELETE — must not be advertised as read-only. But
+    // destructiveHint is explicitly FALSE: every allowlisted write operation is
+    // stateless chart computation (natal, synastry, ACG, returns…) that debits
+    // credits and returns a result — nothing on the allowlist mutates or deletes
+    // user data, and the deny rules block /auth, /billing, /account, /api-keys.
+    // Left unset, strict clients default destructiveHint to true and gate every
+    // call behind a confirmation. idempotentHint true for the same reason: the
+    // same body yields the same chart. openWorldHint false — fixed allowlisted
+    // API only, a closed world.
+    annotations: { title: "API Write", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: makeProxyHandler(WRITE_METHODS, "POST"),
 });
 registerTool({
@@ -226,7 +236,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "List Allowed API Operations", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "List Allowed API Operations", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async () => {
         const allowlist = loadAllowlist();
         return {

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", {

package/dist/tools/specialized/hd_group.js

@@ -53,7 +53,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "HD Composite Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "HD Composite Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["person_a_datetime", "person_b_datetime"]);
         const body = {
@@ -123,7 +123,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "HD Penta Group Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "HD Penta Group Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["group_name", "members"]);
         const members = await Promise.all(args.members.map(async (m, i) => ({

package/dist/tools/specialized/human_design.js

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

package/dist/tools/specialized/moon.js

@@ -39,7 +39,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Moon Phase", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Moon Phase", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateCoordinates(args, "latitude", "longitude");
         const params = {};
@@ -104,7 +104,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Next Lunar Phase", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Next Lunar Phase", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const PHASE_LABELS = {
             new_moon: "New Moon",

package/dist/tools/specialized/natal.js

@@ -73,7 +73,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
-    annotations: { title: "Natal Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Natal Chart", 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/progressed.js

@@ -60,7 +60,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
-    annotations: { title: "Progressed Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Progressed Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude", "target_datetime"]);
         assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);

package/dist/tools/specialized/relocation.js

@@ -51,7 +51,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Relocation Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Relocation Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "relocation_latitude", "relocation_longitude"]);
         assertZonedDatetime("natal_datetime", args.natal_datetime, args.timezone);

package/dist/tools/specialized/returns.js

@@ -63,7 +63,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
-    annotations: { title: "Solar Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Solar Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime"]);
         assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);
@@ -136,7 +136,7 @@ registerTool({
     },
     // 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 },
+    annotations: { title: "Lunar Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime"]);
         assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);
@@ -196,7 +196,7 @@ registerTool({
     },
     // 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 },
+    annotations: { title: "Planetary Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["body", "birth_datetime", "target_datetime"]);
         assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);

package/dist/tools/specialized/synastry.js

@@ -57,7 +57,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
-    annotations: { title: "Synastry Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Synastry Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",

package/dist/tools/specialized/transits.js

@@ -64,7 +64,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Transit Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Transit Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"]);
         // ── Step 1: Compute natal chart to extract real planetary longitudes ──

package/dist/tools/specialized/vedic.js

@@ -38,7 +38,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Vedic Natal Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Vedic Natal Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         validateCoordinates(args, "latitude", "longitude");

package/dist/tools/specialized/venus_star_points.js

@@ -35,7 +35,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Venus Star Points", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Venus Star Points", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         assertZonedDatetime("datetime", args.datetime, args.timezone);
@@ -67,7 +67,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Venus Conjunctions", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Venus Conjunctions", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["start_date", "end_date"]);
         const query = {};
@@ -98,7 +98,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Venus 8-Year Star", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Venus 8-Year Star", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["date"]);
         const query = {};
@@ -130,7 +130,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Venus Phase", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Venus Phase", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const query = {};
         if (args.format)
@@ -158,7 +158,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Venus Elongations", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Venus Elongations", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["start_date", "end_date"]);
         const query = {};
@@ -189,7 +189,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Venus Stations", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Venus Stations", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["start_date"]);
         const query = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "4.8.0",
+  "version": "4.8.1",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",