feat: Add tool annotations for improved LLM tool understanding (#210)

* feat: Add tool annotations for improved LLM tool understanding

Add readOnlyHint and title annotations to all 13 tools to help
LLMs better understand tool behavior and make safer decisions.

Changes:
- Added annotations property to Tool interface
- Added readOnlyHint: true to all read-only tools
- Added title annotations for human-readable display
- Updated server.tool() call to pass annotations to MCP SDK

All tools are read-only operations:
- fetch_documentation / fetch_*_docs (fetches docs)
- search_documentation / search_*_docs (searches docs)
- search_code / search_*_code (searches code)
- fetch_generic_url_content (fetches URL content)
- match_common_libs_owner_repo_mapping (library lookup)
- ThreeJS-specific tools (reference docs, content fetch)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: Remove unnecessary type assertions per review

Remove explicit 'as ToolAnnotations' type casts that TypeScript can infer
from the Tool interface. This follows best practices by letting TypeScript
handle type checking naturally rather than using explicit assertions.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: triepod-ai <noreply@github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

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,
+      },
     },
   ];
 }

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,
+        },
       },
       {
         name: searchToolName,
@@ -51,6 +56,10 @@ class DefaultRepoHandler implements RepoHandler {
             ctx,
           });
         },
+        annotations: {
+          title: "Search Documentation",
+          readOnlyHint: true,
+        },
       },
       {
         name: codeSearchToolName,
@@ -75,6 +84,10 @@ class DefaultRepoHandler implements RepoHandler {
             ctx,
           });
         },
+        annotations: {
+          title: "Search Code",
+          readOnlyHint: true,
+        },
       },
     ];
   }

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,
+        },
       },
       {
         name: "fetch_generic_documentation",
@@ -102,6 +107,10 @@ class GenericRepoHandler implements RepoHandler {
           };
           return fetchDocumentation({ repoData, env, ctx });
         },
+        annotations: {
+          title: "Fetch Generic Documentation",
+          readOnlyHint: true,
+        },
       },
       {
         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,
+        },
       },
       {
         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,
+        },
       },
     ];
   }

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,
+      },
     };
 
     // 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,
+        },
       },
       {
         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,
+        },
       },
       {
         name: "search_threejs_documentation",
@@ -66,6 +75,10 @@ class ThreejsRepoHandler implements RepoHandler {
             fallbackSearch: noopFallbackSearch,
           });
         },
+        annotations: {
+          title: "Search Three.js Documentation",
+          readOnlyHint: true,
+        },
       },
       {
         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,
+        },
       },
     ];
   }

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,
       );
     });
   }