[Discussion] 1 API → Many Tools vs. Tool Overlap: how should MCP servers balance token efficiency and tools maintenance?

[sergio-reltio]

Pre-submission Checklist

• I have verified that this discussion would not be more appropriate as an issue in a specific repository
• I have searched existing discussions to avoid duplicates

Discussion Topic

TL;DR

At enterprise scale, one MCP server may front hundreds or thousands of APIs.

• 1:1 API→tool avoids tools overlap but often forces the LLM to filter large payloads → token waste.
• 1 API→many agent-shaped tools pre-projects data and trims tokens, but creates overlapping tools, additional complexity in maintenance, and potentially tool-selection confusion.

Looking for community best practices, server heuristics, etc., to navigate this trade-off.

Problem framing

We need LLM-efficient outputs (MCP server sending the right amount of data as tool output) and tools catalog clarity (avoid tool overlap).
The same backend API can power multiple types of agents. Agents may need the same data in different shape or form. Duplicating those as separate tools helps reduce token cost, but the proliferation of similar but different MCP tools make it pretty hard to maintain.
I’m not proposing a solution yet—inviting patterns, prior art, and whether this needs MCP server conventions or best practices. Or in other words, what's the right design/architecture/strategy for MCP tools?

Two extremes (and their pain)
1:1 API→tool (no overlap)

• Clear catalog; easy governance.
• LLM must filter/reshape large responses → higher token use and latency.

1 API→many tools (overlap)

• Server returns exactly what the agent needs → cheap token usage, simpler prompts.
• Overlapping tools with similar names/intents; harder to maintain; harder for LLM to select the right one.

What I’m asking the community

Discovery & selection: What MCP tools metadata (or naming conventions) have helped clients choose among overlapping MCP Server tools? Any success with cost/size hints or “intended-use” tags?

Server conventions: Do you ship overlapping, agent-specific tools? If yes, how do you control their growth and deprecate safely?

Spec affordances: Would lightweight, optional fields (e.g., intended-use, typical-response-size, sensitivity) in MCP tools help clients arbitrate between overlapping tools? Or should this remain purely convention/guidance?

Others: Do you have any other ideas on how to approach this scalability issue?