@softeria/ms-365-mcp-server 0.134.0 → 0.134.2

package/dist/__tests__/graph-tools.test.js

@@ -393,6 +393,19 @@ describe("graph-tools", () => {
       expect(schema["expand"].description).toContain("navigation");
       expect(schema["expand"].description).toContain("attachments");
     });
+    it("should describe path params it synthesizes itself", async () => {
+      const endpoint = makeEndpoint({ path: "/me/messages/:messageId" });
+      const config = makeConfig();
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, createMockGraphClient());
+      const schema = server.tools.get("test-tool").schema;
+      expect(schema["messageId"]).toBeDefined();
+      expect(schema["messageId"].description).not.toBe("Path parameter: messageId");
+      expect(schema["messageId"].description).toContain("not as 'id'");
+    });
   });
   describe("MS365_MCP_MAX_TOP", () => {
     const prevMaxTop = process.env.MS365_MCP_MAX_TOP;

package/dist/generated/hack.js

@@ -1,7 +1,12 @@
 import { z } from "zod";
+import { describePathParam } from "../lib/path-params.js";
 function makeApi(endpoints) {
   return endpoints;
 }
+function isPathParamStub(param) {
+  const description = param.description ?? param.schema?.description;
+  return typeof description === "string" && /^Path parameter: /.test(description);
+}
 class Zodios {
   constructor(baseUrlOrEndpoints, endpoints, options) {
     if (typeof baseUrlOrEndpoints === "string") {
@@ -19,17 +24,24 @@ class Zodios {
         pathParams.push(match[1]);
       }
       for (const pathParam of pathParams) {
-        const paramExists = endpoint.parameters.some(
+        const existing = endpoint.parameters.find(
           (param) => param.name === pathParam || param.name === pathParam.replace(/[$_]+/g, "")
         );
-        if (!paramExists) {
+        if (!existing) {
+          const description = describePathParam(pathParam);
           const newParam = {
             name: pathParam,
             type: "Path",
-            schema: z.string().describe(`Path parameter: ${pathParam}`),
-            description: `Path parameter: ${pathParam}`
+            schema: z.string().describe(description),
+            description
           };
           endpoint.parameters.push(newParam);
+          continue;
+        }
+        if (existing.type === "Path" && isPathParamStub(existing)) {
+          const description = describePathParam(existing.name);
+          existing.description = description;
+          existing.schema = z.string().describe(description);
         }
       }
       return endpoint;

package/dist/graph-tools.js

@@ -2,6 +2,7 @@ import { randomUUID } from "crypto";
 import logger from "./logger.js";
 import { auditLog, getUserIdentityForAudit } from "./audit-log.js";
 import { isDestructiveOperation } from "./lib/destructive-ops.js";
+import { describePathParam } from "./lib/path-params.js";
 import {
   getEndpointScopeGroups,
   getMissingAllowedScopesForGroups,
@@ -20,15 +21,33 @@ import { getRequestTokens } from "./request-context.js";
 import { parseTeamsUrl } from "./lib/teams-url-parser.js";
 import { buildBM25Index, scoreQuery, tokenize } from "./lib/bm25.js";
 import { describeToolSchema, describeUtilityToolSchema } from "./lib/tool-schema.js";
+import {
+  TOP_UNSUPPORTED_DELTA_TOOLS,
+  shouldOmitTopParam,
+  paginationAllowed,
+  positiveIntFromEnv,
+  DEFAULT_MAX_PAGES,
+  getMaxPages,
+  isFetchAllPagesApplicable,
+  FILTER_PARAM_DESCRIPTION,
+  SEARCH_PARAM_DESCRIPTION,
+  SELECT_PARAM_DESCRIPTION,
+  EXPAND_PARAM_DESCRIPTION,
+  ORDERBY_PARAM_DESCRIPTION,
+  TOP_PARAM_DESCRIPTION,
+  SKIP_PARAM_DESCRIPTION,
+  COUNT_PARAM_DESCRIPTION,
+  CONFIRM_PARAM_DESCRIPTION,
+  TIMEZONE_PARAM_DESCRIPTION,
+  EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION,
+  getAccountParamDescription,
+  getFetchAllPagesParamDescription
+} from "./lib/param-descriptions.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const endpointsData = JSON.parse(
   readFileSync(path.join(__dirname, "endpoints.json"), "utf8")
 );
-const TOP_UNSUPPORTED_DELTA_TOOLS = /* @__PURE__ */ new Set([
-  "list-calendar-events-delta",
-  "list-calendar-view-delta"
-]);
 function withApiVersionPrefix(description, config) {
   return config?.apiVersion === "beta" ? `[beta] ${description}` : description;
 }
@@ -52,23 +71,7 @@ function clampTopQueryParam(queryParams) {
   logger.info(`Clamping $top from ${requested} to ${cap} (MS365_MCP_MAX_TOP)`);
   queryParams["$top"] = String(cap);
 }
-const DEFAULT_MAX_PAGES = 100;
 const DEFAULT_MAX_ITEMS = 1e4;
-function positiveIntFromEnv(name, defaultValue) {
-  const raw = process.env[name];
-  if (raw === void 0 || raw === "") return defaultValue;
-  const n = Number.parseInt(raw, 10);
-  if (!Number.isFinite(n) || n < 1) {
-    logger.warn(`Ignoring invalid ${name}=${JSON.stringify(raw)} (use a positive integer)`);
-    return defaultValue;
-  }
-  return n;
-}
-function paginationAllowed() {
-  const raw = process.env.MS365_MCP_ALLOW_PAGINATION;
-  if (raw === void 0 || raw === "") return true;
-  return !/^(0|false|no)$/i.test(raw.trim());
-}
 function isConfirmGateEnabled() {
   return process.env.MS365_MCP_REQUIRE_CONFIRM === "true";
 }
@@ -1000,81 +1003,62 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
     for (const match of pathParamMatches) {
       const pathParamName = match[1];
       if (!(pathParamName in paramSchema)) {
-        paramSchema[pathParamName] = z.string().describe(`Path parameter: ${pathParamName}`);
+        paramSchema[pathParamName] = z.string().describe(describePathParam(pathParamName));
       }
     }
-    if (tool.method.toUpperCase() === "GET" && tool.path.includes("/") && paginationAllowed()) {
-      const maxPages = positiveIntFromEnv("MS365_MCP_MAX_PAGES", DEFAULT_MAX_PAGES);
-      paramSchema["fetchAllPages"] = z.boolean().describe(
-        `Follow @odata.nextLink and merge up to ${maxPages} pages into one response. Can return enormous payloads\u2014only when the user explicitly needs a full export. Prefer a small $top first, then paginate or narrow with $filter/$search.`
-      ).optional();
+    if (isFetchAllPagesApplicable(tool)) {
+      const maxPages = getMaxPages();
+      paramSchema["fetchAllPages"] = z.boolean().describe(getFetchAllPagesParamDescription(maxPages)).optional();
     }
     if (paramSchema["filter"] !== void 0 || paramSchema["$filter"] !== void 0) {
       const key = paramSchema["$filter"] !== void 0 ? "$filter" : "filter";
-      paramSchema[key] = z.string().describe(
-        "OData filter expression. Add $count=true for advanced filters (flag/flagStatus, contains()). Cannot combine with $search."
-      ).optional();
+      paramSchema[key] = z.string().describe(FILTER_PARAM_DESCRIPTION).optional();
     }
     if (paramSchema["search"] !== void 0 || paramSchema["$search"] !== void 0) {
       const key = paramSchema["$search"] !== void 0 ? "$search" : "search";
-      paramSchema[key] = z.string().describe("KQL search query \u2014 wrap value in double quotes. Cannot combine with $filter.").optional();
+      paramSchema[key] = z.string().describe(SEARCH_PARAM_DESCRIPTION).optional();
     }
     if (paramSchema["select"] !== void 0 || paramSchema["$select"] !== void 0) {
       const key = paramSchema["$select"] !== void 0 ? "$select" : "select";
-      paramSchema[key] = z.string().describe("Comma-separated fields to return, e.g. id,subject,from,receivedDateTime").optional();
+      paramSchema[key] = z.string().describe(SELECT_PARAM_DESCRIPTION).optional();
     }
     if (paramSchema["expand"] !== void 0 || paramSchema["$expand"] !== void 0) {
       const key = paramSchema["$expand"] !== void 0 ? "$expand" : "expand";
-      paramSchema[key] = z.array(z.string()).describe(
-        'Navigation properties to inline, e.g. attachments on a message or event. Only navigation properties can be expanded: expanding a non-navigation property such as a message body fails with "Parsing OData Select and Expand failed", and an unsupported value may be ignored rather than reported. Request ordinary fields with $select instead.'
-      ).optional();
+      paramSchema[key] = z.array(z.string()).describe(EXPAND_PARAM_DESCRIPTION).optional();
     }
     if (paramSchema["orderby"] !== void 0 || paramSchema["$orderby"] !== void 0) {
       const key = paramSchema["$orderby"] !== void 0 ? "$orderby" : "orderby";
-      paramSchema[key] = z.string().describe("Sort expression, e.g. receivedDateTime desc").optional();
+      paramSchema[key] = z.string().describe(ORDERBY_PARAM_DESCRIPTION).optional();
     }
-    if (TOP_UNSUPPORTED_DELTA_TOOLS.has(tool.alias)) {
+    if (shouldOmitTopParam(tool.alias)) {
       delete paramSchema["top"];
       delete paramSchema["$top"];
     } else if (paramSchema["top"] !== void 0 || paramSchema["$top"] !== void 0) {
       const key = paramSchema["$top"] !== void 0 ? "$top" : "top";
-      paramSchema[key] = z.number().describe(
-        "Page size (Graph $top). Start small (e.g. 5\u201315) so responses fit the model context; raise only if needed. Use $select to return fewer fields per item. For more rows, use @odata.nextLink from the response instead of a very large $top."
-      ).optional();
+      paramSchema[key] = z.number().describe(TOP_PARAM_DESCRIPTION).optional();
     }
     if (paramSchema["skip"] !== void 0 || paramSchema["$skip"] !== void 0) {
       const key = paramSchema["$skip"] !== void 0 ? "$skip" : "skip";
-      paramSchema[key] = z.number().describe("Items to skip for pagination. Not supported with $search.").optional();
+      paramSchema[key] = z.number().describe(SKIP_PARAM_DESCRIPTION).optional();
     }
     if (paramSchema["count"] !== void 0 || paramSchema["$count"] !== void 0) {
       const countKey = paramSchema["$count"] !== void 0 ? "$count" : "count";
-      paramSchema[countKey] = z.boolean().describe(
-        "Set true to enable advanced query mode (ConsistencyLevel: eventual). Required for complex $filter on flag/flagStatus or contains()."
-      ).optional();
+      paramSchema[countKey] = z.boolean().describe(COUNT_PARAM_DESCRIPTION).optional();
     }
     if (multiAccount) {
-      const accountHint = accountNames.length > 0 ? `Known accounts: ${accountNames.join(", ")}. ` : "";
-      paramSchema["account"] = z.string().describe(
-        `${accountHint}Microsoft account email to use for this request. Required when multiple accounts are configured. Use the list-accounts tool to discover all currently available accounts.`
-      ).optional();
+      paramSchema["account"] = z.string().describe(getAccountParamDescription(accountNames)).optional();
     }
     paramSchema["includeHeaders"] = z.boolean().describe("Include response headers (including ETag) in the response metadata").optional();
     paramSchema["excludeResponse"] = z.boolean().describe("Exclude the full response body and only return success or failure indication").optional();
     const destructive = isDestructiveOperation(tool.method, endpointConfig);
     if (destructive) {
-      paramSchema["confirm"] = z.boolean().describe(
-        'For destructive operations when the confirm gate is enabled (MS365_MCP_REQUIRE_CONFIRM=true; off by default). Set to true only after the user has explicitly approved this action. When the gate is on, calls without confirm: true return { error: "confirmation_required" } without touching user data.'
-      ).optional();
+      paramSchema["confirm"] = z.boolean().describe(CONFIRM_PARAM_DESCRIPTION).optional();
     }
     if (endpointConfig?.supportsTimezone) {
-      paramSchema["timezone"] = z.string().describe(
-        'IANA timezone name (e.g., "America/New_York", "Europe/London", "Asia/Tokyo") for calendar event times. If not specified, times are returned in UTC.'
-      ).optional();
+      paramSchema["timezone"] = z.string().describe(TIMEZONE_PARAM_DESCRIPTION).optional();
     }
     if (endpointConfig?.supportsExpandExtendedProperties) {
-      paramSchema["expandExtendedProperties"] = z.boolean().describe(
-        "When true, expands singleValueExtendedProperties on each event. Use this to retrieve custom extended properties (e.g., sync metadata) stored on calendar events."
-      ).optional();
+      paramSchema["expandExtendedProperties"] = z.boolean().describe(EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION).optional();
     }
     let toolDescription = withApiVersionPrefix(
       (endpointConfig?.descriptionOverride ?? tool.description) || `Execute ${tool.method.toUpperCase()} request to ${tool.path}`,
@@ -1373,7 +1357,7 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
     async ({ tool_name }) => {
       const entry = toolsRegistry.get(tool_name);
       if (entry) {
-        const schema = describeToolSchema(entry.tool, entry.config);
+        const schema = describeToolSchema(entry.tool, entry.config, { multiAccount, accountNames });
         return {
           content: [{ type: "text", text: JSON.stringify(schema, null, 2) }]
         };

package/dist/lib/param-descriptions.js

@@ -0,0 +1,93 @@
+import logger from "../logger.js";
+const TOP_UNSUPPORTED_DELTA_TOOLS = /* @__PURE__ */ new Set([
+  "list-calendar-events-delta",
+  "list-calendar-view-delta"
+]);
+function shouldOmitTopParam(toolAlias) {
+  return TOP_UNSUPPORTED_DELTA_TOOLS.has(toolAlias);
+}
+function paginationAllowed() {
+  const raw = process.env.MS365_MCP_ALLOW_PAGINATION;
+  if (raw === void 0 || raw === "") return true;
+  return !/^(0|false|no)$/i.test(raw.trim());
+}
+const DEFAULT_MAX_PAGES = 100;
+function positiveIntFromEnv(name, defaultValue) {
+  const raw = process.env[name];
+  if (raw === void 0 || raw === "") return defaultValue;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1) {
+    logger.warn(`Ignoring invalid ${name}=${JSON.stringify(raw)} (use a positive integer)`);
+    return defaultValue;
+  }
+  return n;
+}
+function getMaxPages() {
+  return positiveIntFromEnv("MS365_MCP_MAX_PAGES", DEFAULT_MAX_PAGES);
+}
+function isFetchAllPagesApplicable(tool) {
+  return tool.method.toUpperCase() === "GET" && tool.path.includes("/") && paginationAllowed();
+}
+const FILTER_PARAM_DESCRIPTION = "OData filter expression. Add $count=true for advanced filters (flag/flagStatus, contains()). Cannot combine with $search.";
+const SEARCH_PARAM_DESCRIPTION = "KQL search query \u2014 wrap value in double quotes. Cannot combine with $filter.";
+const SELECT_PARAM_DESCRIPTION = "Comma-separated fields to return, e.g. id,subject,from,receivedDateTime";
+const EXPAND_PARAM_DESCRIPTION = 'Navigation properties to inline, e.g. attachments on a message or event. Only navigation properties can be expanded: expanding a non-navigation property such as a message body fails with "Parsing OData Select and Expand failed", and an unsupported value may be ignored rather than reported. Request ordinary fields with $select instead.';
+const ORDERBY_PARAM_DESCRIPTION = "Sort expression, e.g. receivedDateTime desc";
+const TOP_PARAM_DESCRIPTION = "Page size (Graph $top). Start small (e.g. 5\u201315) so responses fit the model context; raise only if needed. Use $select to return fewer fields per item. For more rows, use @odata.nextLink from the response instead of a very large $top.";
+const SKIP_PARAM_DESCRIPTION = "Items to skip for pagination. Not supported with $search.";
+const COUNT_PARAM_DESCRIPTION = "Set true to enable advanced query mode (ConsistencyLevel: eventual). Required for complex $filter on flag/flagStatus or contains().";
+const CONFIRM_PARAM_DESCRIPTION = 'For destructive operations when the confirm gate is enabled (MS365_MCP_REQUIRE_CONFIRM=true; off by default). Set to true only after the user has explicitly approved this action. When the gate is on, calls without confirm: true return { error: "confirmation_required" } without touching user data.';
+const TIMEZONE_PARAM_DESCRIPTION = 'IANA timezone name (e.g., "America/New_York", "Europe/London", "Asia/Tokyo") for calendar event times. If not specified, times are returned in UTC.';
+const EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION = "When true, expands singleValueExtendedProperties on each event. Use this to retrieve custom extended properties (e.g., sync metadata) stored on calendar events.";
+function getAccountParamDescription(accountNames) {
+  const accountHint = accountNames.length > 0 ? `Known accounts: ${accountNames.join(", ")}. ` : "";
+  return `${accountHint}Microsoft account email to use for this request. Required when multiple accounts are configured. Use the list-accounts tool to discover all currently available accounts.`;
+}
+function getFetchAllPagesParamDescription(maxPages) {
+  return `Follow @odata.nextLink and merge up to ${maxPages} pages into one response. Can return enormous payloads\u2014only when the user explicitly needs a full export. Prefer a small $top first, then paginate or narrow with $filter/$search.`;
+}
+function getODataParamDescription(bareName) {
+  switch (bareName) {
+    case "filter":
+      return FILTER_PARAM_DESCRIPTION;
+    case "search":
+      return SEARCH_PARAM_DESCRIPTION;
+    case "select":
+      return SELECT_PARAM_DESCRIPTION;
+    case "expand":
+      return EXPAND_PARAM_DESCRIPTION;
+    case "orderby":
+      return ORDERBY_PARAM_DESCRIPTION;
+    case "top":
+      return TOP_PARAM_DESCRIPTION;
+    case "skip":
+      return SKIP_PARAM_DESCRIPTION;
+    case "count":
+      return COUNT_PARAM_DESCRIPTION;
+    default:
+      return void 0;
+  }
+}
+export {
+  CONFIRM_PARAM_DESCRIPTION,
+  COUNT_PARAM_DESCRIPTION,
+  DEFAULT_MAX_PAGES,
+  EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION,
+  EXPAND_PARAM_DESCRIPTION,
+  FILTER_PARAM_DESCRIPTION,
+  ORDERBY_PARAM_DESCRIPTION,
+  SEARCH_PARAM_DESCRIPTION,
+  SELECT_PARAM_DESCRIPTION,
+  SKIP_PARAM_DESCRIPTION,
+  TIMEZONE_PARAM_DESCRIPTION,
+  TOP_PARAM_DESCRIPTION,
+  TOP_UNSUPPORTED_DELTA_TOOLS,
+  getAccountParamDescription,
+  getFetchAllPagesParamDescription,
+  getMaxPages,
+  getODataParamDescription,
+  isFetchAllPagesApplicable,
+  paginationAllowed,
+  positiveIntFromEnv,
+  shouldOmitTopParam
+};

package/dist/lib/path-params.js

@@ -0,0 +1,16 @@
+function describePathParam(pathParamName) {
+  const match = /^(.*?)Id(\d*)$/.exec(pathParamName);
+  if (match && match[1]) {
+    const base = `Value for the '${pathParamName}' path segment. Pass it under the name '${pathParamName}', not as 'id'. `;
+    if (match[2]) {
+      return base + `It identifies a different resource from the similarly named parameter without the number; check the tool's path to see which.`;
+    }
+    const resource = match[1].replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+    const noun = /(^|\s)object$/.test(resource) ? resource : `${resource} object`;
+    return base + `Use the 'id' field of the ${noun} as returned by Microsoft Graph.`;
+  }
+  return `Value for the '${pathParamName}' path segment.`;
+}
+export {
+  describePathParam
+};

package/dist/lib/tool-schema.js

@@ -1,5 +1,16 @@
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { isDestructiveOperation } from "./destructive-ops.js";
+import {
+  getODataParamDescription,
+  shouldOmitTopParam,
+  isFetchAllPagesApplicable,
+  getMaxPages,
+  getFetchAllPagesParamDescription,
+  getAccountParamDescription,
+  CONFIRM_PARAM_DESCRIPTION,
+  TIMEZONE_PARAM_DESCRIPTION,
+  EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION
+} from "./param-descriptions.js";
 function unwrapOptional(schema) {
   const def = schema._def;
   const typeName = def?.typeName;
@@ -8,17 +19,22 @@ function unwrapOptional(schema) {
   }
   return { inner: schema, optional: false };
 }
-function describeToolSchema(tool, config) {
-  const params = (tool.parameters ?? []).map((p) => {
+function bareParamName(name) {
+  return name.startsWith("$") ? name.slice(1) : name;
+}
+function describeToolSchema(tool, config, ctx = {}) {
+  const omitTop = shouldOmitTopParam(tool.alias);
+  const params = (tool.parameters ?? []).filter((p) => !(omitTop && bareParamName(p.name) === "top")).map((p) => {
     const { inner, optional } = unwrapOptional(p.schema);
     const isPath = p.type === "Path";
     const jsonSchema = zodToJsonSchema(inner, { target: "jsonSchema7", $refStrategy: "none" });
     const { $schema: _s, ...schema } = jsonSchema;
+    const override = p.type === "Query" ? getODataParamDescription(bareParamName(p.name)) : void 0;
     return {
       name: p.name,
       in: p.type,
       required: isPath || !optional,
-      description: p.description,
+      description: override ?? p.description,
       schema
     };
   });
@@ -27,7 +43,43 @@ function describeToolSchema(tool, config) {
       name: "confirm",
       in: "Query",
       required: false,
-      description: 'For destructive operations when the confirm gate is enabled (MS365_MCP_REQUIRE_CONFIRM=true; off by default). Set to true only after the user has explicitly approved this action. When the gate is on, calls without confirm: true return { error: "confirmation_required" } without touching user data.',
+      description: CONFIRM_PARAM_DESCRIPTION,
+      schema: { type: "boolean" }
+    });
+  }
+  if (isFetchAllPagesApplicable({ method: tool.method, path: tool.path })) {
+    params.push({
+      name: "fetchAllPages",
+      in: "Query",
+      required: false,
+      description: getFetchAllPagesParamDescription(getMaxPages()),
+      schema: { type: "boolean" }
+    });
+  }
+  if (ctx.multiAccount) {
+    params.push({
+      name: "account",
+      in: "Query",
+      required: false,
+      description: getAccountParamDescription(ctx.accountNames ?? []),
+      schema: { type: "string" }
+    });
+  }
+  if (config?.supportsTimezone) {
+    params.push({
+      name: "timezone",
+      in: "Query",
+      required: false,
+      description: TIMEZONE_PARAM_DESCRIPTION,
+      schema: { type: "string" }
+    });
+  }
+  if (config?.supportsExpandExtendedProperties) {
+    params.push({
+      name: "expandExtendedProperties",
+      in: "Query",
+      required: false,
+      description: EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION,
       schema: { type: "boolean" }
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.134.0",
+  "version": "0.134.2",
   "description": " A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Office services through the Graph API",
   "type": "module",
   "main": "dist/index.js",

package/src/generated/hack.ts

@@ -1,10 +1,17 @@
 import { Endpoint, Parameter } from './endpoint-types.js';
 import { z } from 'zod';
+import { describePathParam } from '../lib/path-params.js';
 
 export function makeApi(endpoints: Endpoint[]) {
   return endpoints;
 }
 
+/** True when a path parameter carries only the generated `Path parameter: x` placeholder. */
+function isPathParamStub(param: Parameter): boolean {
+  const description = param.description ?? param.schema?.description;
+  return typeof description === 'string' && /^Path parameter: /.test(description);
+}
+
 export class Zodios {
   endpoints: Endpoint[];
 
@@ -26,18 +33,30 @@ export class Zodios {
       }
 
       for (const pathParam of pathParams) {
-        const paramExists = endpoint.parameters.some(
+        const existing = endpoint.parameters.find(
           (param) => param.name === pathParam || param.name === pathParam.replace(/[$_]+/g, '')
         );
 
-        if (!paramExists) {
+        if (!existing) {
+          const description = describePathParam(pathParam);
           const newParam: Parameter = {
             name: pathParam,
             type: 'Path',
-            schema: z.string().describe(`Path parameter: ${pathParam}`),
-            description: `Path parameter: ${pathParam}`,
+            schema: z.string().describe(description),
+            description,
           };
           endpoint.parameters.push(newParam);
+          continue;
+        }
+
+        // Some operations arrive with the path parameter already declared, but described
+        // only as `Path parameter: drive-id` — no more use to the model than nothing, and
+        // spelled in kebab-case so it does not even match the name callers must send.
+        // Upgrade those; any real upstream description is left alone.
+        if (existing.type === 'Path' && isPathParamStub(existing)) {
+          const description = describePathParam(existing.name);
+          existing.description = description;
+          existing.schema = z.string().describe(description);
         }
       }