feat: add tool annotations for improved LLM understanding

[bryankthompson]

Summary

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

Changes

• Added destructiveHint: true to sandbox management tools:

  • sandbox_initialize - creates Docker containers
  • sandbox_exec - executes shell commands
  • run_js - runs JavaScript code
  • sandbox_stop - terminates containers
  • run_js_ephemeral - runs code in temporary containers

• Added readOnlyHint: true to query tools:

  • get_dependency_types - fetches TypeScript definitions
  • search_npm_packages - searches npm registry

• Added openWorldHint: true to tools that access external resources (Docker, npm registry)

• Added title annotations for human-readable display

Why This Matters

Tool annotations provide semantic metadata that helps MCP clients:

• Auto-approve read-only tools without user confirmation
• Show appropriate warnings for destructive operations
• Make safer decisions about tool execution order

Testing

• Server builds successfully (npm run build)
• Linter passes for modified files (npm run lint)
• Annotations correctly placed in compiled output
• No type errors in TypeScript compilation

Note: Live server verification requires Node.js 23+ (for import ... with { type: 'json' } syntax). Build verification confirms annotations are correctly structured.

Before/After

Before:

server.tool(
  'search_npm_packages',
  'Search for npm packages...',
  SearchNpmPackagesToolSchema.shape,
  searchNpmPackages
);

After:

server.tool(
  'search_npm_packages',
  'Search for npm packages...',
  SearchNpmPackagesToolSchema.shape,
  {
    title: 'Search NPM Packages',
    readOnlyHint: true,
    openWorldHint: true,
  },
  searchNpmPackages
);

---

🤖 Generated with Claude Code