Skip to content

feat: per-agent toolset restriction for orchestrator pattern (parent-scoped no_mcp) #32668

@davidgut1982

Description

@davidgut1982

Problem

When running Hermes as an orchestrator that delegates to specialized sub-agents via `delegate_task` + `agent_profiles`, there is no mechanism to restrict the orchestrator's tool schemas without also blocking sub-agent tool access.

Observed behavior

With the orchestrator pattern (SOUL.md routing table + agent_profiles), the main agent:

  • Makes a single routing decision (classifies intent → calls `delegate_task(profile="mail")`)
  • Uses 29 completion tokens to do so
  • But loads ~14,000 prompt tokens of MCP tool schemas to make that decision

The orchestrator doesn't need fastmail, proxmox, tavily, etc. — it only needs `delegate_task`. The sub-agents (spawned via profiles) need those domain tools.

What was tried

Attempt 1: `platform_toolsets.cli/api_server: [delegation, no_mcp]`

  • `no_mcp` correctly strips all MCP schemas from the orchestrator platform ✓
  • But `no_mcp` is platform-scoped — it also prevents sub-agents from loading their profile-defined toolsets ✗
  • Result: gateway instability and broken sub-agent tool access

Attempt 2: `mcp_servers..enabled: false` on domain servers

  • Reduces orchestrator token load ✓
  • But `enabled: false` is global — sub-agents with `toolsets: ["mcp-fastmail"]` in their profile can't access disabled servers ✗
  • Result: sub-agents silently have no domain tools

Neither mechanism supports the pattern: restrict parent, allow children.

Desired behavior

A way to say: "the orchestrator agent should not load these tool schemas, but child agents spawned via `delegate_task` with an `agent_profiles` entry that explicitly requests them should still get them."

Proposed solutions (any would work)

Option A: `inherit_mcp_toolsets` applied in reverse — profile toolsets override parent restriction

When a child is spawned with `agent_profiles..toolsets: ["mcp-fastmail"]`, the profile's explicit toolset list should always resolve against the full `mcp_servers` config, regardless of what the parent's platform toolset is.

Option B: `platform_toolsets` supports a `parent_only: true` flag

```yaml
platform_toolsets:
api_server:
toolsets: [delegation, no_mcp]
parent_only: true # child agents spawned from this platform ignore these restrictions
```

Option C: Separate `orchestrator_toolsets` config key

```yaml
orchestrator_toolsets:

  • delegation
  • mcp-knowledge

domain servers not listed here → not loaded for orchestrator

but still available to child agents via agent_profiles

```

Option D: `agent_profiles` toolsets always resolve from full mcp_servers config

Document (or enforce) that profile `toolsets` always resolve from the full `mcp_servers` list, bypassing parent platform restrictions. This makes `no_mcp` safe to use on the parent since child toolsets come from a different resolution path.

Context

  • Discovered during production testing of the orchestrator routing pattern (SOUL.md intent routing + agent_profiles)
  • Related to PR feat(delegation): agent profiles for delegate_task (#9459) #18522 (agent_profiles implementation by @w87x)
  • Token impact: orchestrator call = 14K prompt tokens, 29 completion tokens (1 function call) — 99.8% of tokens are unused tool schemas
  • KV cache mitigates cost but not latency or the architectural incorrectness
  • The multiple-Hermes-instance workaround (separate HERMES_HOME per domain) solves this at infrastructure cost but shouldn't be required for basic orchestrator setup

Environment

  • hermes-agent 0.14.0
  • Production homelab deployment
  • 9 MCP servers configured (~146 tools total)
  • Orchestrator + 5 domain profiles (mail, search, homelab, calendar, dealfinder)

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3Low — cosmetic, nice to havecomp/toolsTool registry, model_tools, toolsetstool/delegateSubagent delegationtype/featureNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions