Reduce total number of tools, introduce "Meta Mode" for the MCP server

[Daniel Gonzalez (dggsax)]

I started writing this idea manually and then figured "let me use agent mode to make this go a little faster" in VS Code :) This proposal was drafted (and reviewed) with the assistance of Claude Opus 4.6. 😄 I'm not sure if this idea is even possible, but I do think that something like a --meta-mode should be considered to reduce the bloat of the MCP server and give Agentic tools a better change of success, especially in non-interactive environments where the MCP is configured with all tools.

Gonzo

Proposal: Dynamic Tool Discovery for the Azure DevOps MCP Server

Feature flag: --meta-mode

When enabled, the MCP server would wrap all existing tools behind a 4-tool discovery surface. Under the hood, the same tool implementations would be invoked — permissions, clients, and domain-scoped logic would remain unchanged. When disabled (default), the server exposes tools via the current flat tools/list behavior.

---

🔥 Problem

The ADO MCP server currently exposes all tools at once via tools/list. This creates several issues for LLM-based agents:

1. Context window bloat — Dozens of tools with full parameter schemas consume ~15,000–25,000 tokens before the agent even starts reasoning about the task.
2. Tool selection confusion — Even with explicit prompting ("use ADO MCP to open a pull request"), agents struggle to pick the correct tool from a large flat list.
3. Optional parameter overload — Nearly every parameter is optional, making schemas verbose and increasing the chance of hallucinated or misapplied arguments.

---

💡 Proposed Solution: Meta-Mode

Behind the --meta-mode flag, the flat tool list would be replaced with a progressive discovery surface of 4 meta-tools:

Tool	Purpose
list_domains	List available ADO capability domains
list_domain_tools	List tool summaries within a domain, optionally filtered by action type
get_tool_schema	Get the full input schema for a specific tool
execute_tool	Execute a specific tool by name with parameters

These meta-tools would be a thin layer over the existing tool infrastructure. execute_tool would delegate directly to the underlying tool implementation — no new permission model, no new client instantiation, no duplicated logic.

---

🛠️ Proposed Tool Definitions

1. list_domains

Would return the set of available capability domains, scoped to the server's configured enabledDomains.

{
  "name": "list_domains",
  "description": "Lists available Azure DevOps capability domains. Call this to understand what areas of functionality are available before discovering specific tools.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

Example response:

{
  "domains": [
    { "name": "repositories", "description": "Git repositories, pull requests, branches, commits, and code reviews" },
    { "name": "pipelines", "description": "Build and release pipelines, runs, approvals, and pipeline permissions" },
    { "name": "work-items", "description": "Work items, queries, tags, and work item tracking" },
    { "name": "work", "description": "Boards, sprints, iterations, team capacity, and backlogs" },
    { "name": "search", "description": "Code search, work item search, and wiki search across the organization" },
    { "name": "wiki", "description": "Wiki pages, creation, and updates" },
    { "name": "core", "description": "Projects, teams, and organization-level operations" },
    { "name": "advanced-security", "description": "Security alerts, code scanning results, and dependency vulnerabilities" },
    { "name": "test-plans", "description": "Test plans, test suites, test cases, and test results" }
  ]
}

Note: Only domains present in the server's enabledDomains configuration would be returned. The domain names returned here would be the only valid values for the domain parameter in list_domain_tools.

---

2. list_domain_tools

Would return summaries only (name + description + action tag) for tools within a domain. No full schemas — keeping the response compact so the agent can scan and decide which tool to use.

{
  "name": "list_domain_tools",
  "description": "Lists available tools within a specific ADO domain as summaries (name, description, and action type). Optionally filter by action type. Available domains: repositories (git, PRs, branches), pipelines (builds, releases, approvals), work-items (tracking, queries, tags), work (boards, sprints, backlogs), search (code, work items, wiki), wiki (pages, updates), core (projects, teams), advanced-security (alerts, scanning), test-plans (test cases, results). Use list_domains for full descriptions.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "domain": {
        "type": "string",
        "description": "The domain to list tools for.",
        "enum": []
      },
      "action": {
        "type": "string",
        "description": "Optional filter for the type of action. Omit to return all tools in the domain.",
        "enum": ["read", "create", "update", "delete"]
      }
    },
    "required": ["domain"]
  }
}

Dynamic enum and description: Both the domain property's enum array and the tool's description string (which lists domain names and short summaries) would be populated at server startup from the enabledDomains configuration. This would ensure the LLM only sees valid, configured domain values — both in the enum constraint and in the human-readable description. For example, if enabledDomains is ["repositories", "pipelines"], the schema would advertise "enum": ["repositories", "pipelines"] and the description would only mention those two domains.

Example request:

{ "domain": "repositories", "action": "create" }

Example response:

{
  "domain": "repositories",
  "action": "create",
  "tools": [
    { "name": "create_pull_request", "description": "Creates a new pull request in a Git repository", "action": "create" },
    { "name": "create_repository", "description": "Creates a new Git repository in a project", "action": "create" },
    { "name": "create_branch", "description": "Creates a new branch from a specified commit or ref", "action": "create" },
    { "name": "create_pull_request_comment", "description": "Adds a comment to a pull request thread", "action": "create" }
  ]
}

Without the action filter:

{ "domain": "repositories" }

{
  "domain": "repositories",
  "tools": [
    { "name": "list_repositories", "description": "Lists all Git repositories in a project", "action": "read" },
    { "name": "get_pull_request", "description": "Gets details of a specific pull request by ID", "action": "read" },
    { "name": "list_pull_requests", "description": "Lists pull requests matching filter criteria", "action": "read" },
    { "name": "create_pull_request", "description": "Creates a new pull request in a Git repository", "action": "create" },
    { "name": "update_pull_request", "description": "Updates properties of an existing pull request", "action": "update" },
    { "name": "create_pull_request_comment", "description": "Adds a comment to a pull request thread", "action": "create" }
  ]
}

The action tag on each tool summary would help the LLM reason about intent even when no filter is applied.

---

3. get_tool_schema

Would return the full inputSchema for a specific tool. This would allow the agent to inspect required and optional parameters before calling execute_tool, without needing to fail first.

{
  "name": "get_tool_schema",
  "description": "Returns the full input schema for a specific tool, including all required and optional parameters with descriptions. Use this to understand how to call a tool before executing it.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tool_name": {
        "type": "string",
        "description": "The name of the tool to get the schema for (e.g., 'create_pull_request')"
      }
    },
    "required": ["tool_name"]
  }
}

Example request:

{ "tool_name": "create_pull_request" }

Example response:

{
  "tool_name": "create_pull_request",
  "description": "Creates a new pull request in a Git repository",
  "domain": "repositories",
  "action": "create",
  "inputSchema": {
    "type": "object",
    "properties": {
      "project": { "type": "string", "description": "The project name" },
      "repositoryId": { "type": "string", "description": "The repository name or ID" },
      "sourceRefName": { "type": "string", "description": "Source branch (e.g., refs/heads/feature)" },
      "targetRefName": { "type": "string", "description": "Target branch (e.g., refs/heads/main)" },
      "title": { "type": "string", "description": "Pull request title" },
      "description": { "type": "string", "description": "Pull request description" }
    },
    "required": ["project", "repositoryId", "sourceRefName", "targetRefName", "title"]
  }
}

This would keep execute_tool responses lean (result only on success, schema only on validation failure), while giving agents an explicit way to fetch schemas proactively when they need them.

Consideration: Example values in schema responses

Including example values alongside parameter descriptions could significantly reduce hallucination for format-sensitive fields (e.g., refs/heads/feature/auth for sourceRefName). JSON Schema supports an examples keyword, and some MCP implementations may pass it through — but it's worth verifying whether the MCP protocol and common MCP hosts preserve examples or example fields in tool schemas. If supported, get_tool_schema responses could include:

"sourceRefName": {
  "type": "string",
  "description": "Source branch (e.g., refs/heads/feature)",
  "examples": ["refs/heads/feature/auth", "refs/heads/bugfix/login-fix"]
}

This would be especially valuable for ADO-specific conventions like ref name formatting, WIQL query syntax, and reviewer identity formats.

---

4. execute_tool

Would execute a specific tool by delegating to the existing tool implementation. The meta-mode layer would add no new permission logic — the underlying tool would handle auth, client instantiation, and domain scoping exactly as it does today.

{
  "name": "execute_tool",
  "description": "Executes a specific ADO tool by name with the given arguments. If you already know the tool name and parameters (from a previous interaction or from your instructions), you can call this directly without calling list_domains or list_domain_tools first.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tool_name": {
        "type": "string",
        "description": "The name of the tool to execute (e.g., 'create_pull_request')"
      },
      "arguments": {
        "type": "object",
        "description": "The arguments to pass to the tool"
      }
    },
    "required": ["tool_name", "arguments"]
  }
}

On validation failure (wrong/missing params), the error response includes the full schema so the agent can self-correct:

{
  "error": "Missing required parameter: sourceRefName",
  "tool_name": "create_pull_request",
  "inputSchema": {
    "type": "object",
    "properties": {
      "project": { "type": "string", "description": "The project name" },
      "repositoryId": { "type": "string", "description": "The repository name or ID" },
      "sourceRefName": { "type": "string", "description": "Source branch (e.g., refs/heads/feature)" },
      "targetRefName": { "type": "string", "description": "Target branch (e.g., refs/heads/main)" },
      "title": { "type": "string", "description": "Pull request title" },
      "description": { "type": "string", "description": "Pull request description" }
    },
    "required": ["project", "repositoryId", "sourceRefName", "targetRefName", "title"]
  }
}

---

🎓 Skipping Discovery: SKILL.md with Auto-Generated Schemas

Agents that already know which tools they need could call execute_tool directly without the discovery round-trips. To enable this, a SKILL.md file could be auto-generated from the tool source definitions.

How it could work

1. A build-time or startup-time script would read the tool registry (the same source that produces tools/list responses).
2. For each tool the operator wants to expose in the skill file, it would generate a Markdown recipe with the tool name, description, required parameters, and optional parameters.
3. The resulting SKILL.md would be provided to the agent as part of its system prompt or instructions.

Generation config

The operator could specify which tools to surface in the skill file via a configuration:

{
  "skillTools": [
    "create_pull_request",
    "list_pull_requests",
    "get_pull_request",
    "run_work_item_query",
    "list_repositories"
  ]
}

Auto-generated output example

The build step could produce a SKILL.md like:

## Azure DevOps MCP — Common Tool Recipes

These tools can be called directly via `execute_tool` without
calling `list_domains` or `list_domain_tools` first.

### create_pull_request
Creates a new pull request in a Git repository.

**Required parameters:**
| Parameter | Type | Description |
|---|---|---|
| `project` | string | The project name |
| `repositoryId` | string | The repository name or ID |
| `sourceRefName` | string | Source branch (e.g., `refs/heads/feature/my-change`) |
| `targetRefName` | string | Target branch (e.g., `refs/heads/main`) |
| `title` | string | Pull request title |

**Optional parameters:**
| Parameter | Type | Description |
|---|---|---|
| `description` | string | Pull request description |
| `reviewers` | string[] | List of reviewer IDs or email addresses |
| `isDraft` | boolean | Whether to create as a draft PR |

---

### list_pull_requests
Lists pull requests matching filter criteria.

**Required parameters:**
| Parameter | Type | Description |
|---|---|---|
| `project` | string | The project name |
| `repositoryId` | string | The repository name or ID |

**Optional parameters:**
| Parameter | Type | Description |
|---|---|---|
| `status` | string | Filter by status: `active`, `completed`, `abandoned`, `all` |
| `creatorId` | string | Filter by creator |
| `reviewerId` | string | Filter by reviewer |
| `targetRefName` | string | Filter by target branch |

---

<!-- Additional tools omitted for brevity -->

Benefits

• Always in sync — Generated from the same source as the tool definitions. No manual maintenance, no drift.
• Selective exposure — Operators choose which tools to include. An agent working primarily with PRs doesn't need test plan schemas in its instructions.
• Reduces round-trips — For known workflows, the agent goes straight to execute_tool on turn 1.
• Composable — Different SKILL.md files can be generated for different agent personas or use cases.

---

🏗️ Architecture: How Meta-Mode Could Work Under the Hood

┌─────────────┐     tools/list      ┌──────────────────┐
│   LLM/Host  │ ──────────────────► │  Meta-Mode Layer  │ → Returns only 4 meta-tools
│             │                     │                   │
│             │  execute_tool(      │                   │
│             │   "list_domains")   │  Reads from       │ → Returns enabledDomains
│             │ ──────────────────► │  server config    │   (no downstream call)
│             │                     │                   │
│             │  execute_tool(      │                   │     tools/list
│             │   "list_domain_     │  Calls underlying │ ──► (to underlying server)
│             │    tools",          │  tools/list,      │ ◄── Full tool list
│             │   {domain:"repos"}) │  filters & maps   │     Returns summaries only
│             │ ──────────────────► │                   │
│             │                     │                   │
│             │  execute_tool(      │                   │     tools/call
│             │   "create_pr",      │  Delegates to     │ ──► (to underlying server)
│             │   {args...})        │  existing tool    │ ◄── Response
│             │ ──────────────────► │  implementation   │     Returns result
└─────────────┘                     └──────────────────┘
                                            │
                                    Same permissions, same
                                    clients, same domain logic

The meta-mode layer would:

• Intercept tools/list and return only the 4 meta-tools.
• Cache the full tool list from the underlying server (fetched once at startup or lazily on first list_domain_tools call).
• Delegate execute_tool directly to the underlying tools/call — zero changes to tool implementations.

---

🔄 Expected Interaction Flow Comparison

Current (flat tools/list)

1. tools/list → 40+ tools with full schemas (~20K tokens)
2. Agent picks (often incorrectly) → tools/call

Meta-mode: Discovery path (typical)

Because list_domain_tools embeds domain names and short descriptions in its tool description, agents can typically skip list_domains and go straight to the domain they need:

1. tools/list → 4 meta-tools (~800 tokens)
2. list_domain_tools({domain: "repositories", action: "create"})
   → 4 tool summaries (~200 tokens)
3. get_tool_schema("create_pull_request") → full schema (~300 tokens)
4. execute_tool("create_pull_request", {...}) → result

Meta-mode: Discovery path (unfamiliar agent)

An agent that doesn't know which domain to use can call list_domains first:

1. tools/list → 4 meta-tools (~800 tokens)
2. list_domains() → 9 domain summaries with full descriptions (~400 tokens)
3. list_domain_tools({domain: "repositories", action: "create"})
   → 4 tool summaries (~200 tokens)
4. get_tool_schema("create_pull_request") → full schema (~300 tokens)
5. execute_tool("create_pull_request", {...}) → result

Meta-mode: Experienced agent with SKILL.md

1. tools/list → 4 meta-tools (~800 tokens)
2. execute_tool("create_pull_request", {...}) → result

Estimated context savings

Scenario	Tokens at decision point
Current (no meta-mode)	~20,000+
Meta-mode: typical discovery path	~1,300
Meta-mode: unfamiliar agent path	~1,700
Meta-mode: SKILL.md direct call	~800

---

⚖️ Tradeoffs & Concerns

Round-trip cost

The meta-mode discovery path introduces additional round-trips compared to the current flat tools/list approach. In the best case (experienced agent with SKILL.md), it's a single execute_tool call. In the typical discovery case, it's 4 turns. In the worst case (unfamiliar agent, cross-domain task), it could be more.

This is an intentional tradeoff: fewer tokens upfront in exchange for more turns. For most LLM hosting environments, turns are cheap relative to the context window cost of 20K+ tokens of tool schemas that the agent has to carry for the entire conversation.

Cross-domain tasks

If a user asks something like "Create a PR and link it to work item #1234", the agent needs tools from both the repositories and work-items domains. This would require calling list_domain_tools twice (once per domain), and possibly get_tool_schema twice — adding up to several discovery round-trips for a common composite task.

Mitigations:

• SKILL.md can pre-load common cross-domain recipes, letting the agent skip discovery entirely.
• The list_domain_tools description already embeds all domain names, so the agent can identify both relevant domains from the tool description and issue both list_domain_tools calls in parallel (if the host supports parallel tool calls).
• A future search_tools meta-tool that searches across all domains by keyword (e.g., {"query": "pull request work item link"}) could address this more directly, but adds complexity to the initial proposal.

---

❓ Open Questions

1. Action taxonomy: The action enum should align with the action types already used by the Azure DevOps REST API rather than inventing a new taxonomy. This needs investigation — what action categorization does ADO use across its resource areas, and can it be derived from the API metadata?

2. Server-level defaults in tool summaries: When asked to evaluate the proposal, Claude Opus 4.6 suggested:

   When I see create_pull_request in the summary, I know I need a project and repo — but I often don't know if the server has a default project configured. If the tool summary included a hint like "default_project": "MyProject", I could skip asking the user for information the server already knows. Consider including server-level defaults or context in domain tool summaries.

   This may not be feasible depending on how the underlying MCP server exposes (or doesn't expose) configured defaults, but it's worth investigating.

---

✅ Decisions

• --meta-mode is opt-in. The default behavior remains the current flat tools/list. The team can decide later whether to make meta-mode the default or remove the flat mode entirely.
• Schema delivery: execute_tool returns only the result on success, and includes the full inputSchema on validation failure. Agents that want the schema proactively use get_tool_schema.
• No fuzzy domain matching. The list_domains response and the enum on list_domain_tools already advertise the exact set of valid domain names.
• SKILL.md is a complementary idea, not a core part of the meta-mode feature. It's a way to further reduce round-trips for agents that repeatedly use the same tools — auto-generated from the tool source definitions so it stays in sync. Implementation details (build-time vs. CLI generation) can be decided if/when the idea is picked up.

[Dan Hellem (danhellem)]

Is there are a reason you can't just use domains to only bring in the areas you are using?