Tool namespacing is the practice of grouping related tools under common prefixes so that the boundaries between them are legible to an agent choosing among them. It is set out under that name in Writing effective tools for agents — with agents, which motivates it by the situation an agent is increasingly in: access to dozens of Model Context Protocol servers and hundreds of tools, including tools written by other developers, where overlapping function or vague purpose leaves the agent unsure which to call. Some MCP clients are reported to apply namespacing by default.
Usage
The post describes two axes, which can be combined. Tools may be namespaced by service, so that
searching in one product and searching in another carry distinct prefixes rather than competing as two
tools both called “search”; and by resource, so that searching projects and searching users within
the same service are separated in turn. The examples given are service-level names of the form
asana_search and jira_search, and resource-level names of the form asana_projects_search and
asana_users_search.
The choice of scheme is presented as an empirical question rather than a convention. The authors report that selecting between prefix- and suffix-based namespacing had non-trivial effects on their own tool-use evaluations, that the effects vary by model, and they recommend choosing a naming scheme according to one’s own evaluations rather than adopting a rule.
OpenAI’s function-calling guide (see Function calling) supports the practice as an
API feature rather than a naming convention: related tools can be grouped into namespaces by domain, with
crm, billing and shipping as its examples. It gives the same motivation — namespaces are
especially useful when the model must choose between tools serving different systems or purposes, such
as one search tool for a CRM and another for a support ticketing system. Where namespaced tools are
deferred with Tool search, the guide advises keeping the namespace description concise
and putting detailed guidance in each function’s description, since the namespace helps the model
choose what to load and the function description helps it use the loaded tool correctly.
The post places namespacing alongside a second, related discipline: selectively implementing tools whose names reflect natural subdivisions of tasks. It is that second practice the post credits with simultaneously reducing the number of tools and tool descriptions loaded into the agent’s context and offloading agentic computation from that context back into the tool calls themselves.
When It Applies
It applies where an agent has enough tools available that selection itself becomes a failure point. The failure modes the post names are calling the wrong tool, calling the right tool with the wrong parameters, calling too few tools, and processing tool responses incorrectly. What the post credits namespacing itself with is helping delineate boundaries and helping agents select the right tools at the right time; it attaches the broader claim about reducing an agent’s overall risk of mistakes to the neighbouring practice of naming tools after natural subdivisions of tasks.
It assumes the tools are yours to name, or at least that the client can rewrite names on the way through. The post notes separately that MCP clients sometimes apply namespacing by default, and that an agent’s tools may include those written by other developers. It also assumes names carry meaning for the model, which is the same assumption behind the post’s separate advice on prompt-engineering tool descriptions and on naming parameters unambiguously.
The technique is not presented as sufficient on its own. In the same post it is one of five principles, and the one preceding it — building a few thoughtful, consolidated tools rather than wrapping every API endpoint — addresses the same underlying problem from the other end, by not creating the overlapping tools in the first place.
How well-established it is: the naming advice is one vendor’s engineering guidance, drawn from optimizing its own internal tools against its own evaluations. The direction of the advice is stated as a finding; the specific choice between prefix and suffix is explicitly left to the reader’s own measurement. OpenAI’s function-calling guide separately offers namespaces as a first-class API feature for grouping tools by domain.
Related Terms
- Function calling — the broader pattern this is a design discipline within
- Model Context Protocol — the protocol whose tool sprawl motivates the practice
- Context engineering — the concern that tool names and descriptions occupy context
- Function calling — the mechanism through which namespaced tools are offered to a model
- Tool search — deferring namespaced tools until the model needs them