Describe the feature

The AWS MCP Lambda Handler currently does not support MCP tool annotations, which are part of the official MCP specification. Tool annotations provide additional metadata about a tool's behavior, helping clients understand how to present and manage tools appropriately.

According to the MCP specification, tool annotations include:

• title (string) - A human-readable title for the tool
• readOnlyHint (boolean) - Indicates if the tool doesn't modify its environment
• destructiveHint (boolean) - If the tool may perform destructive updates
• idempotentHint (boolean) - If calling the tool repeatedly with same arguments has no additional effect
• openWorldHint (boolean) - If the tool may interact with external entities

These annotations provide UX-specific information without affecting model context and help clients categorize and present tools appropriately.

Use Case

Tool annotations are essential for several scenarios:

1. Client UI/UX Enhancement

# Read-only tools can be presented with different visual cues
@mcp_server.tool(annotations={"readOnlyHint": True, "title": "Weather Info"})
def get_weather(city: str) -> str:
    """Get current weather information."""
    return f"Weather in {city}: sunny"

2. Destructive Operation Warnings

# Destructive tools can trigger additional confirmation prompts
@mcp_server.tool(annotations={"destructiveHint": True, "title": "Delete File"})
def delete_file(filepath: str) -> str:
    """Delete a file from the system."""
    # Implementation

3. Idempotent Operation Optimization

# Clients can optimize repeated calls for idempotent operations
@mcp_server.tool(annotations={"idempotentHint": True, "title": "Create User"})
def create_user_if_not_exists(email: str) -> str:
    """Create user account if it doesn't already exist."""
    # Implementation

4. Closed vs Open World Systems

# Internal database operations vs external API calls
@mcp_server.tool(annotations={"openWorldHint": False, "title": "Query Database"})
def query_internal_db(query: str) -> str:
    """Query internal company database."""
    # Implementation

@mcp_server.tool(annotations={"openWorldHint": True, "title": "Web Search"})
def web_search(query: str) -> str:
    """Search the web for information."""
    # Implementation

5. Client-Specific Tool Management - Different MCP clients (Claude Desktop, Cursor, etc.) can use annotations to provide appropriate user experiences, warnings, and approval workflows.

Proposed Solution

Add support for tool annotations in the @mcp_server.tool() decorator and any future add_tool() method:

Current Implementation:

@mcp_server.tool()
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"Weather in {city}: sunny"

Proposed Implementation:

@mcp_server.tool(
    annotations={
        "title": "Weather Information",
        "readOnlyHint": True,
        "destructiveHint": False,
        "idempotentHint": True,
        "openWorldHint": True
    }
)
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"Weather in {city}: sunny"

Other Information

Implementation Requirements:

• Support all five standard MCP tool annotations
• Validate annotation types (boolean for hints, string for title)
• Include annotations in the tool manifest returned by tools/list
• Maintain backward compatibility (annotations optional)
• Follow MCP specification defaults (readOnlyHint=false, destructiveHint=true, etc.)

Other Information

MCP Specification Compliance: This feature is required for full compliance with the MCP specification. The current implementation returns incomplete tool definitions without annotations.

Framework Comparison: Other MCP frameworks already support annotations:

• FastMCP supports annotations via the annotations parameter in @mcp.tool()
• The official MCP Python SDK includes annotation support

Expected Tool Definition Structure:

{
  "name": "get_weather",
  "description": "Get weather for a city.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": {"type": "string"}
    },
    "required": ["city"]
  },
  "annotations": {
    "title": "Weather Information",
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": true
  }
}

Testing Requirements:

• Verify annotations appear correctly in tool manifest
• Validate annotation type checking and defaults
• Test backward compatibility with existing tools (no annotations)
• Ensure annotations don't affect tool execution, only metadata

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change