Tool Scoping for Sub-Agents

[tushar-altera]

Describe the feature or problem you'd like to solve

Product: GitHub Copilot CLI (Agent Mode) Type: Feature Request Priority: Medium --- ## Summary When spawning a sub-agent via the task tool, the sub-agent inherits the full tool set registered in the parent session. There is no mechanism to restrict which tools are passed to the sub-agent. This causes sub-agent spawning to fail entirely when the environment has a large number of MCP tools registered and the target model has a tool count limit. --- ## Problem In enterprise environments, multiple MCP servers are typically registered simultaneously — for example: - Azure DevOps MCP (ADO) - Confluence MCP - MSSQL MCP - GitHub MCP - Custom agent tools This results in 150+ tools being registered in a single session. When spawning a sub-agent targeting gpt-4.1, the platform passes all 150+ tools to the sub-agent. GPT-4.1 has a hard API limit of approximately 128 tools per request. The result is an immediate rejection: Error: tool count exceeded limit (151 > 128) The sub-agent fails to spawn entirely, even if its actual task requires only 5–6 tools (e.g., grep, view, edit, create, glob for wiki/catalog work). --- ## Impact 1. Model choice is constrained. gpt-4.1 is the preferred model for deterministic, low-cost tasks (catalog sweeps, file transforms, registry updates) because it is free in this environment and has a 1M token context. The tool count limit makes it completely unusable as a sub-agent in any environment with many MCP servers. 2. Cost increases. The fallback is claude-haiku-4.5, which works but costs ~$0.005/sweep. At scale across many agents and sessions, this adds up unnecessarily. 3. Workarounds are fragile. Unregistering MCP servers before spawning a sub-agent is impractical — it affects the entire session and requires manual reconfiguration.

Proposed solution

Add an optional allowed_tools parameter to the task tool that lets the caller explicitly scope which tools are passed to the sub-agent:

task(
  agent_type: "general-purpose",
  model: "gpt-4.1",
  allowed_tools: ["grep", "glob", "view", "edit", "create", "powershell"],
  prompt: "..."
)

Behavior:

• If allowed_tools is provided → only those tools are passed to the sub-agent
• If allowed_tools is omitted → current behavior (full tool inheritance) is preserved
• Unknown tool names in allowed_tools are silently ignored (no error)

---

Alternative Solutions

Option A — Tool category groups
Instead of listing individual tools, allow grouping:

allowed_tool_groups: ["filesystem", "search"]

Where filesystem = view, edit, create and search = grep, glob.

Option B — Tool exclusion list
Instead of allowlist, provide a denylist:

excluded_tools: ["ADO-MCP-*", "ATLASSIAN-MCP-*", "MSSQL-MCP-*"]

Useful when most tools are needed but specific MCP servers should be excluded.

Option C — Model-aware automatic trimming
Platform automatically trims tools to fit the target model's limit, prioritizing built-in tools over MCP tools when a cut is needed.

Of these, Option A (allowlist) is recommended as the primary solution — it gives the caller precise control and makes the sub-agent's capability surface explicit and auditable.

---

Acceptance Criteria

• task tool accepts an optional allowed_tools parameter (array of tool name strings)
• Sub-agent receives only the listed tools when allowed_tools is specified
• Sub-agent spawning with allowed_tools: ["grep", "glob", "view", "edit", "create"] succeeds against gpt-4.1 in an environment with 150+ registered tools
• Omitting allowed_tools preserves existing full-inheritance behavior (no breaking change)
• Documentation updated for task tool parameters

---

Environment Details

• Copilot CLI version: 1.0.35
• Primary model: Claude Sonnet 4.6
• MCP servers registered: ADO-MCP, ATLASSIAN-MCP (Confluence), MSSQL-MCP, github-mcp-server + custom tools
• Total tools in session: ~151
• Affected model: gpt-4.1 (128-tool limit)
• Workaround in use: Fall back to claude-haiku-4.5 for all sub-agent catalog/wiki work

---

References

• GPT-4.1 tool limit: [OpenAI API documentation — function calling limits]
• Catalog skill pattern: uses only 6 tools (grep, glob, view, edit, create, powershell) but cannot use gpt-4.1 due to this constraint

copilot-cli-feature-request-tool-scoping-sub-agents.md

Example prompts or workflows

No response

Additional context

No response