Tools

Tools sind ein mächtiges Primitiv im Model Context Protocol (MCP), das Servern ermöglicht, ausführbare Funktionalität für Clients bereitzustellen. Durch Tools können LLMs mit externen Systemen interagieren, Berechnungen durchführen und Aktionen in der realen Welt ausführen.

Überblick

Tools in MCP ermöglichen es Servern, ausführbare Funktionen bereitzustellen, die von Clients aufgerufen und von LLMs zur Durchführung von Aktionen verwendet werden können. Wichtige Aspekte von Tools umfassen:

• Entdeckung: Clients können verfügbare Tools über den tools/list Endpunkt auflisten
• Aufruf: Tools werden über den tools/call Endpunkt aufgerufen, wo Server die angeforderte Operation durchführen und Ergebnisse zurückgeben
• Flexibilität: Tools können von einfachen Berechnungen bis hin zu komplexen API-Interaktionen reichen

Wie Ressourcen werden Tools durch eindeutige Namen identifiziert und können Beschreibungen enthalten, um ihre Verwendung zu leiten. Im Gegensatz zu Ressourcen repräsentieren Tools jedoch dynamische Operationen, die den Zustand modifizieren oder mit externen Systemen interagieren können.

Tool definition structure

Each tool is defined with the following structure:

{
  name: string;          // Unique identifier for the tool
  description?: string;  // Human-readable description
  inputSchema: {         // JSON Schema for the tool's parameters
    type: "object",
    properties: { ... }  // Tool-specific parameters
  }
}

Implementing tools

Here’s an example of implementing a basic tool in an MCP server:

// Define available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      description: "Add two numbers together",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      }
    }]
  };
});

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "calculate_sum") {
    const { a, b } = request.params.arguments;
    return {
      toolResult: a + b
    };
  }
  throw new Error("Tool not found");
});
```

@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="calculate_sum",
            description="Add two numbers together",
            inputSchema={
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"}
                },
                "required": ["a", "b"]
            }
        )
    ]

@app.call_tool()
async def call_tool(
    name: str,
    arguments: dict
) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
    if name == "calculate_sum":
        a = arguments["a"]
        b = arguments["b"]
        result = a + b
        return [types.TextContent(type="text", text=str(result))]
    raise ValueError(f"Tool not found: {name}")
```

Example tool patterns

Here are some examples of types of tools that a server could provide:

System operations

Tools that interact with the local system:

{
  name: "execute_command",
  description: "Run a shell command",
  inputSchema: {
    type: "object",
    properties: {
      command: { type: "string" },
      args: { type: "array", items: { type: "string" } }
    }
  }
}

API integrations

Tools that wrap external APIs:

{
  name: "github_create_issue",
  description: "Create a GitHub issue",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string" },
      body: { type: "string" },
      labels: { type: "array", items: { type: "string" } }
    }
  }
}

Data processing

Tools that transform or analyze data:

{
  name: "analyze_csv",
  description: "Analyze a CSV file",
  inputSchema: {
    type: "object",
    properties: {
      filepath: { type: "string" },
      operations: {
        type: "array",
        items: {
          enum: ["sum", "average", "count"]
        }
      }
    }
  }
}

Best practices

When implementing tools:

1. Provide clear, descriptive names and descriptions
2. Use detailed JSON Schema definitions for parameters
3. Include examples in tool descriptions to demonstrate how the model should use them
4. Implement proper error handling and validation
5. Use progress reporting for long operations
6. Keep tool operations focused and atomic
7. Document expected return value structures
8. Implement proper timeouts
9. Consider rate limiting for resource-intensive operations
10. Log tool usage for debugging and monitoring

Security considerations

When exposing tools:

Input validation

• Validate all parameters against the schema
• Sanitize file paths and system commands
• Validate URLs and external identifiers
• Check parameter sizes and ranges
• Prevent command injection

Access control

• Implement authentication where needed
• Use appropriate authorization checks
• Audit tool usage
• Rate limit requests
• Monitor for abuse

Error handling

• Don’t expose internal errors to clients
• Log security-relevant errors
• Handle timeouts appropriately
• Clean up resources after errors
• Validate return values

Tool discovery and updates

MCP supports dynamic tool discovery:

1. Clients can list available tools at any time
2. Servers can notify clients when tools change using notifications/tools/list_changed
3. Tools can be added or removed during runtime
4. Tool definitions can be updated (though this should be done carefully)

Error handling

Tool errors should be reported within the result object, not as MCP protocol-level errors. This allows the LLM to see and potentially handle the error. When a tool encounters an error:

1. Set isError to true in the result
2. Include error details in the content array

Here’s an example of proper error handling for tools:

This approach allows the LLM to see that an error occurred and potentially take corrective action or request human intervention.

Testing tools

A comprehensive testing strategy for MCP tools should cover:

• Functional testing: Verify tools execute correctly with valid inputs and handle invalid inputs appropriately
• Integration testing: Test tool interaction with external systems using both real and mocked dependencies
• Security testing: Validate authentication, authorization, input sanitization, and rate limiting
• Performance testing: Check behavior under load, timeout handling, and resource cleanup
• Error handling: Ensure tools properly report errors through the MCP protocol and clean up resources