Route capabilities through a tested tool version

Learning objective

Compare explicit tool assignment with dynamic, capability- and version-aware tool routing.

Core idea

Tool routing has two questions: which capability fits the request, and which implementation contract is acceptable to execute it? A catalog match answers the first incompletely and doesn’t answer the second. For a senior engineer designing an expanding tool estate, the goal is to discover useful tools without silently changing their privileges or semantics.

Explicit assignment gives an agent a known tool set. Dynamic discovery retrieves relevant definitions at runtime. Microsoft Foundry Toolbox provides a shared MCP-compatible endpoint, and its tool search feature is preview. Toolbox versions provide a separate mechanism for testing and promoting a collection of tool configurations.

See 2.3.1 for typed function contracts and 2.3.4 for MCP client approval. This lesson owns the selection and version decisions that happen before execution.

How it works

Assign a small, stable set explicitly

With explicit assignment, you select the tools configured on an agent or in a curated toolbox. For remote MCP tools, Foundry’s allowed_tools restricts the exposed subset. A billing assistant can receive invoice lookup and credit calculation without also receiving the catalog’s account-deletion operation.

This approach makes review straightforward: an agent definition and its tool configuration describe the intended surface. It also avoids discovery latency and makes selection tests repeatable. The cost is maintenance. As roles and capabilities grow, you must keep their configured tool sets aligned with their responsibilities.

Explicit exposure doesn’t mean mandatory invocation; see 0.4 for tool_choice controls inside the supplied tool set. Those controls don’t search an external catalog or grant backend permission.

Discover capabilities without loading every definition

Foundry Toolbox tool search activates when the toolbox includes {"type": "toolbox_search"}. The initial MCP tools/list exposes two meta-tools: tool_search discovers relevant definitions, and call_tool invokes a discovered tool by name. Ordinary unpinned tools remain hidden from that initial listing. The configuration entry itself isn’t an exposed tool.

tool_search takes a required query string and an optional limit. The documented default limit is five and maximum is ten. Foundry uses BM25 ranking over tool names, descriptions, and parameter information. Returned tools remain callable for the rest of the turn without another search.

Use tool_configs on an individual toolbox tool entry to combine explicit and dynamic exposure. For a named remote tool, "pin": true keeps its definition visible in the initial tools/list beside tool_search and call_tool. Pin critical role tools and discover the less frequent capabilities on demand. This is a hybrid configuration, not a choice that forces every tool into the same discovery path.

The initial listing carries only the meta-tools and pinned tools; every other tool is found with tool_search and invoked with call_tool.

When you can’t change an MCP tool’s description, add the domain vocabulary through additional_search_text in its tool_configs entry. Foundry uses this text only for ranking; it never exposes it to the model in the tool schema. A generic description such as “process business information” can need terms such as invoice, overdue, and receivable to distinguish its capability. Search relevance still doesn’t prove safety or version compatibility.

Foundry also auto-pins frequently called tools per user after a warmup period. Auto-pinning composes with explicit pin and additional_search_text; don’t interpret every tool visible in the initial list as an explicitly pinned deployment choice.

The tool search page suggests this approach when a toolbox has more than 10–15 tools or different tasks need different subsets. That is a design guideline, not a hard service quota. A small fixed role can still benefit from explicit assignment, even when the organization’s overall catalog is large.

Keep capability and protocol compatibility separate

A business capability describes what a tool does. MCP protocol capabilities describe which interactions the peers support. Under MCP version 2025-11-25, a server advertises tools during initialization; listChanged indicates support for tool-list change notifications. Neither field says that an invoice tool accepts your application’s currency representation.

Compare a discovered tool’s name, description, inputSchema, and optional outputSchema with the consumer’s required contract. An application can maintain a compatibility record for approved implementations. Treat that record as application policy, not a standardized MCP semantic-version field. The MCP tool definition doesn’t supply a general tool-package version selector.

For a mutation, also require the relevant backend permission and approval policy. An excellent search match that only accepts whole currency units is unsuitable for a consumer whose contract uses minor units. Prompting the model to “be careful with versions” doesn’t repair that mismatch. Select a compatible configuration or an explicit adapter that has been tested.

Test and promote a toolbox version

Foundry separates a version-specific developer endpoint from the consumer endpoint. The developer pattern is {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1. The consumer pattern omits /versions/{version} and serves default_version.

Use the version-specific endpoint to list tools, compare their contracts, and invoke representative calls before promotion. Microsoft’s documented consumer pattern lets agents receive a promoted default without changing their code. That convenience makes promotion a consequential compatibility decision: an unchanged URL can expose a different configured collection.

The first toolbox version becomes the default automatically. Don’t assume creating the first version leaves it invisible to consumers. For later changes, test the candidate version and promote it only after its tools satisfy the agent’s expected inputs, results, and access rules. In the Python SDK, project.toolboxes.update(toolbox_name=TOOLBOX_NAME, default_version=VERSION_ID) selects that default; TOOLBOX_NAME and VERSION_ID stand for the approved toolbox and version identifiers. Where your tests need an exact candidate, use the developer endpoint for that test rather than hoping the consumer endpoint still points to it.

These are toolbox configuration versions, not the MCP wire-protocol version. A successful protocol handshake doesn’t establish that a changed business tool is safe for a deployed consumer. Record both dimensions in release evidence so a later investigation can distinguish transport compatibility from contract drift.

Key distinctions and trade-offs

Discovery reduces the definitions initially supplied to the model. It doesn’t remove authorization, approval, or result validation. Version management reduces accidental configuration drift only when promotion tests exercise the contracts that consumers depend on.

Architecture / decision scenario

A finance assistant starts with two approved tools: invoice lookup and credit calculation. You assign them explicitly and use allowed_tools for the MCP subset. The broader organization later curates dozens of tools for separate finance tasks. You enable preview tool search, pin those two tools through tool_configs with "pin": true, and leave the long tail available through tool_search.

For “find overdue invoices,” the pinned invoice lookup is visible immediately. A less frequent refund capability is discovered through tool_search and invoked through call_tool only after schema and approval checks. If its remote description lacks finance vocabulary, additional_search_text supplies ranking keywords without changing the model-visible schema. Search relevance doesn’t authorize the refund.

A candidate toolbox version changes a refund amount from whole units to minor units. You test it through the version-specific endpoint and reject promotion until the consumer or a tested adapter matches that contract. The default endpoint continues serving its approved configuration. The architecture combines dynamic capability discovery with deliberate version promotion instead of asking the model to compensate for an incompatible release.

Common exam traps

• Confusing tool_choice with external catalog discovery.
• Presenting Toolbox tool search as generally available.
• Treating the 10–15-tool guideline as a quota.
• Assuming a BM25 match proves schema compatibility or access permission.
• Confusing default_version with a fixed candidate version.
• Treating MCP protocol negotiation as business-tool version negotiation.

What to remember

Assign stable role tools explicitly; use discovery when catalog size and task variation justify it. Foundry tool search retrieves capabilities, while Toolbox endpoints separate candidate testing from default consumption. Gate promotion on the consumer’s contract and permissions.

Knowledge check

References

• Microsoft, What is Toolbox in Microsoft Foundry?
• Microsoft, Enable tool search in a toolbox
• Microsoft, Create and use a Foundry Toolbox
• Microsoft, Connect agents to MCP server endpoints
• Microsoft, How to use function calling with Microsoft Foundry Models
• Model Context Protocol, Tools