MCP Tools Overview — MCP Tools

What Is MCP?

MCP is a protocol that standardises how LLMs describe and call tools. Each tool has a JSON Schema definition that the LLM uses to construct valid tool call requests. Octopus's MCPToolRegistry manages all registered tools per agent:

// MCP tool definition (what the LLM sees)
{
  "name":        "get_employee_leave_balance",
  "description": "Returns the remaining leave days for a given employee.",
  "input_schema": {
    "type":     "object",
    "properties": {
      "employeeId": {
        "type":        "string",
        "description": "The employee's unique identifier"
      }
    },
    "required": ["employeeId"]
  }
}

The Tool Call Lifecycle

LLM Receives Tool Schemas All registered tools are sent with every LLM call as the tools parameter. The LLM knows what tools are available.

LLM Decides to Call a Tool The LLM response contains a tool_calls array instead of (or alongside) text content.

Runtime Executes the Tool MCPToolRegistry.ExecuteAsync looks up the registered handler and invokes it with the LLM-provided arguments.

Result Appended to History Tool call + result messages appended to working memory as a required consecutive pair.

LLM Continues Another LLM call is made with the tool result in context. LLM either calls another tool or produces a final text response.

Tool Categories

Data Query Tools

Query databases, APIs, or service endpoints. Return structured data the LLM can use to form answers. Examples: get_leave_balance, lookup_vendor, search_inventory.

Action Tools

Create, update, or trigger things. Examples: create_vendor, send_email, submit_expense_report, start_workflow.

Workflow Tools

Trigger Flow Studio workflows or hand off to other agents. The ProcessPlugin provides these automatically when the agent is linked to workflows.

MCPToolRegistry

public class MCPToolRegistry
{
    private readonly Dictionary<string, MCPTool> _tools = new();

    // Register a tool with its schema and handler
    public void Register(MCPTool tool) => _tools[tool.Name] = tool;

    // Get all tool schemas for the LLM call
    public IReadOnlyList<ToolDefinition> GetSchemas()
        => _tools.Values.Select(t => t.Schema).ToList();

    // Execute a tool call
    public async Task<string> ExecuteAsync(
        ToolCallRequest request,
        ConversationContext context,
        CancellationToken ct)
    {
        if (!_tools.TryGetValue(request.Name, out var tool))
            return JsonSerializer.Serialize(new { error = $"Unknown tool: {request.Name}" });

        return await tool.Handler(request.Input, context, ct);
    }
}

Tool Limits and Best Practices

Guideline	Reason
Keep tool count below 20 per agent	Too many tools confuses the LLM — it may choose the wrong one
Write clear, specific descriptions	The LLM uses the description to decide when to call the tool
Return minimal data	Large tool results consume tokens and may overflow the context budget
Never expose admin operations as tools	The LLM is not an authorisation layer — use tool security guards
Truncate large results	Use `ToolResultTruncator` to cap output to 2000 tokens

Next: Tool Schema →