@softeria/ms-365-mcp-server 0.167.0 → 0.168.0

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

@@ -4190,6 +4190,175 @@ describe("graph-tools", () => {
       expect(isDestructiveOperation("DELETE", { readOnly: true })).toBe(true);
     });
   });
+  describe("rewriteMentionShorthand", () => {
+    const U1 = "11111111-2222-3333-4444-555555555555";
+    const U2 = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+    const html = (content, extra = {}) => ({
+      body: { contentType: "html", content },
+      ...extra
+    });
+    const mention = (id, userId, name) => ({
+      id,
+      mentionText: name,
+      mentioned: { user: { id: userId, displayName: name, userIdentityType: "aadUser" } }
+    });
+    it("rewrites one tag and builds the mentions array", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      expect(rewriteMentionShorthand(html(`Hi <at user-id="${U1}">Jane Doe</at>!`)).body).toEqual(
+        html('Hi <at id="0">Jane Doe</at>!', { mentions: [mention(0, U1, "Jane Doe")] })
+      );
+    });
+    it("numbers several tags in order, including a repeated user", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const out = rewriteMentionShorthand(
+        html(
+          `<at user-id="${U1}">Jane</at> <at user-id="${U2}">Bob</at> <at user-id="${U1}">Jane</at>`
+        )
+      ).body;
+      expect(out.body.content).toBe(
+        '<at id="0">Jane</at> <at id="1">Bob</at> <at id="2">Jane</at>'
+      );
+      expect(out.mentions.map((m) => m.id)).toEqual([0, 1, 2]);
+    });
+    it("starts above ids already in the content and mentions", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const input = html(`<at id="0">Old</at> <at user-id="${U1}">Jane</at>`, {
+        mentions: [mention(0, U2, "Old")]
+      });
+      const out = rewriteMentionShorthand(input).body;
+      expect(out.body.content).toBe('<at id="0">Old</at> <at id="1">Jane</at>');
+      expect(out.mentions).toEqual([mention(0, U2, "Old"), mention(1, U1, "Jane")]);
+    });
+    it("passes a correct hand-built body through unchanged", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const input = html('<at id="0">Jane</at>', { mentions: [mention(0, U1, "Jane")] });
+      expect(rewriteMentionShorthand(input).body).toBe(input);
+    });
+    it("returns an error for a user-id that is not a GUID", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const input = html('<at user-id="jane@contoso.com">Jane</at>');
+      const out = rewriteMentionShorthand(input);
+      expect(out.error).toContain("jane@contoso.com");
+      expect(out.body).toBe(input);
+    });
+    it("leaves non-html content without the shorthand alone", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const text = { body: { contentType: "text", content: "plain words" } };
+      const bare = { body: { content: "plain words" } };
+      expect(rewriteMentionShorthand(text).body).toBe(text);
+      expect(rewriteMentionShorthand(bare).body).toBe(bare);
+    });
+    it.each([
+      ["text", { contentType: "text" }],
+      ["missing", {}]
+    ])("returns an error for the shorthand when contentType is %s", async (_label, type) => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const input = { body: { ...type, content: `<at user-id="${U1}">Jane</at>` } };
+      const out = rewriteMentionShorthand(input);
+      expect(out.error).toContain("contentType");
+      expect(out.body).toBe(input);
+    });
+    it.each([
+      ["single-quoted user-id", `<at user-id='${U1}'>Jane</at>`],
+      ["spaces around =", `<at user-id = "${U1}">Jane</at>`],
+      ["an extra attribute", `<at user-id="${U1}" class="x">Jane</at>`],
+      ["nested markup in the name", `<at user-id="${U1}"><b>Jane</b></at>`]
+    ])("returns an error for an unsupported tag form: %s", async (_label, tag) => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const input = html(`Hi ${tag}`);
+      const out = rewriteMentionShorthand(input);
+      expect(out.error).toContain("Unsupported mention tag form");
+      expect(out.body).toBe(input);
+    });
+    it("leaves a raw string body alone", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      expect(rewriteMentionShorthand('{"body":{}}').body).toBe('{"body":{}}');
+      expect(rewriteMentionShorthand(null).body).toBeNull();
+    });
+    it("keeps the display name verbatim", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const out = rewriteMentionShorthand(html(`<at user-id="${U1}">Smith &amp; Co</at>`)).body;
+      expect(out.body.content).toBe('<at id="0">Smith &amp; Co</at>');
+      expect(out.mentions[0].mentionText).toBe("Smith &amp; Co");
+    });
+  });
+  describe("mention shorthand (tool wiring)", () => {
+    const U1 = "11111111-2222-3333-4444-555555555555";
+    const aliases = [
+      ["send-channel-message", "post"],
+      ["reply-to-channel-message", "post"],
+      ["update-channel-message", "patch"],
+      ["update-channel-message-reply", "patch"],
+      ["send-chat-message", "post"],
+      ["reply-to-chat-message", "post"],
+      ["update-chat-message", "patch"]
+    ];
+    async function call(alias, method, body) {
+      mockEndpoints.push(
+        makeEndpoint({
+          alias,
+          method,
+          path: "/chats/{chat-id}/messages",
+          parameters: [{ name: "body", type: "Body", schema: z.object({}).passthrough() }]
+        })
+      );
+      mockEndpointsJson = [
+        makeConfig({ toolName: alias, method, pathPattern: "/chats/{chat-id}/messages" })
+      ];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ id: "m1" }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const result = await server.tools.get(alias).handler({ "chat-id": "c1", body, confirm: true });
+      return { result, graphClient };
+    }
+    const sent = (graphClient) => JSON.parse(graphClient.graphRequest.mock.calls[0][1].body);
+    it.each(aliases)("rewrites the shorthand on %s", async (alias, method) => {
+      const { graphClient } = await call(alias, method, {
+        body: { contentType: "html", content: `Hi <at user-id="${U1}">Jane</at>` }
+      });
+      const out = sent(graphClient);
+      expect(out.body.content).toBe('Hi <at id="0">Jane</at>');
+      expect(out.mentions).toEqual([
+        {
+          id: 0,
+          mentionText: "Jane",
+          mentioned: { user: { id: U1, displayName: "Jane", userIdentityType: "aadUser" } }
+        }
+      ]);
+    });
+    it("returns a tool error and sends nothing for a bad user-id", async () => {
+      const { result, graphClient } = await call("send-chat-message", "post", {
+        body: { contentType: "html", content: '<at user-id="jane">Jane</at>' }
+      });
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("not an Entra object id");
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+    });
+    it("does not rewrite on a tool outside the seven", async () => {
+      const { graphClient } = await call("create-draft-email", "post", {
+        body: { contentType: "html", content: `<at user-id="${U1}">Jane</at>` }
+      });
+      expect(sent(graphClient).body.content).toBe(`<at user-id="${U1}">Jane</at>`);
+    });
+    it("lists only tools that exist in endpoints.json and documents the shorthand", async () => {
+      const actualFs = await vi.importActual("fs");
+      const endpoints = JSON.parse(
+        actualFs.readFileSync(join(__dirname, "..", "endpoints.json"), "utf8")
+      );
+      for (const [alias] of aliases) {
+        const entry = endpoints.find((e) => e.toolName === alias);
+        expect(entry, alias).toBeDefined();
+        const tip = entry.llmTip;
+        expect(tip, alias).toContain("user-id=");
+        expect(tip, alias).not.toContain("name param");
+        expect(tip, alias).toContain("userId");
+        expect(tip.split("To @mention someone").length - 1, alias).toBe(1);
+      }
+    });
+  });
   describe("filterMembersByName", () => {
     const body = {
       value: [

package/dist/endpoints.json

@@ -1759,7 +1759,8 @@
     "method": "patch",
     "toolName": "update-chat-message",
     "presets": ["teams", "work"],
-    "workScopes": ["Chat.ReadWrite"]
+    "workScopes": ["Chat.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/chats/{chat-id}/messages/{chatMessage-id}/hostedContents",
@@ -1775,7 +1776,7 @@
     "toolName": "send-chat-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChatMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/me/joinedTeams",
@@ -1878,7 +1879,8 @@
     "method": "patch",
     "toolName": "update-channel-message",
     "presets": ["teams", "work"],
-    "workScopes": ["ChannelMessage.ReadWrite"]
+    "workScopes": ["ChannelMessage.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/hostedContents",
@@ -1894,7 +1896,7 @@
     "toolName": "send-channel-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChannelMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
@@ -1902,7 +1904,7 @@
     "toolName": "reply-to-channel-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChannelMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
@@ -1916,7 +1918,8 @@
     "method": "patch",
     "toolName": "update-channel-message-reply",
     "presets": ["teams", "work"],
-    "workScopes": ["ChannelMessage.ReadWrite"]
+    "workScopes": ["ChannelMessage.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/teams/{team-id}/members",
@@ -1982,7 +1985,7 @@
     "toolName": "reply-to-chat-message",
     "presets": ["teams", "work"],
     "workScopes": ["ChatMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/chats/{chat-id}/messages/{chatMessage-id}/setReaction",

package/dist/graph-tools.js

@@ -397,6 +397,63 @@ function collectRecipients(node, domains, counter, depth = 0) {
     collectRecipients(value, domains, counter, depth + 1);
   }
 }
+const MENTION_SHORTHAND_TOOLS = /* @__PURE__ */ new Set([
+  "send-channel-message",
+  "reply-to-channel-message",
+  "update-channel-message",
+  "update-channel-message-reply",
+  "send-chat-message",
+  "reply-to-chat-message",
+  "update-chat-message"
+]);
+const AAD_GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHORTHAND_AT = /<at\s+user-id="([^"]*)">([^<]*)<\/at>/gi;
+const HAS_SHORTHAND = /<at\b[^>]*\buser-id\b/i;
+function rewriteMentionShorthand(body) {
+  if (!isPlainObject(body) || !isPlainObject(body.body)) return { body };
+  const itemBody = body.body;
+  const content = itemBody.content;
+  if (typeof content !== "string" || !HAS_SHORTHAND.test(content)) return { body };
+  if (String(itemBody.contentType).toLowerCase() !== "html") {
+    return {
+      body,
+      error: 'The <at user-id> mention shorthand needs contentType "html" on the message body. Set body.contentType to "html".'
+    };
+  }
+  const existing = Array.isArray(body.mentions) ? body.mentions : [];
+  let nextId = 0;
+  for (const m of existing) {
+    if (isPlainObject(m) && typeof m.id === "number") nextId = Math.max(nextId, m.id + 1);
+  }
+  for (const m of content.matchAll(/<at\s+id="(\d+)"/gi)) {
+    nextId = Math.max(nextId, Number(m[1]) + 1);
+  }
+  const added = [];
+  let error;
+  const rewritten = content.replace(SHORTHAND_AT, (tag, userId, name) => {
+    if (!AAD_GUID.test(userId)) {
+      error ?? (error = `Mention user-id "${userId}" is not an Entra object id (GUID). Use the userId from list-team-members or list-chat-members.`);
+      return tag;
+    }
+    const id = nextId++;
+    added.push({
+      id,
+      mentionText: name,
+      mentioned: { user: { id: userId, displayName: name, userIdentityType: "aadUser" } }
+    });
+    return `<at id="${id}">${name}</at>`;
+  });
+  if (error) return { body, error };
+  if (HAS_SHORTHAND.test(rewritten)) {
+    return {
+      body,
+      error: 'Unsupported mention tag form. Write <at user-id="<guid>">Name</at> with double quotes, no other attributes and plain text inside.'
+    };
+  }
+  return {
+    body: { ...body, body: { ...itemBody, content: rewritten }, mentions: [...existing, ...added] }
+  };
+}
 function bodyForRecipientWalk(body) {
   if (typeof body !== "string") return body;
   if (!/^\s*[{[]/.test(body)) return void 0;
@@ -1730,6 +1787,16 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
         );
       }
     }
+    if (MENTION_SHORTHAND_TOOLS.has(tool.alias)) {
+      const rewritten = rewriteMentionShorthand(body);
+      if (rewritten.error) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: rewritten.error }) }],
+          isError: true
+        };
+      }
+      body = rewritten.body;
+    }
     if (TOP_UNSUPPORTED_DELTA_TOOLS.has(tool.alias)) {
       delete queryParams["$top"];
     }
@@ -2588,5 +2655,6 @@ export {
   isDestructiveOperation,
   registerDiscoveryTools,
   registerGraphTools,
+  rewriteMentionShorthand,
   scoreDiscoveryQuery
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softeria/ms-365-mcp-server",
   "mcpName": "io.github.Softeria/ms-365-mcp-server",
-  "version": "0.167.0",
+  "version": "0.168.0",
   "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/endpoints.json

@@ -1759,7 +1759,8 @@
     "method": "patch",
     "toolName": "update-chat-message",
     "presets": ["teams", "work"],
-    "workScopes": ["Chat.ReadWrite"]
+    "workScopes": ["Chat.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/chats/{chat-id}/messages/{chatMessage-id}/hostedContents",
@@ -1775,7 +1776,7 @@
     "toolName": "send-chat-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChatMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/me/joinedTeams",
@@ -1878,7 +1879,8 @@
     "method": "patch",
     "toolName": "update-channel-message",
     "presets": ["teams", "work"],
-    "workScopes": ["ChannelMessage.ReadWrite"]
+    "workScopes": ["ChannelMessage.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/hostedContents",
@@ -1894,7 +1896,7 @@
     "toolName": "send-channel-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChannelMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
@@ -1902,7 +1904,7 @@
     "toolName": "reply-to-channel-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChannelMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
@@ -1916,7 +1918,8 @@
     "method": "patch",
     "toolName": "update-channel-message-reply",
     "presets": ["teams", "work"],
-    "workScopes": ["ChannelMessage.ReadWrite"]
+    "workScopes": ["ChannelMessage.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/teams/{team-id}/members",
@@ -1982,7 +1985,7 @@
     "toolName": "reply-to-chat-message",
     "presets": ["teams", "work"],
     "workScopes": ["ChatMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/chats/{chat-id}/messages/{chatMessage-id}/setReaction",