fix: clarify MCP doc tool routing for Glama

packages/mcp/src/__tests__/docs.test.ts

@@ -193,6 +193,33 @@ describe("MCP Docs Tools", () => {
       expect(toolNames).toContain("translate_api_docs");
       expect(toolNames).toContain("create_bilingual_doc");
     });
+
+    it("should describe markdown and API-doc routing clearly for MCP discovery", async () => {
+      const { registerDocsTools } = await import("../tools/docs.js");
+      const mockServer = {
+        registerTool: vi.fn(),
+        tool: vi.fn(),
+      };
+
+      registerDocsTools(mockServer as any, { registry: mockRegistry });
+
+      const configs = new Map(
+        vi.mocked(mockServer.registerTool).mock.calls.map(([name, config]) => [
+          name,
+          config as { description: string },
+        ])
+      );
+      const markdown = configs.get("translate_markdown")!.description.toLowerCase();
+      const apiDocs = configs.get("translate_api_docs")!.description.toLowerCase();
+
+      expect(markdown).toContain("ordinary markdown");
+      expect(markdown).toContain("use translate_readme");
+      expect(markdown).toContain("use translate_api_docs");
+      expect(apiDocs).toContain("endpoint");
+      expect(apiDocs).toContain("http methods");
+      expect(apiDocs).toContain("status codes");
+      expect(apiDocs).toContain("not general markdown");
+    });
   });
 
   describe("translate_markdown tool", () => {

packages/mcp/src/__tests__/translator.test.ts

@@ -197,6 +197,31 @@ describe("MCP Translator Tools", () => {
       expect(toolNames).toContain("list_dialects");
       expect(toolNames).toContain("research_regional_term");
     });
+
+    it("should describe translate_readme as README-specific for MCP discovery", async () => {
+      const { registerTranslatorTools } = await import("../tools/translator.js");
+      const mockServer = {
+        registerTool: vi.fn(),
+        tool: vi.fn(),
+      };
+
+      registerTranslatorTools(mockServer as any, { registry: mockRegistry });
+
+      const tools = new Map(
+        vi.mocked(mockServer.registerTool).mock.calls.map(([name, config]) => [
+          name,
+          config as { description: string },
+        ])
+      );
+      const description = tools.get("translate_readme")!.description.toLowerCase();
+
+      expect(description).toContain("repository readme");
+      expect(description).toContain("badges");
+      expect(description).toContain("install");
+      expect(description).toContain("license");
+      expect(description).toContain("use translate_markdown");
+      expect(description).toContain("use translate_api_docs");
+    });
   });
 
   describe("translate_text tool", () => {

packages/mcp/src/tools/docs.ts

@@ -492,7 +492,7 @@ export function registerDocsTools(
     {
       title: "Translate Markdown file",
       description:
-        "Read a Markdown file, translate translatable prose into a Spanish dialect, and return reconstructed Markdown while preserving code blocks, links, and non-translatable sections. Reads the file only; it does not overwrite the source file.",
+        "Read an ordinary Markdown file, translate translatable prose into a Spanish dialect, and return reconstructed Markdown while preserving code blocks, links, and non-translatable sections. Use this for general Markdown pages, articles, or docs; use translate_readme for repository README files with badges/install/license sections, and use translate_api_docs for endpoint/reference documentation. Reads the file only, may call the selected translation provider under the configured rate limiter, and does not overwrite the source file.",
       inputSchema: {
         filePath: z.string().min(1).describe("Path to the Markdown file to read and translate."),
         dialect: dialectSchema.optional().describe("Target Spanish dialect code. Defaults to es-ES when omitted; examples include es-MX, es-AR, and es-CO."),
@@ -542,7 +542,7 @@ export function registerDocsTools(
     {
       title: "Translate API documentation",
       description:
-        "Read API documentation Markdown and translate prose into a Spanish dialect with documentation context for tables, lists, endpoints, and technical terms. Returns translated Markdown and errors; it does not modify the file.",
+        "Read API documentation Markdown and translate prose into a Spanish dialect with documentation context for endpoints, HTTP methods, route paths, parameters, status codes, code examples, tables, lists, and technical terms. Use this for API/reference docs, not general Markdown or repository README pages. Returns translated Markdown and errors; it may call the selected translation provider under the configured rate limiter and does not modify the file.",
       inputSchema: {
         filePath: z.string().min(1).describe("Path to the API documentation Markdown file to read and translate."),
         dialect: dialectSchema.optional().describe("Target Spanish dialect code. Defaults to es-ES when omitted."),

packages/mcp/src/tools/translator.ts

@@ -141,7 +141,7 @@ export function registerTranslatorTools(
     {
       title: "Translate README Markdown",
       description:
-        "Read a README Markdown file, translate translatable prose into a Spanish dialect, and return translated Markdown with code blocks and structure preserved. Reads the file only; it does not overwrite the README.",
+        "Read a repository README Markdown file, translate translatable prose into a Spanish dialect, and return translated Markdown while preserving badges, install commands, usage examples, contribution sections, license text, code blocks, and structure. Use translate_markdown for ordinary Markdown pages, and use translate_api_docs for endpoint/reference documentation. Reads the file only, may call the selected translation provider under the configured rate limiter, and does not overwrite the README.",
       inputSchema: {
         filePath: z.string().min(1).describe("Path to the README Markdown file to read and translate."),
         dialect: dialectSchema.optional().describe("Target Spanish dialect code. Defaults to es-ES when omitted."),