Strands Agents (Python): Tools and MCP
Defining tools in Strands Python: the @tool decorator, schemas, ToolContext, streaming and async tools, module and class-based tools, executors, what `strands-agents-tools` 0.9 removed, vended tools, sandboxes and MCP clients.
Checked against strands-agents 1.64.0 and strands-agents-tools 0.9.0 (2026-11-19). Examples were run against an offline Bedrock stub; the MCP examples ran against real local MCP servers.
The @tool decorator
Section titled “The @tool decorator”@tool turns a function into a tool. The function name is the tool name, the docstring’s summary is the description, and the parameters become a JSON schema built with Pydantic from the type hints. Parameter descriptions come from a Google-style Args: section:
from typing import Literal
from strands import Agent, tool
@tooldef search_products(query: str, category: Literal["books", "music", "games"] | None = None, limit: int = 5) -> list[dict]: """Search the product catalogue.
Args: query: Free-text search terms. category: Restrict results to one category. limit: Maximum number of results. """ return [{"sku": "B-101", "title": f"Result for {query}"}][:limit]
print(search_products.tool_spec["inputSchema"]["json"]["properties"]["category"])agent = Agent(model="us.anthropic.claude-sonnet-5-5", tools=[search_products], callback_handler=None)Parameters without a default are required. The decorated object still works as a plain function (search_products("jazz")), which makes unit-testing tools easy.
Overrides. @tool(name=..., description=..., inputSchema=...) replaces any of the generated values. inputSchema takes {"json": {...}}.
Descriptions without a docstring section. Annotated[str, "description"] works. Annotated[str, Field(...)] does not: the decorator raises NotImplementedError in this release.
Pydantic parameters. A parameter typed as a Pydantic model gets a nested schema and is validated, but the function receives a plain dict, not a model instance. Convert it yourself:
from pydantic import BaseModel, Fieldfrom strands import tool
class Address(BaseModel): street: str postcode: str = Field(description="UK postcode")
@tooldef ship_order(order_id: str, address: Address) -> str: """Ship an order.
Args: order_id: Order to ship. address: Delivery address. """ addr = Address.model_validate(address) # arrives as a dict return f"{order_id} shipping to {addr.postcode}"Validation errors. If the model’s arguments fail validation, the tool is not called; the model receives an error result naming the field, and usually corrects itself on the next turn.
Return values and errors
Section titled “Return values and errors”| Return | What the model sees |
|---|---|
str, number | A text block |
dict, list | JSON text |
A dict with status and content keys | Used as the tool result as-is (content blocks such as {"text": ...}, {"json": ...}, {"image": ...}) |
from strands import tool
@tooldef chart_data(metric: str) -> dict: """Return a metric series.
Args: metric: Metric name. """ return { "status": "success", "content": [ {"text": f"Series for {metric}"}, {"json": {"points": [3, 5, 8]}}, ], }Raising an exception does not stop the agent. The model gets {"status": "error", "content": [{"text": "Error: RuntimeError - ..."}]} and can retry, try another tool or explain the failure. Raise with a message the model can act on.
Tool context and per-request data
Section titled “Tool context and per-request data”@tool(context=True) injects a ToolContext into a parameter named tool_context (or pass a string to name the parameter yourself). It gives the tool:
| Attribute | Contents |
|---|---|
tool_use | The tool call (toolUseId, name, input) |
agent | The calling agent (agent.state, agent.messages, agent.name) |
invocation_state | The invocation_state passed to this call |
cancel_signal | A threading.Event set when the call is cancelled |
interrupt(name, reason=...) | Pause for human input (see interrupts) |
from strands import Agent, ToolContext, tool
@tool(context="ctx")def record_preference(key: str, value: str, ctx: ToolContext) -> str: """Remember a user preference.
Args: key: Preference name. value: Preference value. """ prefs = ctx.agent.state.get("prefs") or {} prefs[key] = value ctx.agent.state.set("prefs", prefs) return f"Saved {key} for user {ctx.invocation_state['user_id']}"
agent = Agent(model="us.anthropic.claude-sonnet-5-5", tools=[record_preference], callback_handler=None)agent("Please use metric units from now on", invocation_state={"user_id": "u-17"})The context parameter is not part of the schema the model sees.
Async and streaming tools
Section titled “Async and streaming tools”Tools can be async def. With the default ConcurrentToolExecutor, several tool calls from one model turn run concurrently; synchronous tools run in worker threads.
A tool written as an async generator streams progress: each yield is surfaced as a tool_stream_event in stream_async, and the last value yielded is the tool result:
import asyncio
from strands import Agent, tool
@toolasync def export_report(report_id: str): """Export a report to PDF.
Args: report_id: Report to export. """ yield "Collecting data..." await asyncio.sleep(0.1) yield "Rendering PDF..." yield f"s3://reports/{report_id}.pdf" # final value becomes the result
agent = Agent(model="us.anthropic.claude-sonnet-5-5", tools=[export_report], callback_handler=None)
async def main() -> None: async for event in agent.stream_async("Export report R-9"): if "tool_stream_event" in event: print("progress:", event["tool_stream_event"]["data"])
asyncio.run(main())Calling tools directly
Section titled “Calling tools directly”agent.tool.<name>(**kwargs) runs a tool without the model. It is useful for deterministic set-up steps and for tests. By default the call and its result are recorded in agent.messages so the model knows it happened; pass record_direct_tool_call=False to keep it out:
from strands import Agent, tool
@tooldef load_profile(user_id: str) -> dict: """Load a user profile.
Args: user_id: User ID. """ return {"user_id": user_id, "name": "Priya", "plan": "pro"}
agent = Agent(model="us.anthropic.claude-sonnet-5-5", tools=[load_profile], callback_handler=None)result = agent.tool.load_profile(user_id="u-17")print(result["status"], result["content"][0]["text"])agent.tool.load_profile(user_id="u-18", record_direct_tool_call=False)Names with hyphens are reachable with underscores (agent.tool.my_tool for my-tool).
Other ways to define tools
Section titled “Other ways to define tools”Methods
Section titled “Methods”@tool works on methods, so a tool can carry configuration or a client:
from strands import Agent, tool
class Catalogue: def __init__(self, prices: dict[str, float]): self.prices = prices
@tool def price(self, sku: str) -> float: """Look up the price of a SKU in GBP.
Args: sku: Product SKU. """ return self.prices[sku]
catalogue = Catalogue({"A-1": 9.50})agent = Agent(model="us.anthropic.claude-sonnet-5-5", tools=[catalogue.price], callback_handler=None)Module tools with TOOL_SPEC
Section titled “Module tools with TOOL_SPEC”A module with a TOOL_SPEC dict and a function of the same name is a tool. This was the format strands-agents-tools used, and it gives full control over the schema and the result:
from typing import Any
from strands.types.tools import ToolResult, ToolUse
TOOL_SPEC = { "name": "weather_tool", "description": "Get the forecast for a city.", "inputSchema": { "json": { "type": "object", "properties": {"city": {"type": "string", "description": "City name"}}, "required": ["city"], } },}
def weather_tool(tool_use: ToolUse, **kwargs: Any) -> ToolResult: city = tool_use["input"]["city"] return { "toolUseId": tool_use["toolUseId"], "status": "success", "content": [{"text": f"Sunny in {city}"}], }import weather_toolfrom strands import Agent
agent = Agent(model="us.anthropic.claude-sonnet-5-5", tools=[weather_tool], callback_handler=None)print(agent.tool_names) # ['weather_tool']tools= also accepts a file path ("./tools/weather_tool.py"), and load_tools_from_directory=True loads and hot-reloads every tool in ./tools/, which is convenient while developing and best left off in production.
AgentTool subclasses and tool providers
Section titled “AgentTool subclasses and tool providers”For tools built at run time, subclass strands.types.tools.AgentTool (implement tool_name, tool_spec, tool_type and an async-generator stream), or wrap a function with PythonAgentTool(tool_name, tool_spec, tool_func). A strands.tools.ToolProvider supplies a set of tools with a lifecycle (load_tools, add_consumer, remove_consumer); MCPClient is one.
Tool execution
Section titled “Tool execution”| Executor | Behaviour |
|---|---|
ConcurrentToolExecutor() | Default. All tool calls in one model turn run at once |
SequentialToolExecutor() | One at a time, in the order the model asked |
from strands import Agentfrom strands.tools.executors import SequentialToolExecutor
agent = Agent( model="us.anthropic.claude-sonnet-5-5", tool_executor=SequentialToolExecutor(), # tools that share a resource or must run in order callback_handler=None,)To stop a run after a tool, a hook can set event.end_turn on AfterToolsEvent, or a tool can use the vended stop tool; Agent.as_tool(delegate=True) ends the turn with a sub-agent’s answer. Retrying a tool is a hook concern (AfterToolCallEvent.retry = True), covered on the hooks page.
Background tools
Section titled “Background tools”A slow tool normally blocks the turn: the model asks for it, and nothing else happens until it returns. With background_tasks=, a tool call can be dispatched instead, leaving the model free to keep working while it runs:
import time
from strands import Agent, tool
@tooldef nightly_report(region: str) -> str: """Build the nightly report for a region.
Args: region: Region code. """ time.sleep(30) return f"report for {region}"
agent = Agent( model="us.anthropic.claude-sonnet-5-5", tools=[nightly_report], background_tasks={"max_concurrency": 2, "timeout": 300.0}, callback_handler=None,)print(agent.tool_names) # ['nightly_report', 'strands_manage_background_task']print(agent("Start the nightly report for eu-west-1, then tell me what else you can do."))background_tasks=True takes the defaults; a BackgroundTasksConfig (a TypedDict in strands.background_tasks) sets them:
| Key | Default | Meaning |
|---|---|---|
wait_for_completion | True | The invocation does not return until background work finishes |
max_concurrency | 4 | Background tasks physically running at once |
timeout | infinity | Per-execution timeout, in seconds |
agentic | ["*"] | Tools (or names) the model may choose to send to the background |
always | — | Tools that always run in the background |
never | — | Tools that never do |
Two things change when background execution is on. Every agentic tool’s schema gains a reserved boolean parameter, _background_execution, which is how the model asks for the call to be dispatched; a tool whose own schema declares that name raises TypeError when the agent is built. And the agent gains a strands_manage_background_task tool, which lists, inspects and cancels tasks.
A dispatched call returns a task id to the model straight away. When the task finishes, the result is delivered on the next model call as a synthetic strands_manage_background_task “get” call and its result, so the model never has to poll. Each task passes through queued, working and then completed, failed or cancelled, with input_required while an interrupt from the task is unanswered; the loop pauses rather than calling the model again while any task is waiting for input.
Not everything can run in the background: structured-output tools, delegating sub-agents (as_tool(delegate=True)) and a few internal tools always run in the foreground. Naming one of them in always or agentic explicitly raises TypeError at construction; under the ["*"] default they are simply left alone. agent.load_snapshot() refuses while tasks are still tracked, so take and restore snapshots between invocations, not mid-flight.
strands-agents-tools
Section titled “strands-agents-tools”strands-agents-tools 0.9.0 removed every tool it used to ship. Importing one (from strands_tools import file_read) now raises an ImportError whose message names the replacement. The package still installs, and strands_tools.utils remains, but there is nothing in it to hand to an agent. Pin strands-agents-tools<0.9 only as a stop-gap while you migrate; 0.8 logs a deprecation warning for most of the tools below.
Removed (strands_tools) | Replacement |
|---|---|
shell | strands.vended_tools.shell, which runs through the agent’s sandbox instead of directly on the host |
calculator, environment | strands.vended_tools.shell (arbitrary commands, so a wider boundary than the tools it replaces) |
editor, file_read, file_write | strands.vended_tools.edit, read and write (or file_editor) |
http_request | strands.vended_tools.http_request and web_fetch |
python_repl, sleep, stop, handoff_to_user | The vended tools of the same name |
code_interpreter | strands.vended_tools.python_repl for general programming; the AgentCore client for the managed sandbox |
journal | strands.vended_tools.notebook |
mcp_client | strands.vended_tools.make_mcp_router |
a2a_client | strands.vended_tools.make_a2a_client |
workflow, graph, agent_graph | strands.vended_tools.graph (make_graph) |
swarm | strands.vended_tools.swarm (make_swarm) |
use_agent, use_llm | strands.vended_tools.subagent (make_subagent) |
batch | Nothing: concurrent tool execution is the default |
current_time | Inject the time as context (ContextInjector plugin) |
think | The provider’s native reasoning (extended thinking) |
memory, retrieve, mem0_memory | MemoryManager with BedrockKnowledgeBaseStore (writable=False for retrieve), or the mem0-strands store |
agent_core_memory | MemoryManager with the AgentCoreMemoryStore from bedrock-agentcore |
elasticsearch_memory, mongodb_memory | Your own MemoryStore over the vendor’s client |
use_aws | The AWS MCP Server |
tavily, exa, bright_data, slack, chat_video, search_video | The vendor’s official MCP server (slack_bolt directly for Socket Mode) |
cron | EventBridge Scheduler (or shell) |
image_reader | Pass the image to the agent as an image content block |
load_tool | Pass tools to the Agent, or Agent(load_tools_from_directory=True) |
browser | Playwright from a custom tool (BrowserClient from bedrock-agentcore for AgentCore sessions) |
diagram, rss, generate_image, generate_image_stability, speak, use_computer | No replacement tool: write a custom tool around graphviz, feedparser, the Stability AI API, Amazon Polly or pyautogui |
nova_reels | None: Amazon Nova Reel reached end of life on Bedrock on 30 September 2026 |
The strands.vended_tools replacements were imported and, for graph, swarm and subagent, called against a scripted model on strands-agents 1.64.0; make_a2a_client needs the a2a extra. The store and MCP-server replacements are as named in the package’s own removal messages, and were not run here. Some replacements widen or narrow the security boundary: shell now goes through the sandbox, so it is tighter than the old tool, while calculator and environment become arbitrary command execution.
Vended tools in strands-agents
Section titled “Vended tools in strands-agents”strands.vended_tools ships tools with the SDK. Each has a ready instance and a make_* factory for configuration:
| Tool | Factory options |
|---|---|
shell | make_shell(sandbox=..., name=..., description=...) |
file_editor | make_file_editor(sandbox=...); commands view, create, str_replace, insert |
http_request | make_http_request(client=httpx.AsyncClient(...)) |
web_fetch | Needs the web-fetch extra |
python_repl, notebook, sleep, stop, handoff_to_user | |
subagent, swarm | Let the model spawn sub-agents or a swarm |
make_mcp_router(...), make_a2a_client(allowed_endpoints=[...]) | Factories only |
from strands import Agentfrom strands.vended_tools import file_editor, http_request, make_shell
agent = Agent( model="us.anthropic.claude-sonnet-5-5", tools=[make_shell(), file_editor, http_request], callback_handler=None,)print(agent.tool_names)Sandboxes
Section titled “Sandboxes”shell and file_editor run through the agent’s sandbox. Without one they run directly on the host (NotASandboxLocalEnvironment), with the same permissions as your process. Pass a sandbox to run them elsewhere:
from strands import Agentfrom strands.sandbox.docker import DockerSandbox
# docker run -d --name agent-sandbox python:3.12-slim sleep infinityagent = Agent( model="us.anthropic.claude-sonnet-5-5", sandbox=DockerSandbox("agent-sandbox", working_dir="/workspace"), callback_handler=None,)print(agent.tool_names) # ['sandbox_file_editor', 'sandbox_shell']DockerSandbox(container, working_dir=None, user=None) runs commands with docker exec in a container you started and vends sandbox_shell and sandbox_file_editor. strands.sandbox.ssh.SshSandbox(host, working_dir=..., identity_file=...) does the same over SSH, and PosixShellSandbox is the base class for your own. On AWS, the managed option for model-written code is the AgentCore Code Interpreter (python_repl or the AgentCore client).
strands.tools.mcp.MCPClient connects to a Model Context Protocol server and exposes its tools to an agent. The agent starts the client when it loads its tools and stops it on agent.cleanup() or when the agent is garbage-collected.
Strands 1.64.0 accepts mcp from 1.23 up to (not including) 2.2, so a fresh install resolves to the 2.x series. In mcp 2.x, FastMCP has been renamed to MCPServer (from mcp.server.mcpserver import MCPServer); server code written for mcp 1.x that imports mcp.server.fastmcp fails with ModuleNotFoundError there. Pin mcp<2 if you need the old import.
A local stdio server
Section titled “A local stdio server”A small server to test against:
from mcp.server.mcpserver import MCPServer
mcp = MCPServer("inventory")
@mcp.tool()def stock_level(sku: str) -> int: """Return the number of units in stock for a SKU.""" return {"A-1": 12, "B-2": 0}.get(sku, 0)
@mcp.tool()def delete_sku(sku: str) -> str: """Delete a SKU from the catalogue.""" return f"deleted {sku}"
if __name__ == "__main__": mcp.run() # stdioAn agent using it, with one tool filtered out and the rest prefixed:
import sys
from mcp import StdioServerParameters, stdio_clientfrom strands import Agentfrom strands.tools.mcp import MCPClient
inventory = MCPClient( lambda: stdio_client(StdioServerParameters(command=sys.executable, args=["inventory_server.py"])), tool_filters={"rejected": ["delete_sku"]}, prefix="inv",)
agent = Agent(model="us.anthropic.claude-sonnet-5-5", tools=[inventory], callback_handler=None)print(agent.tool_names) # ['inv_stock_level']agent("How many A-1 are in stock?")agent.cleanup() # stops the server processPublished servers are launched the same way, for example StdioServerParameters(command="uvx", args=["awslabs.aws-documentation-mcp-server@latest"]).
Remote servers
Section titled “Remote servers”For a Streamable HTTP server, pass url= instead of a transport callable:
from strands import Agentfrom strands.tools.mcp import MCPClient
internal = MCPClient( url="https://mcp.example.com/mcp", headers={"Authorization": "Bearer <token>"}, startup_timeout=30,)agent = Agent(model="us.anthropic.claude-sonnet-5-5", tools=[internal], callback_handler=None)auth= takes OAuth client credentials (machine-to-machine) and auth_provider= any httpx.Auth. For SSE servers pass lambda: sse_client(url) from mcp.client.sse. AgentCore Gateway is an MCP server, so it is reached the same way (see Gateway).
Servers from a config file
Section titled “Servers from a config file”Many MCP hosts describe their servers in an mcpServers JSON file. MCPClient.load_servers() builds one client per enabled server from such a file (a path) or from the same structure as a dict. A server with command is started over stdio, one with url uses Streamable HTTP (set transport to "sse" or "streamable-http" to override), and ${VAR} in string values is filled from the environment:
import sys
from strands import Agentfrom strands.tools.mcp import MCPClient
config = { "mcpServers": { "inventory": {"command": sys.executable, "args": ["inventory_server.py"]}, "docs": { "url": "https://mcp.example.com/mcp", "headers": {"Authorization": "Bearer ${MCP_TOKEN}"}, "continue_on_error": True, }, "legacy": {"command": "node", "args": ["server.js"], "disabled": True}, }}
clients = MCPClient.load_servers(config, prefix_with_server_name=True)agent = Agent(model="us.anthropic.claude-sonnet-5-5", tools=clients, callback_handler=None)print(agent.tool_names) # ['inventory_stock_level', 'inventory_delete_sku']: "docs" was skippedagent.cleanup()disabled servers are skipped. A server whose config cannot be resolved (here MCP_TOKEN is not set) is skipped if it has "continue_on_error": true, and raises otherwise; the continue_on_error= argument sets that default for every server. Malformed JSON or a malformed entry always raises. prefix_with_server_name=True prefixes each server’s tools with its key (characters outside [A-Za-z0-9_-] become _), so two servers that both offer search do not clash. Note that this example does not filter delete_sku; pass tool_filters by building the client directly when you need that.
Using the client directly
Section titled “Using the client directly”As a context manager, the client can list and call tools, prompts and resources without an agent:
import sys
from mcp import StdioServerParameters, stdio_clientfrom strands.tools.mcp import MCPClient
with MCPClient(lambda: stdio_client(StdioServerParameters(command=sys.executable, args=["inventory_server.py"]))) as client: print([t.tool_name for t in client.list_tools_sync()]) result = client.call_tool_sync(tool_use_id="t-1", name="stock_level", arguments={"sku": "B-2"}) print(result["status"], result["content"])list_prompts_sync, get_prompt_sync, list_resources_sync and read_resource_sync cover the rest of the protocol, with _async variants of the call methods.
Options
Section titled “Options”MCPClient argument | Use |
|---|---|
tool_filters | {"allowed": [...], "rejected": [...]}: exact names, compiled regexes or callables |
prefix | Prefix tool names to avoid clashes between servers |
startup_timeout | Seconds to wait for the server (default 30) |
continue_on_error | Let the agent start without this server if it fails |
elicitation_callback | Answer server elicitation requests |
progress_callback | Receive progress notifications |
tasks_config | Use MCP tasks for long-running tools |
on_tools_changed | React when the server’s tool list changes |
If a server cannot start, the agent constructor raises a ValueError (wrapping a ToolProviderException) unless the client was created with continue_on_error=True.
Revision history
Section titled “Revision history”| Date | Version | Changes |
|---|---|---|
| 2026-11-13 | 1.64.0 | Added background tools: BackgroundTasksConfig, the _background_execution parameter, the strands_manage_background_task tool, task statuses and which tools cannot be dispatched. |
| 2026-11-06 | 1.64.0 | strands-agents-tools 0.9.0 removed every tool it shipped. Replaced the deprecations table with a removal table naming each replacement, and updated the pages that imported strands_tools tools. |
| 2026-10-24 | 1.64.0 | Audit against the installed packages. Corrected the mcp dependency range (1.23 up to 2.2, not 2.x only), the shell replacement note and the diagram/rss guidance. Added MCPClient.load_servers() for mcpServers config files. |
| 2026-10-24 | 1.62.0 | New page. Documents schema generation limits (Annotated with Field unsupported; Pydantic parameters arrive as dicts), return-value handling, streaming tools, direct calls, module and class tools, executors, the strands-agents-tools 0.8 deprecations, vended tools, sandboxes and MCP with mcp 2.x. |