feat: Add tool annotations support via runtime options

[bryankthompson]

Summary

This PR adds support for MCP tool annotations through a runtime options pattern, allowing users to add semantic hints to generated tools. This follows the existing WithExtraProperties() pattern and enables LLMs and MCP clients to better understand tool behavior.

Key changes:

• WithToolAnnotations() - New runtime option for specifying annotations
• ApplyToolAnnotations() - Helper function to apply annotations to a tool
• ApplyOptions() - Combined function for both annotations and extra properties
• Comprehensive unit tests (9 test cases covering all scenarios)
• New example demonstrating annotation usage

Usage Example

import "github.com/redpanda-data/protoc-gen-go-mcp/pkg/runtime"

// Apply annotations to generated tools
getItemTool := runtime.ApplyToolAnnotations(
    testdatamcp.TestService_GetItemTool,
    runtime.WithToolAnnotations(runtime.ToolAnnotationConfig{
        Title:        "Get Item",
        ReadOnlyHint: boolPtr(true),  // Tool only reads data
    }),
)

// Or combine with extra properties
tool := runtime.ApplyOptions(generatedTool,
    runtime.WithToolAnnotations(runtime.ToolAnnotationConfig{
        Title:         "API Tool",
        OpenWorldHint: boolPtr(true),
    }),
    runtime.WithExtraProperties(runtime.ExtraProperty{
        Name:        "api_key",
        Description: "API key for authentication",
        Required:    true,
    }),
)

Annotation Types Supported

Annotation	Type	Description
Title	string	Human-readable title for the tool
ReadOnlyHint	*bool	Tool does not modify its environment
DestructiveHint	*bool	Tool may perform destructive updates
IdempotentHint	*bool	Repeated calls have no additional effect
OpenWorldHint	*bool	Tool interacts with external entities

Test Plan

• All unit tests pass (go test ./pkg/runtime/...)
• Example builds successfully (go build ./examples/with-annotations/...)
• go vet passes
• No changes to existing tests required

Related

This implements support for the MCP tool annotations specification. The SDK (mcp-go v0.37.0) already supports mcp.ToolAnnotation - this PR makes it easy for users to apply annotations to generated tools.

🤖 Generated with Claude Code