Tool Scoping — Agent Areas

Tool Scope Levels

Scope	Visibility	Example
Global (plugin-registered)	Available to all agents; agent admin chooses to assign or not	`start_workflow` (ProcessPlugin)
Area tool group	Registered for a specific area; agents in the area can be assigned the group	`get_leave_balance` — HR area only
Agent-specific	Assigned to exactly one agent	`get_executive_salary` — CFO agent only

Assigning Tools to an Area Agent

// In the agents-app: Area → Agent → Tools tab
// Via API:
POST /api/octopus/agents/{agentId}/tool-groups
Authorization: Bearer {areaAdminToken}

{
  "toolGroupId": "tg_hr_leave_tools",
  "enabled":      true
}

// Tool group "tg_hr_leave_tools" contains:
// - get_leave_balance
// - submit_leave_request
// - get_leave_history
// - cancel_leave_request

Area-Level Tool Groups

// Create a tool group scoped to an area
POST /api/octopus/areas/{areaId}/tool-groups
{
  "name":        "HR Leave Tools",
  "description": "Tools for managing employee leave",
  "toolNames":   ["get_leave_balance", "submit_leave_request", "get_leave_history"]
}

// List tool groups available in an area
GET /api/octopus/areas/{areaId}/tool-groups

// Tool groups in one area are NOT visible to agents in other areas
// (unless the group was defined at the global/plugin level)

Tool Isolation Enforcement

When an agent calls MCPToolRegistry.ExecuteAsync, the registry only contains tools explicitly assigned to that agent. It is not possible for the agent to discover or call tools registered for a different agent:

// Per-agent tool registry — built at agent load time
public class AgentToolRegistryFactory
{
    public MCPToolRegistry BuildForAgent(OctopusAgent agent, IServiceProvider sp)
    {
        var registry = new MCPToolRegistry();

        // 1. Add globally registered tools that the agent has been assigned
        foreach (var toolGroupId in agent.AssignedToolGroupIds)
        {
            var group = _toolGroupStore.GetById(toolGroupId);
            foreach (var toolName in group.ToolNames)
            {
                if (_globalRegistry.TryGet(toolName, out var tool))
                    registry.Register(tool);
            }
        }

        // 2. Add AI Functions active for this agent
        _aiFunctionRegistrar.RegisterForAgent(agent.AgentId, agent.TenantId, registry, ...);

        return registry;
        // Only contains tools explicitly assigned — no cross-agent leakage
    }
}

← Knowledge Scoping Next: User Access →