Tools

Claude Managed Agents provides a set of built-in tools that Claude can use autonomously within a session. You control which tools are available by specifying them in the agent configuration.

Claude Managed Agents also supports custom, user-defined tools. Your application executes these tools separately and returns the results to Claude, which uses them to continue the task. To give the agent tools from an MCP server, use the MCP connector instead.

Available tools

The agent toolset includes the following tools. All are enabled by default when you include the toolset in the agent configuration.

When a tool output exceeds 100,000 characters (about 25,000 tokens), it is automatically written to a file in the sandbox. The model receives a truncated preview with the file path and can read the full content from there.

Configuring the toolset

Enable the full toolset with agent_toolset_20260401 when creating an agent. Use the configs array to disable specific tools or override their settings. Each entry is identified by its name, which takes a value from the Name column in Available tools. An entry also accepts an optional type field with the same value.

Each config entry can also set a permission_policy. The policy controls whether the tool's calls run without confirmation, require confirmation, or are evaluated individually by the server. See Permission policies for the available policy types.

The following example enables the toolset and disables web_fetch:

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
---

Disabling specific tools

To disable a tool, set enabled: false in its configs entry:

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}

Enabling only specific tools

The default_config object sets the baseline for every tool in the set, and per-tool configs entries override it. To start with everything off and enable only what you need, set default_config.enabled to false:

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash", "enabled": true },
    { "name": "read", "enabled": true },
    { "name": "write", "enabled": true }
  ]
}

Restricting web search and web fetch

The web_search and web_fetch entries also accept domain lists, a cap on fetched content, and a search location. See Restrict web search and web fetch domains.

Config entry types in the SDKs

The Python, TypeScript, Go, Java, C#, Ruby, and PHP SDKs type each configs entry per tool. The type is a union with one member per built-in tool, discriminated by type.

In Go, Java, C#, and PHP, you construct entries from typed values rather than plain dictionaries or hashes. In those SDKs, the element type of configs is the union itself, so build each entry from its per-tool member type.

You can omit type when you construct an entry, because the server infers it from name. Responses always include it. This typing does not change the JSON that an entry serializes to. A request whose entries set only name, enabled, and permission_policy is valid with or without type.

Custom tools

Custom tools are analogous to user-defined client tools in the Messages API. You specify what operations are available and what they return, and Claude determines when and how to call them.

Claude does not run a custom tool itself. It emits a structured request, your code runs the operation, and you return the result to the session.

The following example creates an agent with the built-in toolset and one custom tool, get_weather:

ant apply agent.md

---
name: Weather Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
  - type: custom
    name: get_weather
    description: Get current weather for a location
    input_schema:
      type: object
      properties:
        location:
          type: string
          description: City name
      required:
        - location
---

A custom tool's name can't start with mcp__ or ant__, or match the name of a built-in agent tool. A request that breaks this rule returns a 400 error. An agent that already has a custom tool whose name starts with ant__ accepts an update only if the update sends tools without that name, so rename or remove the tool in your next update. A new session is refused with a 400 error if such a tool is on its agent (after any overrides), on an agent in the predefined_agents list of subagents, or on an agent in the predefined_agents list of workflows. Sessions that already exist aren't affected.

The agent calls its custom tools during a session. To receive the calls and return results, see Session event stream.

For sessions that run in a self-hosted sandbox, the environment worker can serve custom tools from the sandbox. These can include tools that wrap an MCP server inside your network.

Best practices for custom tool definitions

• Provide extremely detailed descriptions. This is by far the most important factor in tool performance. The more context you can give Claude about your tools, the better it is at determining when and how to use them. Aim for three to four sentences for each tool description, more if the tool is complex. Your descriptions should cover:
  • What the tool does
  • When to use it, and when not to
  • What each parameter means and how it affects the tool's behavior
  • Any important caveats or limitations
• Consolidate related operations into fewer tools. Group actions such as create_pr, review_pr, and merge_pr into a single tool with an action parameter. Fewer, more capable tools reduce selection ambiguity and make your tool surface easier for Claude to navigate.
• Use meaningful namespacing in tool names. When your tools span multiple services or resources, prefix names with the resource (for example, db_query or storage_read). This makes tool selection unambiguous as your library grows.
• Design tool responses to return only high-signal information. Return semantic, stable identifiers (for example, slugs or UUIDs) rather than opaque internal references. Include only the fields Claude needs to determine its next step. Bloated responses waste context and make it harder for Claude to extract what matters.

Next steps