Skip to content

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

Open
bryankthompson wants to merge 1 commit intozcaceres:mainfrom
bryankthompson:feat/add-tool-annotations
Open

feat: Add tool annotations for improved LLM tool understanding#39
bryankthompson wants to merge 1 commit intozcaceres:mainfrom
bryankthompson:feat/add-tool-annotations

Conversation

@bryankthompson
Copy link

Summary

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

Changes

  • Bump @modelcontextprotocol/sdk from 1.0.1 to ^1.7.0 for annotation support
  • Bump zod from ^3.24.1 to ^3.25.0 for SDK compatibility
  • Added readOnlyHint: true to all 10 tools (pure converters, no side effects)
  • Added openWorldHint: true to URL-based tools that fetch external content:
    • youtube-to-markdown
    • bing-search-to-markdown
    • webpage-to-markdown
  • Added title annotations for human-readable display

Why This Matters

  • Annotations provide semantic metadata that helps LLMs understand tool behavior
  • LLMs can make better decisions about when to use tools and in what order
  • readOnlyHint: true enables MCP clients to auto-approve safe operations
  • openWorldHint: true signals tools that access external resources

Testing

  • pnpm run build succeeds
  • Live verification: Started server and confirmed tools/list returns annotations
  • All 10 tools have correct annotations

Before/After

Before:

{
  "name": "youtube-to-markdown",
  "description": "Convert a YouTube video to markdown..."
}

After:

{
  "name": "youtube-to-markdown",
  "description": "Convert a YouTube video to markdown...",
  "annotations": {
    "title": "YouTube to Markdown",
    "readOnlyHint": true,
    "openWorldHint": true
  }
}

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

Changes:
- Bump @modelcontextprotocol/sdk from 1.0.1 to ^1.7.0 for annotation support
- Bump zod from ^3.24.1 to ^3.25.0 for SDK compatibility
- Added readOnlyHint: true to all 10 tools (pure converters)
- Added openWorldHint: true to URL-based tools (youtube, bing, webpage)
- Added human-readable title annotations to all tools

This improves tool safety metadata for MCP clients.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant