Dynamic tool loading

Tool definitions are re-sent on every request. One MCP server can expose dozens of tools, so a naively connected agent pays for every schema on every call, for the whole run — and a model choosing among forty tools picks wrong more often than one choosing among four. Dynamic tool loading fixes both. The agent connects, puts every discovered tool into a searchable catalog, and sends only a tool_search tool up front. When the model needs something, it searches, the matching schemas are loaded, and they are included from the next request onwards.


Server	`https://mcp.deepwiki.com/mcp`
Auth	none
Model used here	`gpt-5.4-mini`

Dynamic tool loading is off by default: dynamic_tools defaults to False, so every schema is sent on every request until you turn it on. This page shows how to turn it on, see it working, and when to leave it off.

Build it

Install and set your key

pip install -U swarms python-dotenv
export OPENAI_API_KEY="sk-..."

Create the agent

from swarms import Agent

MCP_SERVER = "https://mcp.deepwiki.com/mcp"

agent = Agent(
    agent_name="RepoResearcher",
    model_name="gpt-5.4-mini",
    max_loops="auto",
    mcp_url=MCP_SERVER,
    dynamic_tools=True,   # MCP tools go into a searchable catalog
    print_on=False,
)

max_loops="auto" lets the agent decide when it is done — a good fit here, because searching for a tool and then using it takes an unknown number of turns.

Inspect the catalog

Building the LLM is what pulls the server’s tools into the catalog. The agent already did that when it was constructed; rebuilding it is harmless and makes the step explicit:

import json

agent.llm = agent.llm_handling()

catalog = agent.tool_loader.deferred_names if agent.tool_loader else []
exposed = [t["function"]["name"] for t in agent.tools_list_dictionary]

print(f"tools in catalog:       {len(catalog)}  {catalog}")
print(f"tools sent per request: {len(exposed)}  {exposed}")
print(f"schema bytes sent:      {len(json.dumps(agent.tools_list_dictionary)):,}")

The catalog holds the server’s tools; the request carries tool_search and nothing else. That gap is the saving, repeated on every call of the run.

Run a task and watch what gets loaded

result = agent.run(
    "What is the kyegomez/swarms repository for? Search for a tool that can "
    "answer questions about a GitHub repository, use it, and summarise the "
    "answer in three sentences."
)

print(f"loaded during the run: {agent.tool_loader.loaded_names}")
print(f"still deferred:        {len(agent.tool_loader.deferred_names)}")

After the run, loaded_names shows the handful of tools the task actually needed — everything else stayed out of the context window.

The complete script

import json

from swarms import Agent

MCP_SERVER = "https://mcp.deepwiki.com/mcp"

agent = Agent(
    agent_name="RepoResearcher",
    model_name="gpt-5.4-mini",
    max_loops="auto",
    mcp_url=MCP_SERVER,
    dynamic_tools=True,
    print_on=False,
)

# Building the LLM is what pulls the server's tools into the catalog.
agent.llm = agent.llm_handling()

catalog = agent.tool_loader.deferred_names if agent.tool_loader else []
exposed = [t["function"]["name"] for t in agent.tools_list_dictionary]

print(f"MCP server:             {MCP_SERVER}")
print(f"tools in catalog:       {len(catalog)}  {catalog}")
print(f"tools sent per request: {len(exposed)}  {exposed}")
print(f"schema bytes sent:      {len(json.dumps(agent.tools_list_dictionary)):,}")

if not catalog:
    print("\nNo MCP tools were loaded - the server could not be reached.")
    raise SystemExit(1)

result = agent.run(
    "What is the kyegomez/swarms repository for? Search for a tool that can "
    "answer questions about a GitHub repository, use it, and summarise the "
    "answer in three sentences."
)

print(f"\nloaded during the run: {agent.tool_loader.loaded_names}")
print(f"still deferred:        {len(agent.tool_loader.deferred_names)}")

How the model knows to search

Two things are added when deferral is on:

A tool_search tool, which takes a keyword query and loads the matching schemas.
A system prompt notice telling the model that most of its tools are not loaded, that any tool list it has seen describes what exists rather than what it can call, and that it should load everything it expects to need for a subtask in one search.

Loading changes the tool list, so the underlying LLM client is rebuilt at that point — otherwise the model could not call what it had just found.

When to leave it off

agent = Agent(
    agent_name="Focused-Agent",
    model_name="gpt-5.4-mini",
    mcp_url="https://mcp.deepwiki.com/mcp",
    dynamic_tools=False,   # the default: send every schema, every request
    max_loops=1,
)

Situation	Setting
Small server, three or four tools, one-shot task	`dynamic_tools=False` — the search round-trip costs more than the schemas.
Large server, or several servers at once	`dynamic_tools=True`.
Long autonomous runs (`max_loops="auto"`)	`dynamic_tools=True` — the saving compounds on every call.
A weak model that will not reliably search	`dynamic_tools=False`, or narrow the server surface instead.

Troubleshooting

The model says it has no tools

It has tool_search and needs to use it. Check that the system prompt notice survived — if you passed your own system_prompt, swarms appends the notice, but a prompt that insists “you have exactly these tools” fights it.

tools in catalog: 0

The server was unreachable and the agent carried on without those tools by design. Check the URL and any credential; run with verbose=True to see the fetch error.

cannot import name 'streamablehttp_client'

Your swarms predates mcp 2.x support, which renamed that function. Upgrade with pip install -U swarms; 15.0.1 and later work with both mcp 1.x and 2.x.

Timeouts on slow tools

A single tool call may run for tool_timeout seconds, 120 by default. Raise it with mcp_config=MCPConnection(url=MCP_SERVER, tool_timeout=300). mcp_timeout only bounds connecting and sending requests.

Source: examples/mcp/agents/autonomous_agent_dynamic_tools.py

Dynamic tool usage — the same mechanism for local Python tools.
Several servers at once — where deferral matters most.

Index

Basic Examples

Model Providers

Single Agent

Tree of Thoughts

Multi-Agent Examples

Auto Agent Builder

Scheduled Agents

Applications

Research

Technical Analysis

Use Cases

Finance

Voice Agents

Integrations

MCP Tool Integrations

Deployment

CLI

Dynamic tool loading

Build it

The complete script

How the model knows to search

When to leave it off

Troubleshooting

Next

​Build it

​The complete script

​How the model knows to search

​When to leave it off

​Troubleshooting

​Next

Build it

The complete script

How the model knows to search

When to leave it off

Troubleshooting

Next