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

triepod-ai · 2025-12-21T19:24:26Z

Summary

Adds MCP tool annotations (readOnlyHint, title) to all 13 tools to help LLMs better understand tool behavior and make safer decisions about tool execution.

Changes

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

Tools Annotated

Tool	Title	ReadOnly
`fetch_*_documentation`	Fetch Documentation	✅
`search_*_documentation`	Search Documentation	✅
`search_*_code`	Search Code	✅
`fetch_generic_url_content`	Fetch URL Content	✅
`fetch_generic_documentation`	Fetch Generic Documentation	✅
`search_generic_documentation`	Search Generic Documentation	✅
`search_generic_code`	Search Generic Code	✅
`match_common_libs_owner_repo_mapping`	Match Library to Repository	✅
`get_threejs_reference_docs_list`	Get Three.js Reference Docs List	✅
`get_threejs_specific_docs_content`	Get Three.js Specific Docs Content	✅
`search_threejs_documentation`	Search Three.js Documentation	✅
`fetch_threejs_urls_inside_docs`	Fetch Three.js URLs Inside Docs	✅

Why This Matters

Tool annotations provide semantic metadata that helps LLMs:

Understand tool behavior beyond just descriptions
Make better decisions about when and in what order to use tools
Enable safer tool execution by distinguishing read-only from destructive operations
Display human-readable tool titles in UIs

Testing

Project builds successfully (pnpm run build)
TypeScript type checking passes (npx tsc --noEmit)
Tool-related tests pass (Tools Module tests: 4/4 passing)
Pre-existing test failure (threejs/utils.test.ts) is unrelated to these changes (network API issue)

Before/After

Before:

{
  name: "fetch_documentation",
  description: "Fetch entire documentation file..."
  // No annotations
}

After:

{
  name: "fetch_documentation",
  description: "Fetch entire documentation file...",
  annotations: {
    title: "Fetch Documentation",
    readOnlyHint: true
  }
}

🤖 Generated with Claude Code

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 <[email protected]>

Copilot

Pull request overview

This PR enhances tool definitions by adding MCP (Model Context Protocol) annotations to provide semantic metadata that helps LLMs better understand tool behavior. The changes add title and readOnlyHint properties to all 13 tools in the codebase.

Key changes:

Extended the Tool interface to support optional ToolAnnotations from the MCP SDK
Added readOnlyHint: true annotation to all tools to mark them as safe, read-only operations
Added human-readable title annotations to improve tool display in UIs
Updated tool registration logic to conditionally pass annotations to the MCP SDK's server.tool() method

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
src/api/tools/repoHandlers/RepoHandler.ts	Added optional `annotations` property to the `Tool` interface
src/index.ts	Updated tool registration to conditionally pass annotations to `server.tool()`
src/api/tools/index.ts	Added annotations to the `fetch_generic_url_content` tool
src/api/tools/repoHandlers/DefaultRepoHandler.ts	Added annotations to 3 default tools (fetch, search documentation, search code)
src/api/tools/repoHandlers/GenericRepoHandler.ts	Added annotations to 4 generic tools (match library, fetch/search documentation, search code)
src/api/tools/repoHandlers/ReactRouterRepoHandler.ts	Added annotations to the React Router search documentation tool
src/api/tools/repoHandlers/ThreejsRepoHandler.ts	Added annotations to 4 Three.js-specific tools (reference docs, search, URL fetch)

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-21T19:28:49Z

src/api/tools/repoHandlers/ThreejsRepoHandler.ts

+        annotations: {
+          title: "Search Three.js Documentation",
+          readOnlyHint: true,
+        } as ToolAnnotations,


The type assertion as ToolAnnotations is unnecessary here. The object literal already satisfies the ToolAnnotations type, and explicit type casting can hide type mismatches. Remove the type assertion and let TypeScript infer the type naturally.

Copilot · 2025-12-21T19:28:49Z

src/api/tools/repoHandlers/ThreejsRepoHandler.ts

+        annotations: {
+          title: "Fetch Three.js URLs Inside Docs",
+          readOnlyHint: true,
+        } as ToolAnnotations,


The type assertion as ToolAnnotations is unnecessary here. The object literal already satisfies the ToolAnnotations type, and explicit type casting can hide type mismatches. Remove the type assertion and let TypeScript infer the type naturally.

Copilot · 2025-12-21T19:28:50Z

src/api/tools/repoHandlers/GenericRepoHandler.ts

+        annotations: {
+          title: "Match Library to Repository",
+          readOnlyHint: true,
+        } as ToolAnnotations,


The type assertion as ToolAnnotations is unnecessary here. The object literal already satisfies the ToolAnnotations type, and explicit type casting can hide type mismatches. Remove the type assertion and let TypeScript infer the type naturally.

Copilot · 2025-12-21T19:28:50Z

src/api/tools/repoHandlers/DefaultRepoHandler.ts

+        annotations: {
+          title: "Search Code",
+          readOnlyHint: true,
+        } as ToolAnnotations,


The type assertion as ToolAnnotations is unnecessary here. The object literal already satisfies the ToolAnnotations type, and explicit type casting can hide type mismatches. Remove the type assertion and let TypeScript infer the type naturally.

Copilot · 2025-12-21T19:28:50Z

src/api/tools/index.ts

+      annotations: {
+        title: "Fetch URL Content",
+        readOnlyHint: true,
+      } as ToolAnnotations,


The type assertion as ToolAnnotations is unnecessary here. The object literal already satisfies the ToolAnnotations type, and explicit type casting can hide type mismatches. Remove the type assertion and let TypeScript infer the type naturally.

Suggested change

} as ToolAnnotations,

},

Copilot · 2025-12-21T19:28:52Z

src/api/tools/repoHandlers/GenericRepoHandler.ts

+        annotations: {
+          title: "Fetch Generic Documentation",
+          readOnlyHint: true,
+        } as ToolAnnotations,


The type assertion as ToolAnnotations is unnecessary here. The object literal already satisfies the ToolAnnotations type, and explicit type casting can hide type mismatches. Remove the type assertion and let TypeScript infer the type naturally.

Copilot · 2025-12-21T19:28:52Z

src/api/tools/repoHandlers/GenericRepoHandler.ts

+        annotations: {
+          title: "Search Generic Documentation",
+          readOnlyHint: true,
+        } as ToolAnnotations,


The type assertion as ToolAnnotations is unnecessary here. The object literal already satisfies the ToolAnnotations type, and explicit type casting can hide type mismatches. Remove the type assertion and let TypeScript infer the type naturally.

Copilot · 2025-12-21T19:28:52Z

src/api/tools/repoHandlers/GenericRepoHandler.ts

+        annotations: {
+          title: "Search Generic Code",
+          readOnlyHint: true,
+        } as ToolAnnotations,


The type assertion as ToolAnnotations is unnecessary here. The object literal already satisfies the ToolAnnotations type, and explicit type casting can hide type mismatches. Remove the type assertion and let TypeScript infer the type naturally.

Copilot · 2025-12-21T19:28:52Z

src/api/tools/repoHandlers/DefaultRepoHandler.ts

+        annotations: {
+          title: "Fetch Documentation",
+          readOnlyHint: true,
+        } as ToolAnnotations,


The type assertion as ToolAnnotations is unnecessary here. The object literal already satisfies the ToolAnnotations type, and explicit type casting can hide type mismatches. Remove the type assertion and let TypeScript infer the type naturally.

Copilot · 2025-12-21T19:28:52Z

src/api/tools/repoHandlers/DefaultRepoHandler.ts

+        annotations: {
+          title: "Search Documentation",
+          readOnlyHint: true,
+        } as ToolAnnotations,


The type assertion as ToolAnnotations is unnecessary here. The object literal already satisfies the ToolAnnotations type, and explicit type casting can hide type mismatches. Remove the type assertion and let TypeScript infer the type naturally.

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 <[email protected]>

Copilot AI review requested due to automatic review settings December 21, 2025 19:24

Copilot started reviewing on behalf of triepod-ai December 21, 2025 19:24 View session

Copilot AI reviewed Dec 21, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

triepod-ai commented Dec 21, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Dec 21, 2025

Uh oh!

Copilot AI Dec 21, 2025

Uh oh!

Copilot AI Dec 21, 2025

Uh oh!

Copilot AI Dec 21, 2025

Uh oh!

Copilot AI Dec 21, 2025

Uh oh!

Copilot AI Dec 21, 2025

Uh oh!

Copilot AI Dec 21, 2025

Uh oh!

Copilot AI Dec 21, 2025

Uh oh!

Copilot AI Dec 21, 2025

Uh oh!

Copilot AI Dec 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

triepod-ai commented Dec 21, 2025

Summary

Changes

Tools Annotated

Why This Matters

Testing

Before/After

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants