06. Tools in MCP

Chapter 6 of 22 · 20 min

KEY INSIGHT

Tools are the action layer of MCPΓÇöeach tool defines a schema that clients use to construct valid execution requests. Tools in MCP enable AI applications to perform operations. Where resources read data, tools modify state. Every tool has a name, description, and JSON Schema defining its parameters. **Tool Definition:** ```python from mcp.types import Tool list_tools_tool = Tool( name="list_files", description="List files in a directory matching a pattern", inputSchema={ "type": "object", "properties": { "directory": { "type": "string", "description": "Directory to list files from" }, "pattern": { "type": "string", "description": "Glob pattern to filter files" } }, "required": ["directory"] } ) ``` **Tool Execution:** The `call_tool` handler receives the tool name and arguments map. ```python @app.call_tool() async def call_tool(name: str, arguments: dict) -> str | list[ContentBlock]: match name: case "list_files": return list_directory( arguments.get("directory"), arguments.get("pattern", "*") ) case "read_file": return read_file_content(arguments.get("path")) case _: raise ValueError(f"Tool not found: {name}") ``` **Return Types:** Tools can return strings, structured data, or content blocks. Content blocks enable mixed return types. ```python from mcp.types import ImageContent, TextContent @app.call_tool() async def call_tool(name: str, arguments: dict): if name == "generate_chart": chart_data = generate_chart_data(arguments) return [ TextContent(type="text", text="Chart generated successfully"), ImageContent( type="image", data=chart_data["base64"], mimeType="image/png" ) ] ``` **Error Handling:** Tool errors should be descriptive. Return error information that clients can display to users. ```python @app.call_tool() async def call_tool(name: str, arguments: dict): try: return execute_tool(name, arguments) except PermissionError as e: raise ToolError(f"Permission denied: {e}") except FileNotFoundError as e: raise ToolError(f"File not found: {e}") ``` **Schema Validation:** The inputSchema defines what clients send. Server implementations should validate incoming arguments against the schema. ```python import jsonschema @app.call_tool() async def call_tool(name: str, arguments: dict): tool = get_tool_definition(name) try: jsonschema.validate(arguments, tool.inputSchema) except jsonschema.ValidationError as e: raise ToolError(f"Invalid arguments: {e.message}") # proceed with execution ``` **Tool Discovery:** Clients call `tools/list` to discover available tools and their schemas. Servers should return complete, accurate schemas that clients can use for input validation and user interface generation.

EXERCISE

Implement a tool server with three tools: (1) get_weather taking a city parameter, (2) send_email taking to, subject, and body parameters, (3) calculate taking two numbers and an operation ("add", "subtract", "multiply", "divide"). Return appropriate error messages for invalid inputs.