From 30 Tools to 3: Designing a Token-Efficient MCP Tool Surface

A developer describes a pattern for reducing large MCP tool surfaces into a few domain-oriented tools by using an 'action' discriminator, which preserves capabilities while shrinking the model's context and decision space. The approach consolidates tools like Jira, GitLab, and Confluence into 3-5 domain tools, improving token efficiency and agent performance.

Modern agentic applications rarely suffer from a lack of tools. They suffer from too many of them . As an AI agent grows, it is common to connect it to Jira, GitLab, Confluence, Sentry, Elasticsearch, Jaeger, databases, monitoring systems, internal APIs, deployment platforms, and dozens of other services. Each integration can expose many operations: Jira ├── searchIssues ├── getIssue ├── createIssue ├── updateIssue ├── addComment ├── transitionIssue ├── getTransitions ├── assignIssue └── ... GitLab ├── listProjects ├── getProject ├── listIssues ├── createIssue ├── updateIssue ├── listMergeRequests ├── getMergeRequest ├── createComment └── ... Confluence ├── searchPages ├── getPage ├── createPage ├── updatePage └── ... It is easy to end up with 30, 50, or even hundreds of tools. At first, this looks like a capability problem. It is actually a tool-surface problem . The agent does not necessarily need fewer capabilities. It needs fewer top-level tools . This article describes a pattern I have been using to reduce large MCP/tool surfaces into a small number of domain-oriented tools while preserving the underlying capabilities. The core idea is simple: Consolidate the tool surface, not the capabilities. Instead of exposing: 30 MCP tools we can expose: 3–5 domain tools and use an action discriminator to route requests internally. For example: jira search jira get issue jira create issue jira update issue jira add comment jira transition issue ... can become: jira { action: "search", ... } jira { action: "getIssue", ... } jira { action: "createIssue", ... } The backend still has all the original capabilities. The model simply sees a much smaller tool surface. An MCP server is not only an execution interface. It is also part of the model's context. When an agent connects to an MCP server, the model generally needs to understand: Imagine an agent connected to 40 tools. Even if each tool has a relatively small schema, the aggregate context can become significant. More importantly, the model now has a larger decision space: User request │ ▼ Which tool? │ ┌───┼────┬────┬────┬────┐ ▼ ▼ ▼ ▼ ▼ ▼ T1 T2 T3 T4 T5 ... The model has to distinguish between many semantically related operations. For example: jira search issues jira search projects jira get issue jira get issue comments jira get issue transitions jira get issue worklogs are all part of the same conceptual domain. There is little value in forcing the model to treat every operation as a completely independent top-level capability. The pattern is to introduce an intermediate discriminator: { "action": "search", "query": "authentication bug" } Instead of: jira search we expose: jira The tool becomes a small router. Conceptually: jira │ action field │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ search getIssue createIssue │ │ │ ▼ ▼ ▼ searchHandler issueHandler createHandler The important point is that the tool is not the capability . The tool is the external interface. The action represents the capability. This gives us: 30 capabilities ↓ 3 domain-oriented tools without throwing away functionality. The easiest mistake is to think: "I have 30 tools, so I will put 10 operations into each tool." That is not the goal. Grouping should follow semantic domains . For example: jira ├── search ├── issue ├── comment ├── transition └── project gitlab ├── project ├── issue ├── mergeRequest └── pipeline observability ├── search ├── trace ├── log └── error The exact grouping depends on the integration. For a database: db tables db query db advanced might make sense. For Jira: jira issues jira projects jira search may be better. For GitLab: gitlab repository gitlab issues gitlab mergeRequests may be more natural. There is no universal number. The goal is to find the smallest tool surface that still preserves clear semantic boundaries. A database integration is a useful example because database APIs can easily expose a large number of operations. Instead of: listTables getTableSchema getSampleData getTableSize executeQuery getDatabaseInfo listRelationships getIndexes profileColumn searchSchema listProcedures getTriggers compareSchemas we can expose: db tables db query db advanced The first tool can use: js const tablesSchema = z.discriminatedUnion "action", z.object { action: z.literal "list" , schema: schemaField, } , z.object { action: z.literal "schema" , tableName: z.string , schema: schemaField, } , z.object { action: z.literal "sampleData" , tableName: z.string , schema: schemaField, rowCount: z.number .optional .default 10 , } , z.object { action: z.literal "size" , tableName: z.string , schema: schemaField, } , ; The model sees one tool: db tables with an explicit action space: list schema sampleData size The runtime still has four separate handlers. switch args.action { case "list": return handleListTables args.schema ; case "schema": return handleGetTableSchema args.tableName, args.schema ; case "sampleData": return handleGetSampleData args.tableName, args.schema, args.rowCount ; case "size": return handleGetTableSize args.tableName, args.schema ; } This distinction is important: Consolidation happens at the MCP interface, not inside the business logic. The internal handlers remain independently testable and maintainable. For TypeScript applications, z.discriminatedUnion provides a clean way to express this pattern. For example: js const querySchema = z.discriminatedUnion "action", z.object { action: z.literal "execute" , query: z.string , params: z.record z.string .optional , limit: z.number .optional .default 100 , } , z.object { action: z.literal "info" , } , ; The type can then be inferred directly: type QueryInput = z.infer<typeof querySchema ; This gives us three useful properties: The resulting architecture becomes: MCP Tool │ ▼ Discriminated Union │ ┌─────┴─────┐ │ action │ └─────┬─────┘ │ ┌────────┼────────┐ ▼ ▼ ▼ Handler A Handler B Handler C │ │ │ └────────┼────────┘ ▼ Backend This is much more predictable than asking the model to navigate dozens of unrelated top-level tools. This is probably the most important conceptual distinction. Suppose we have: 3 tools 13 actions That does not mean we lost 10 capabilities. We have: 3 external interfaces 13 internal capabilities Therefore: Tool count ≠ capability count This distinction becomes increasingly important as agent systems grow. A large organization may have: Jira 20 operations GitLab 25 operations Confluence 15 operations Sentry 8 operations ELK 10 operations Jaeger 6 operations Database 20 operations That can easily become 100+ operations. Exposing all of them directly to the model creates an unnecessarily large tool surface. Instead, we can build: jira gitlab confluence sentry observability database and keep the underlying operation count unchanged. The primary optimization is reducing the amount of tool metadata the model needs to process. Instead of presenting: Tool 1 Tool 2 Tool 3 Tool 4 ... Tool 30 we present: Tool A Tool B Tool C This can reduce: However, this should not be described as a guaranteed linear cost reduction. If we transform: 30 tools → 3 tools it does not necessarily mean: 90% lower token cost because the consolidated schemas themselves can become larger. The correct statement is: Tool consolidation can significantly reduce the tool metadata exposed to the model, but the actual token and latency savings depend on schema size, descriptions, provider behavior, and how the agent framework handles tools. This distinction matters. There is an important trade-off. Consider a tool with 40 actions: enterprise { action: ... } with actions such as: createCustomer deleteCustomer searchInvoice rotateCredentials deployService createRepository getTrace searchLogs ... This is technically possible. It is also terrible design. The model now has one enormous schema. The problem has simply moved from: 30 tools to: 1 giant tool The correct approach is domain-oriented consolidation . For example: customer billing repository observability deployment The ideal number might be 5 rather than 1. Therefore: Minimize the tool surface, but do not minimize it blindly. Once multiple capabilities share one tool, the action field becomes extremely important. Bad: action: z.string Better: action: z.enum "search", "get", "create", "update" Best, when actions have different parameters: z.discriminatedUnion "action", searchSchema, getSchema, createSchema, updateSchema, Now the action and its parameters form a strongly typed relationship. For example: action = "search" → query required action = "get" → issueId required action = "create" → title + description required This is much more expressive than one generic schema with dozens of optional fields. In practice, there is another layer of complexity. MCP tool schemas ultimately need to be represented as JSON Schema. A Zod discriminated union can produce a schema based on: { "anyOf": ... } or: { "oneOf": ... } depending on the converter. Some MCP schema handling paths expect an object at the root. That creates a compatibility problem. In one implementation, the MCP SDK's Zod compatibility layer expected an object shape and did not naturally handle the discriminated union in the same way. A compatibility layer can therefore normalize the generated schema. Conceptually: Zod discriminated union │ ▼ JSON Schema │ ▼ MCP normalization │ ▼ MCP-compatible object schema The important architectural principle is: Adapt the schema exposed to the model without weakening the runtime validator. The original Zod schema should remain the source of truth for validation. This leads to an important distinction. There are effectively two concerns: LLM-facing representation │ ▼ Tool selection and argument generation Runtime representation │ ▼ Validation and execution The LLM-facing schema needs to be: The runtime schema needs to be: These do not necessarily have to be identical. For example, a flattened object representation may make action choices easier for a model to see, while the original discriminated union remains responsible for strict validation. This is a useful general principle for agent infrastructure: Optimize schemas for model consumption, but never use model-facing schemas as the only security boundary. When there are 30 tools, each tool can have a very specific description. When there are 3 tools, the description needs to explain the action space. For example: Unified tool for advanced database analysis. ACTIONS: relationships List foreign key relationships. indexes Get indexes for a table. profileColumn Analyze nullability, cardinality and top values. searchSchema Search tables and columns. listProcedures List stored procedures. triggers Get triggers. compareSchemas Compare two table definitions. This is not documentation only. It is part of the model's routing interface. A useful mental model is: Tool name + Description + Action enum + Parameter schema ↓ Agent routing signal Therefore, when consolidating tools, descriptions should become more intentional, not less. This approach becomes much more valuable when applied across an entire engineering environment. Instead of: searchIssues getIssue createIssue updateIssue addComment transitionIssue assignIssue getTransitions use: jira issues with: search get create update comment transition assign Instead of exposing every repository, issue, merge request and pipeline operation: gitlab repository gitlab issues gitlab mergeRequests gitlab pipelines Each can expose a focused action set. Instead of: searchPages getPage createPage updatePage deletePage getChildren use: wiki with: search get create update children Potentially: sentry with: searchIssues getIssue events releases projects Potentially: logs with: search aggregate fields indices Potentially: tracing with: search getTrace services operations The important point is not the exact names. It is the architectural pattern. One of the most practical aspects of this approach is that we do not necessarily need to rewrite every integration. There are already MCP implementations for many popular systems. The problem is that their exposed tool surface may not be optimal for a specific agent. Instead of: Agent │ ├── 20 Jira tools ├── 20 GitLab tools └── 15 Confluence tools we can introduce a customized layer: Agent │ Custom MCP Layer │ ┌──────────┼──────────┐ ▼ ▼ ▼ Jira GitLab Confluence │ │ │ existing existing existing APIs MCP MCP The custom layer becomes an agent-oriented facade . This is particularly useful when the existing integration is technically correct but exposes too many low-level operations. This suggests a broader architectural pattern. Traditional integration: Agent → MCP → Service Customized integration: Agent ↓ Agent-oriented MCP facade ↓ Service-specific MCP/API ↓ Service The facade can provide: The MCP layer therefore becomes more than a transport. It becomes an agent interface layer . There is an important security implication. If we consolidate: jira create jira update jira delete into: jira { action: ... } we should not simply grant: permission: jira and assume all operations are equivalent. Permissions should still be evaluated at the action level. For example: jira.search → allowed jira.get → allowed jira.create → allowed jira.update → approval required jira.delete → denied The unified tool is only an interface optimization. It must not become a security boundary that accidentally grants excessive privileges. With consolidated tools, logging only the tool name is no longer sufficient. Bad: tool = jira Better: { "tool": "jira", "action": "search", "duration ms": 142 } Even better: { "tool": "jira", "action": "search", "status": "success", "duration ms": 142, "request id": "...", "agent id": "...", "user id": "..." } The fundamental execution unit becomes: tool + action rather than just: tool This is particularly important for debugging agent behavior. Tool consolidation should happen at the boundary. Do not create a 2,000-line function like: async function jira args { // everything } Instead: async function jira args: JiraInput { switch args.action { case "search": return searchIssues args ; case "get": return getIssue args ; case "create": return createIssue args ; case "update": return updateIssue args ; } } Each handler remains independently testable: jira │ ├── searchIssues ├── getIssue ├── createIssue └── updateIssue This preserves maintainability while reducing the external tool surface. A practical rule for deciding whether two operations should be consolidated is: Would a human developer naturally describe these operations as belonging to the same capability? For example: Jira search Jira get issue Jira update issue Yes. But: Jira update issue Elasticsearch search logs Create AWS infrastructure No. Another useful test: Would the same context usually be required to decide between these operations? If yes, consolidation is often beneficial. If no, keep them separate. There are cases where separate tools are better. database payments infrastructure email should not become: enterprise { action: ... } If a single tool has 50 actions, the schema itself may become expensive and confusing. Operations such as: deleteProductionData rotateCredentials deployProduction may deserve separate permission boundaries even if they belong to the same domain. Read-only operations and destructive operations can sometimes benefit from separate interfaces: jira read jira write instead of one enormous tool. Again, there is no universal rule. The goal is not: 30 → 1 The goal is: 30 → smallest useful semantic surface For one system that might be: 30 → 3 For another: 30 → 7 For another: 30 → 12 The optimization target is: minimize unnecessary tool metadata while preserving: semantic clarity validation security maintainability A scalable implementation can look like this: Agent │ ▼ ┌──────────────────┐ │ Agent MCP Layer │ └────────┬─────────┘ │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ jira gitlab wiki │ │ │ ┌────┼────┐ ┌────┼────┐ ┌────┼────┐ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ search get create issues MR pipeline search get update │ │ │ └──────────────┼──────────────┘ ▼ Existing APIs/MCPs The agent sees a compact interface. The integration layer retains the full capability set. MCP is often treated as: "Expose every API operation as a tool." That is a reasonable starting point. For production agent systems, however, a better question is: What interface should the model see? Those are not necessarily the same thing. A REST API might expose: GET /issues GET /issues/:id POST /issues PATCH /issues/:id POST /issues/:id/comments POST /issues/:id/transition We do not have to expose every HTTP endpoint as a separate model-facing tool. The MCP layer can become a semantic abstraction over those endpoints. This is similar to designing an API specifically for a consumer rather than simply mirroring an underlying database or service API. Traditional API design asks: What endpoints does the system provide? Agent interface design asks: What decisions does the model need to make? These are different questions. A human developer may prefer: getIssue getIssueComments getIssueTransitions getIssueWorklogs because each API operation is explicit. An agent may perform better with: jira issue { action: "get", ... } and: jira issue { action: "comments", ... } because the model first identifies the domain and then chooses the operation. This creates a two-level routing model: Domain ↓ Action ↓ Arguments rather than: One large global tool-selection problem The pattern can be generalized with TypeScript: js const toolSchema = z.discriminatedUnion "action", searchSchema, getSchema, createSchema, updateSchema, ; server.registerTool "jira", { description: "...", inputSchema: toolSchema, }, async args = { switch args.action { case "search": return search args ; case "get": return get args ; case "create": return create args ; case "update": return update args ; } } ; The implementation remains simple. The important engineering work is deciding: Tool consolidation should be measurable. Before: Tools: 32 Tool schema tokens: X Average tool-selection latency: Y Tool-selection errors: Z After: Tools: 5 Tool schema tokens: X' Average tool-selection latency: Y' Tool-selection errors: Z' The most useful metrics include: The objective is not merely: fewer tools but: better agent performance per unit of context This approach can be generalized beyond MCP. The same principle applies to: The pattern is essentially: Traditional API ↓ Many low-level operations ↓ Agent-oriented facade ↓ Small semantic tool surface ↓ Action routing ↓ Strict execution layer This is not really a database trick. It is an agent interface design pattern . The final mental model is simple: ┌──────────────────────┐ │ 30 APIs │ │ capabilities │ └──────────┬───────────┘ │ Consolidation │ ▼ ┌──────────────────────┐ │ 3–5 tools │ │ semantic domains │ └──────────┬───────────┘ │ Action routing │ ▼ ┌──────────────────────┐ │ 30 handlers │ │ original abilities │ └──────────────────────┘ The important transformation is therefore not: 30 capabilities → 3 capabilities It is: 30 exposed tools → 3 exposed interfaces The capabilities remain. The model-facing surface becomes smaller. As agent systems become more integrated, the number of available tools will continue to grow. Jira, GitLab, Confluence, Sentry, ELK, Jaeger, databases, cloud platforms and internal systems can easily produce dozens or hundreds of operations. Exposing every operation directly to the model is not always the best architecture. A better approach is to introduce an agent-oriented tool layer : Many low-level operations ↓ Semantic domain grouping ↓ Discriminated action schemas ↓ Small MCP tool surface ↓ Strict runtime validation ↓ Original capabilities The central principle is: Reduce the number of tools the model has to understand, not the number of capabilities your system provides. A 30-tool integration does not necessarily need 30 model-facing tools. It may need three well-designed interfaces with clear action spaces. And this pattern becomes especially powerful when existing MCP servers are treated not as untouchable interfaces, but as underlying integrations that can be wrapped, adapted and optimized for the needs of the agent. The future of MCP design may therefore be less about exposing everything an API can do , and more about designing the smallest useful interface through which an agent can do what it needs to do .