feat: Add tool annotations for improved LLM tool understanding

src/api/tools/index.ts

@@ -3,6 +3,7 @@ import { getRepoData } from "../../shared/repoData.js";
 import { fetchUrlContent } from "./commonTools.js";
 import { getHandlerByRepoData } from "./repoHandlers/handlers.js";
 import type { Tool } from "./repoHandlers/RepoHandler.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 
 export function getMcpTools(
   env: Env,
@@ -25,6 +26,10 @@ export function getMcpTools(
       cb: async ({ url }) => {
         return fetchUrlContent({ url, env });
       },
+      annotations: {
+        title: "Fetch URL Content",
+        readOnlyHint: true,
+      } as ToolAnnotations,
     },
   ];
 }

src/api/tools/repoHandlers/DefaultRepoHandler.ts

@@ -13,6 +13,7 @@ import {
 import { z } from "zod";
 import type { RepoData } from "../../../shared/repoData.js";
 import type { RepoHandler, Tool } from "./RepoHandler.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 
 class DefaultRepoHandler implements RepoHandler {
   name = "default";
@@ -34,6 +35,10 @@ class DefaultRepoHandler implements RepoHandler {
         cb: async () => {
           return fetchDocumentation({ repoData, env, ctx });
         },
+        annotations: {
+          title: "Fetch Documentation",
+          readOnlyHint: true,
+        } as ToolAnnotations,
       },
       {
         name: searchToolName,
@@ -51,6 +56,10 @@ class DefaultRepoHandler implements RepoHandler {
             ctx,
           });
         },
+        annotations: {
+          title: "Search Documentation",
+          readOnlyHint: true,
+        } as ToolAnnotations,
       },
       {
         name: codeSearchToolName,
@@ -75,6 +84,10 @@ class DefaultRepoHandler implements RepoHandler {
             ctx,
           });
         },
+        annotations: {
+          title: "Search Code",
+          readOnlyHint: true,
+        } as ToolAnnotations,
       },
     ];
   }

src/api/tools/repoHandlers/GenericRepoHandler.ts

@@ -8,6 +8,7 @@ import {
 } from "../commonTools.js";
 import { incrementRepoViewCount } from "../../utils/badge.js";
 import rawMapping from "./generic/static-mapping.json";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 
 const badgeCountAllowedRepos = ["mcp-ui", "git-mcp"];
 
@@ -82,6 +83,10 @@ class GenericRepoHandler implements RepoHandler {
             ],
           };
         },
+        annotations: {
+          title: "Match Library to Repository",
+          readOnlyHint: true,
+        } as ToolAnnotations,
       },
       {
         name: "fetch_generic_documentation",
@@ -102,6 +107,10 @@ class GenericRepoHandler implements RepoHandler {
           };
           return fetchDocumentation({ repoData, env, ctx });
         },
+        annotations: {
+          title: "Fetch Generic Documentation",
+          readOnlyHint: true,
+        } as ToolAnnotations,
       },
       {
         name: "search_generic_documentation",
@@ -125,6 +134,10 @@ class GenericRepoHandler implements RepoHandler {
           };
           return searchRepositoryDocumentation({ repoData, query, env, ctx });
         },
+        annotations: {
+          title: "Search Generic Documentation",
+          readOnlyHint: true,
+        } as ToolAnnotations,
       },
       {
         name: "search_generic_code",
@@ -154,6 +167,10 @@ class GenericRepoHandler implements RepoHandler {
           };
           return searchRepositoryCode({ repoData, query, page, env, ctx });
         },
+        annotations: {
+          title: "Search Generic Code",
+          readOnlyHint: true,
+        } as ToolAnnotations,
       },
     ];
   }

src/api/tools/repoHandlers/ReactRouterRepoHandler.ts

@@ -8,6 +8,7 @@ import type { RepoData } from "../../../shared/repoData.js";
 import type { RepoHandler, Tool } from "./RepoHandler.js";
 import { getDefaultRepoHandler } from "./DefaultRepoHandler.js";
 import { z } from "zod";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 
 class ReactRouterRepoHandler implements RepoHandler {
   name = "react-router";
@@ -34,6 +35,10 @@ class ReactRouterRepoHandler implements RepoHandler {
           ctx,
         });
       },
+      annotations: {
+        title: "Search Documentation",
+        readOnlyHint: true,
+      } as ToolAnnotations,
     };
 
     // Filter out the default search tool and add our specific implementation

src/api/tools/repoHandlers/RepoHandler.ts

@@ -1,10 +1,12 @@
 import type { RepoData } from "../../../shared/repoData.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 
 export interface Tool {
   name: string;
   description: string;
   paramsSchema: any;
   cb: (args: any) => Promise<any>;
+  annotations?: ToolAnnotations;
 }
 
 export interface RepoHandler {

src/api/tools/repoHandlers/ThreejsRepoHandler.ts

@@ -7,6 +7,7 @@ import {
   fetchThreeJsUrlsAsMarkdown,
 } from "./threejs/utils.js";
 import { searchRepositoryDocumentation } from "../commonTools.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 
 const GET_REFERENCE_DOCS_LIST_TOOL_NAME = "get_threejs_reference_docs_list";
 const GET_SPECIFIC_DOCS_CONTENT_TOOL_NAME = "get_threejs_specific_docs_content";
@@ -25,6 +26,10 @@ class ThreejsRepoHandler implements RepoHandler {
         cb: async () => {
           return await getReferenceDocsListAsMarkdown({ env });
         },
+        annotations: {
+          title: "Get Three.js Reference Docs List",
+          readOnlyHint: true,
+        } as ToolAnnotations,
       },
       {
         name: GET_SPECIFIC_DOCS_CONTENT_TOOL_NAME,
@@ -47,6 +52,10 @@ class ThreejsRepoHandler implements RepoHandler {
             documents: args.documents,
           });
         },
+        annotations: {
+          title: "Get Three.js Specific Docs Content",
+          readOnlyHint: true,
+        } as ToolAnnotations,
       },
       {
         name: "search_threejs_documentation",
@@ -66,6 +75,10 @@ class ThreejsRepoHandler implements RepoHandler {
             fallbackSearch: noopFallbackSearch,
           });
         },
+        annotations: {
+          title: "Search Three.js Documentation",
+          readOnlyHint: true,
+        } as ToolAnnotations,
       },
       {
         name: "fetch_threejs_urls_inside_docs",
@@ -87,6 +100,10 @@ class ThreejsRepoHandler implements RepoHandler {
         cb: async ({ urls }) => {
           return await fetchThreeJsUrlsAsMarkdown(urls);
         },
+        annotations: {
+          title: "Fetch Three.js URLs Inside Docs",
+          readOnlyHint: true,
+        } as ToolAnnotations,
       },
     ];
   }

src/index.ts

@@ -103,6 +103,7 @@ export class MyMCP extends McpAgent {
         withViewTracking(env, ctx, repoData, async (args: any) => {
           return tool.cb(args);
         }),
+        tool.annotations ? { annotations: tool.annotations } : undefined,
       );
     });
   }