Call Tool

​

Overview

The tools/call method executes a specific tool with provided arguments. Tools perform operations like querying databases, calling APIs, or processing data. All tools require proper OAuth authentication and parameter validation.

​

Prerequisites

1. Session Initialization: Complete initialize → notifications/initialized flow
2. Authentication: Valid OAuth token or PAT with mcp.tools.execute scope
3. Session ID: Include Mcp-Session-Id header from initialization
4. Tool Discovery: Use tools/list to get available tools and their parameters

​

Request Format

{
  "jsonrpc": "2.0",
  "id": "tool-call-123",
  "method": "tools/call",
  "params": {
    "name": "get_contacts",
    "arguments": {
      "limit": 10,
      "filter": "john@example.com"
    }
  }
}

​

Request Parameters

​

Response Format

​

Example Responses

{
  "jsonrpc": "2.0",
  "id": "tool-call-123",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 3 contacts matching your criteria:\n\n1. John Doe (john@example.com)\n2. Jane Smith (jane@example.com)\n3. John Johnson (jj@example.com)"
      }
    ]
  }
}

​

Tool Execution Results

​

Response Structure

Our implementation follows JSON-RPC 2.0 protocol with these patterns:

1. Success Response: Contains result field with tool output
2. Error Response: Contains error field with error details

​

Content Format

Tool results contain a content array with items of different types:

​

Error Handling Strategy

// Handle tool call responses
function handleToolResponse(response) {
  if (response.error) {
    // Protocol error (tool not found, invalid params, etc.)
    throw new ProtocolError(response.error);
  }

  if (response.result && response.result.content) {
    // Success case - tool executed
    return response.result.content;
  }

  // Unexpected response structure
  throw new Error("Unexpected response structure");
}

​

Implementation Notes

​

Response Validation

• JSON-RPC compliance: All responses follow JSON-RPC 2.0 format
• Content array: Success responses contain content array
• Flexible structure: Tests validate basic structure, not strict field requirements
• Error handling: Protocol errors vs tool execution handled through different response patterns

​

Tool Execution Environment

• Tools execute in controlled environment
• Results formatted as structured content
• Error conditions handled through JSON-RPC error responses
• OAuth validation applied before tool execution

​

OAuth and Permissions

​

Required OAuth Scope

• mcp.tools.execute: Required for all tool execution
• Tool-specific permissions: Additional filtering based on database permissions

​

Tool Access Control

• User-specific: Each user sees only their permitted tools
• Database-driven: Tool permissions stored and validated in database
• Session-bound: Permissions validated per session and tool call

​

Progress Tracking

For long-running tools, include a progress token:

{
  "jsonrpc": "2.0",
  "id": "bulk-operation",
  "method": "tools/call",
  "params": {
    "name": "bulk_data_import",
    "arguments": {
      "file_path": "/data/contacts.csv"
    },
    "_meta": {
      "progressToken": "import-progress-123"
    }
  }
}

​

Error Codes

​

Parameter Validation

Tools validate parameters against their inputSchema:

​

Required Parameters

• All parameters in required array must be provided
• Missing required parameters return -32602 error

​

Type Validation

• Parameters must match schema types (string, integer, number, boolean)
• Invalid types return -32602 error with details

​

Value Constraints

• Minimum/maximum values enforced for numbers
• String length limits applied where specified
• Enum values validated against allowed options

​

Implementation Notes

​

Request ID Requirements

• Must be unique within session
• Cannot be null (enforced by implementation)
• Used for progress notifications and error correlation

​

Session Validation

• Mcp-Session-Id header required after initialization
• Session must be active and authenticated
• Invalid session returns -32000 authentication error

​

Tool Execution Environment

• Tools execute in controlled environment
• Database connections managed per execution
• API rate limits applied per user/tool combination

​

Performance Considerations

• Tool execution may be rate-limited
• Long-running tools support cancellation via notifications/cancelled
• Results cached where appropriate

This method provides the core functionality for AI systems to interact with external services through controlled, authenticated tool execution.