From 2adea7052b08cdc03e93042aed57d6bdc67ba739 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Sat, 7 Nov 2026 01:26:18 +0100 Subject: [PATCH] docs(mcp): name the upcoming periods in the get_cycle description The cycle read returns the projected period starts after the next one, each with its band, under upcoming; the tool description for MCP clients and the Coach did not say so. --- .../tools/__tests__/__snapshots__/coach-turn-tool-defs.snap | 2 +- src/lib/ai/coach/tools/definitions.ts | 2 +- .../__tests__/__snapshots__/tools-list.write-session.snap | 2 +- src/lib/mcp/__tests__/tools.test.ts | 5 +++++ src/lib/mcp/tools/get-cycle.ts | 2 +- 5 files changed, 9 insertions(+), 4 deletions(-) diff --git a/src/lib/ai/coach/tools/__tests__/__snapshots__/coach-turn-tool-defs.snap b/src/lib/ai/coach/tools/__tests__/__snapshots__/coach-turn-tool-defs.snap index 5e6fcd36d..ed91794c9 100644 --- a/src/lib/ai/coach/tools/__tests__/__snapshots__/coach-turn-tool-defs.snap +++ b/src/lib/ai/coach/tools/__tests__/__snapshots__/coach-turn-tool-defs.snap @@ -184,7 +184,7 @@ }, { "name": "get_cycle", - "description": "Fetch the user's menstrual-cycle context: current phase + day-of-cycle, the next predicted event, and the headline phase-correlation finding. Descriptive only — never a contraception-grade or 'safe day' claim. Returns { present: false } when cycle tracking is off or there is no data.", + "description": "Fetch the user's menstrual-cycle context: current phase + day-of-cycle, the next predicted event, the upcoming period starts after it (`upcoming`: each a likely start with its earliest-to-latest band, widening and self-capped), and the headline phase-correlation finding. Descriptive only — never a contraception-grade or 'safe day' claim. Returns { present: false } when cycle tracking is off or there is no data.", "parameters": { "type": "object", "additionalProperties": false, diff --git a/src/lib/ai/coach/tools/definitions.ts b/src/lib/ai/coach/tools/definitions.ts index dcc590b20..c85b0b19e 100644 --- a/src/lib/ai/coach/tools/definitions.ts +++ b/src/lib/ai/coach/tools/definitions.ts @@ -366,7 +366,7 @@ export const COACH_TOOL_DEFS: AiToolDef[] = [ { name: "get_cycle", description: - "Fetch the user's menstrual-cycle context: current phase + day-of-cycle, the next predicted event, and the headline phase-correlation finding. Descriptive only — never a contraception-grade or 'safe day' claim. Returns { present: false } when cycle tracking is off or there is no data.", + "Fetch the user's menstrual-cycle context: current phase + day-of-cycle, the next predicted event, the upcoming period starts after it (`upcoming`: each a likely start with its earliest-to-latest band, widening and self-capped), and the headline phase-correlation finding. Descriptive only — never a contraception-grade or 'safe day' claim. Returns { present: false } when cycle tracking is off or there is no data.", parameters: { type: "object", additionalProperties: false, diff --git a/src/lib/mcp/__tests__/__snapshots__/tools-list.write-session.snap b/src/lib/mcp/__tests__/__snapshots__/tools-list.write-session.snap index 22108a870..25a667153 100644 --- a/src/lib/mcp/__tests__/__snapshots__/tools-list.write-session.snap +++ b/src/lib/mcp/__tests__/__snapshots__/tools-list.write-session.snap @@ -1844,7 +1844,7 @@ { "name": "get_cycle", "title": "Get menstrual cycle", - "description": "Fetch the user's menstrual-cycle context: current phase + day-of-cycle, the next predicted event, and the headline phase-correlation finding. Descriptive only — never a contraception-grade or 'safe day' claim. Gated on cycle tracking being enabled for the account; returns { present: false } when cycle tracking is off or there is no data.", + "description": "Fetch the user's menstrual-cycle context: current phase + day-of-cycle, the next predicted event, the upcoming period starts after it (`upcoming`: each a likely start with its earliest-to-latest band, widening and self-capped), and the headline phase-correlation finding. Descriptive only — never a contraception-grade or 'safe day' claim. Gated on cycle tracking being enabled for the account; returns { present: false } when cycle tracking is off or there is no data.", "inputSchema": { "type": "object", "properties": {} diff --git a/src/lib/mcp/__tests__/tools.test.ts b/src/lib/mcp/__tests__/tools.test.ts index e4fa0aa3e..dd14c655b 100644 --- a/src/lib/mcp/__tests__/tools.test.ts +++ b/src/lib/mcp/__tests__/tools.test.ts @@ -326,6 +326,11 @@ describe("MCP tool registry — surface", () => { } }); + it("tells a client that get_cycle returns the upcoming periods", () => { + const def = MCP_TOOLS.find((t) => t.name === "get_cycle"); + expect(def?.description).toContain("`upcoming`"); + }); + it("annotates every tool read-only / closed-world (cloud-connector requirement)", () => { for (const def of MCP_TOOLS) { expect(def.annotations.readOnlyHint).toBe(true); diff --git a/src/lib/mcp/tools/get-cycle.ts b/src/lib/mcp/tools/get-cycle.ts index e95b4fbb6..b3598eef0 100644 --- a/src/lib/mcp/tools/get-cycle.ts +++ b/src/lib/mcp/tools/get-cycle.ts @@ -6,7 +6,7 @@ export const getCycleTool: McpToolDefinition = { name: "get_cycle", title: "Get menstrual cycle", description: - "Fetch the user's menstrual-cycle context: current phase + day-of-cycle, the next predicted event, and the headline phase-correlation finding. Descriptive only — never a contraception-grade or 'safe day' claim. Gated on cycle tracking being enabled for the account; returns { present: false } when cycle tracking is off or there is no data.", + "Fetch the user's menstrual-cycle context: current phase + day-of-cycle, the next predicted event, the upcoming period starts after it (`upcoming`: each a likely start with its earliest-to-latest band, widening and self-capped), and the headline phase-correlation finding. Descriptive only — never a contraception-grade or 'safe day' claim. Gated on cycle tracking being enabled for the account; returns { present: false } when cycle tracking is off or there is no data.", inputShape: {}, annotations: READ_ONLY_ANNOTATIONS, outputShape: coachReadOutput,