Tools
Tools are declarative. You list what the agent can call; AgentCore handles invocation, credentials, and results. The harness supports five tool types and managed built-in tools.
-
Model Context Protocol
(MCP) servers: Connect to any remote MCP endpoint by URL. To authenticate, send request headers, or have the harness sign each request with Signature Version 4 (SigV4) using the harness execution role. -
AgentCore Gateway: Governed connectivity to APIs and MCP servers with inbound/outbound auth, access control, and policy enforcement. Reference a gateway ARN and every tool configured on that gateway becomes available. Use Gateway when you need a managed, policy-backed tool surface.
-
AgentCore Browser: Managed web browsing and automation.
-
AgentCore Code Interpreter: Sandboxed Python/JavaScript/TypeScript code execution for data analysis and computation.
-
Inline functions: Tool schemas that execute on the client side, not on the harness VM. The harness pauses when the tool is called and returns the call to your code, which decides what to do and sends a result back. This is the pattern for human-in-the-loop approvals and custom integrations.
When allowedTools is omitted or set to ["*"], the harness uses the current recommended built-in tool set.
allowedTools: ["*"] permits every configured tool that resolves successfully and every tool in the current recommended built-in set, including shell and filesystem tools that can read, create, or modify files (read, write, and edit). The recommended set can gain new tools as the harness improves. Use the wildcard only when the agent should be allowed to use every such tool. To keep a fixed, least-privilege tool surface, list individual selectors.
| Selector | Capability |
|---|---|
|
|
Runs shell commands in the harness filesystem. Use it for command-line tools and scripts. |
|
|
Separately permit viewing a file, creating or replacing a file, and making targeted changes to an existing file. |
|
|
Compatibility selector that grants |
|
|
Lets the agent record and update a task plan. It is useful for tracking multi-step work. |
|
|
Moves each tool result larger than approximately 1,500 tokens out of the agentâs context and leaves a shorter preview in its place. The agent can use |
|
|
Lets the agent delegate a self-contained task to a fresh child agent and receive its result. The child is not a separately configured harness. The child gets the agentâs built-in, MCP server, and Gateway tools other than |
|
|
Retrieves content from a URL for the agent to inspect. |
The allowedTools parameter controls which tools the agent can use. Use a plain selector such as read, a built-in selector such as @builtin/read, or @builtin for all built-in tools.
Tool definitions count toward model input tokens even when the agent doesnât call the tools. The current recommended built-in tool set adds approximately 3,000 input tokens to each model request. The exact overhead varies by model and can change as built-in tool definitions evolve.
For supported Amazon Bedrock models using converse_stream, the harness automatically includes the system prompt, tool definitions, and conversation history in prompt caching. After the cache is populated, repeated model calls with an unchanged effective tool set can reuse the cached tool-definition tokens. Cache reads use the modelâs lower cache-read price instead of its regular input-token price; creating or refreshing the entry uses the modelâs cache-write price. Prompt caching does not remove the tool definitions from the model context. Use allowedTools to expose only the tools needed for a request and reduce context usage. See Automatic prompt caching for model support, cache behavior, and pricing details.
Supported patterns:
| Pattern | Example | Matches |
|---|---|---|
|
|
|
All tools |
|
Plain name |
|
Builtin by name |
|
Builtin glob |
|
|
|
|
|
All builtin tools |
|
|
|
Specific builtin |
|
|
|
All tools from an MCP server |
|
|
|
Specific MCP tool |
|
|
|
Glob within a server |
|
|
|
Glob across servers |
allowedTools scopes LLM tool selection during InvokeHarness only. It does not affect InvokeAgentRuntimeCommand, which is a separate API with its own IAM action (bedrock-agentcore:InvokeAgentRuntimeCommand) that executes commands directly without passing through the LLM. To prevent direct command execution, do not grant bedrock-agentcore:InvokeAgentRuntimeCommand in your IAM policies.
Add tools
Remote MCP connections originate inside the harness session microVM. MCP URLs can point to public or private endpoints that the runtime can reach.
Before you invoke the harness for less-trusted application users, validate or replace caller-supplied tool configurations, including MCP URLs and headers. Scope the execution role and AgentCore Identity access to the resources and credentials the harness needs. For more information, see Trust boundary and input validation and MicroVM Metadata Service (MMDS).
Example
Web search
To give your agent web search, put the Web Search Tool connector behind an AgentCore Gateway and attach that gateway to your harness as an agentcore_gateway tool. The gateway exposes web search as a standard MCP WebSearch tool. Your agent discovers and calls it like any other gateway tool. AgentCore Gateway serves all queries entirely within AWS. For more information about the privacy model and the purpose-built web index, see the Web Search Tool connector page.
Web Search Tool is available in multiple AWS Regions. For the current list, see Availability on the Web Search Tool connector page. Create the gateway and harness in a supported Region.
Complete the following steps to set up web search for your harness.
-
Create the gateway and connector target. Follow the steps in Set up Web Search Tool to create a Gateway (MCP protocol,
AWS_IAMinbound auth) and add a target withconnectorId: "web-search". That target needs a Gateway service role withbedrock-agentcore:InvokeWebSearchon the connector. For more information, see Configure the Gateway Service Role. Note the gateway ARN once it reachesREADY. -
Grant the harness execution role access. The harness execution role (distinct from the Gateway service role in the previous step) needs
bedrock-agentcore:InvokeGatewayon the gateway ARN. For more information about the required permissions, see the AgentCore Gateway optional-permissions policy in the security topic. If your harness uses managed memory, the execution role also needs the AgentCore Memory permissions. The agent reads and writes session memory on each invocation. -
Attach the gateway to the harness. Add it as an
agentcore_gatewaytool with the defaultAWS_IAMoutbound auth. The following examples show how to attach the gateway at create time.
Example
Web answer
To give your agent finished, cited answers to questions that need current web information, put the Web Answer connector behind an AgentCore Gateway and attach that gateway to your harness as an agentcore_gateway tool. The gateway exposes the connector as an MCP <target-name>___WebAnswer tool. Your agent calls it with a question and gets back an answer with citations, instead of raw search results.
Web Answer is available in US East (N. Virginia) us-east-1. Create the gateway and harness in that Region.
Complete the following steps to set up Web Answer for your harness.
-
Create the gateway and connector target. Follow the steps in Set up Web Answer to create a Gateway (MCP protocol,
AWS_IAMinbound auth) inus-east-1and add a target withconnectorId: "web-answer". That target needs a Gateway service role withbedrock-agentcore:InvokeWebAnsweron the connector. For more information, see Configure the Gateway Service Role. Note the gateway ARN once it reachesREADY. -
Grant the harness execution role access. The harness execution role (distinct from the Gateway service role in the previous step) needs
bedrock-agentcore:InvokeGatewayon the gateway ARN. For more information about the required permissions, see the AgentCore Gateway optional-permissions policy in the security topic. If your harness uses managed memory, the execution role also needs the AgentCore Memory permissions. -
Attach the gateway to the harness. Add it as an
agentcore_gatewaytool with the defaultAWS_IAMoutbound auth. The following examples show how to attach the gateway at create time.
Example
You can also add a Web Search Tool target and a Web Answer target to the same gateway, so the agent can choose raw results or a finished answer for each question.
Inline function calls
Inline functions let you define a tool that executes in your code, not on the harness. This is useful for human-in-the-loop approvals, calling internal APIs, or any logic you want to control client-side.
Example
Learn more about each tool:
Related topics
-
Models and instructions â Configure models and override per invocation
-
Lifecycle hooks â Configure hooks to validate invocations and tool calls
-
Environment and filesystem â Bring your own container and run shell commands
-
Security and access controls â Configure the harness execution role and control tool access