> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Tools
> Equip your agent with built-in, MCP, and custom tools.
Tools determine **what an Agent can do**. By configuring the `tools` field when creating or updating an Agent, you precisely control its capabilities.
## What Tools Do
When executing a task, the Agent decides which capabilities it can call based on the `tools` configuration. Built-in tools are configured through `{ "type": "agent_toolset_20260401", "enabled_tools": [...] }`, selectively enabling atomic tools in the `enabled_tools` array. Client-side custom tools are configured as separate `{ "type": "custom", ... }` entries.
When `enabled_tools` is a non-empty allowlist, tools outside the list are not visible to the model and no invocation attempt is made. When `enabled_tools` is omitted or an empty array, **all** built-in tools are exposed to the model. When the `tools` field itself is omitted or set to `[]`, the model receives no tool schema at all (see FAQ below).
## Available Tools
| Tool name (enabled\_tools value) | Purpose | Typical use cases |
| -------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `Bash` | Shell command execution | Installing dependencies, running scripts, calling APIs with curl |
| `Read` | File reading | Viewing mounted files, code reading |
| `Write` | File writing (create/overwrite) | Generating reports, producing output |
| `Edit` | Partial file editing | Changing configuration, editing code |
| `Glob` | Glob pattern file listing | Finding code files |
| `Grep` | File content search | Locating strings |
| `WebFetch` | HTTP GET a single page | Fetching documentation/pages |
| `WebSearch` | Web search | Looking up information |
| `DeliverArtifacts` | Deliver files the Agent produced under `/data/` to the user as downloadable artifacts. | When the user asks for a file/report/export as a deliverable |
Notes:
* Tool names must use the exact values in the table, and event streams use the same values
* Omitting `enabled_tools` or passing an empty array `[]` enables **all** built-in tools (including `DeliverArtifacts` listed above). If you want the Agent to have no tools at all, omit the whole `tools` field or set it to `[]`.
* When `enabled_tools` is a **non-empty allowlist**, only the listed tools are visible to the model. To use `DeliverArtifacts` alongside a custom allowlist, you must include it explicitly (e.g. `["Bash", "Write", "DeliverArtifacts"]`).
* Each tool name in `enabled_tools` is validated — writing an unknown name (e.g. `"Foo"`) returns **400**: `"unknown tool name 'Foo'"`
* Built-in and MCP tool permissions are configured with `configs[].permission_policy`; see [Permission Policies](/cloud-agents/permission-policies).
* The old per-tool-object schema (such as `{"type": "bash_20250124"}`) is no longer supported
## Current Format: Single Object
Built-in tool configuration uses a single object that toggles specific tools via the `enabled_tools` array:
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
}
```
Set when creating an Agent:
```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/agents \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "dev-agent",
"model": "ultimate",
"system": "You are a development assistant",
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
}'
```
## Custom Client-Side Tools
Custom tools let your application expose actions that the Agent can request but the platform does not execute directly. When the Agent calls a custom tool, the session pauses with a `requires_action` stop reason. Your client executes the tool and sends the result back with a `user.custom_tool_result` event.
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Read", "Write"]
},
{
"type": "custom",
"name": "lookup_order",
"description": "Look up an order by ID.",
"input_schema": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"]
}
}
]
}
```
Custom tool rules:
* `name`, `description`, and `input_schema` are required.
* `input_schema` must be a JSON Schema object with `"type": "object"`.
* Custom tool names are case-insensitively unique within the Agent.
* A custom tool name must not collide with a built-in tool name such as `Bash` or `Read`.
* Names starting with `mcp__` are reserved for MCP tools.
* `permission_policy` is not supported on custom tools because the client executes them.
See [Send an event](/cloud-agents/api/sessions/send-event) for the `user.custom_tool_result` response flow.
## Configuration Examples
### Minimal (CLI only)
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash"]
}
]
}
```
### Full Development Stack
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
}
```
## Update Tool Configuration
Use `POST` to update an Agent's tool configuration. The request must include the current `version`; when `tools` is provided, it replaces the stored tool array.
```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"version": 1,
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit"]
}
]
}'
```
Agent updates use merge semantics for omitted fields. Array fields such as `tools`, `mcp_servers`, and `skills` are replaced when explicitly provided. You must include the `version` field for optimistic concurrency control:
* If the supplied version matches the current version: 200, version increments by 1
* If the supplied version is stale: 409 `{ error: { type: "conflict_error", message: "Version conflict. Expected version N, got M." }}`
Existing Sessions are unaffected; new Sessions use the updated configuration.
## Inspect Current Tool Configuration
```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
-H "Authorization: Bearer $QODER_PAT" | jq '.tools'
```
Example output:
```json theme={null}
[
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
```
## FAQ
**Q: What if I don't configure `tools`?** A: The Agent has no tools available and can only have plain-text conversations. To give the Agent any tool capability, pass at least `[{"type":"agent_toolset_20260401"}]` (which enables all built-in tools).
**Q: Can I override tools at the Session level?** A: Not currently. Tool configuration is bound to the Agent, and all Sessions for that Agent share the same toolset.
**Q: Does the order of `tools` matter?** A: No. The Agent decides which tool to invoke based on the task context.
**Q: Will the version suffix change over time?** A: Yes. As new tool versions ship, new dated suffixes are introduced. Watch the changelog and adopt the latest suffix.
## Next steps
Control whether tool calls are allowed, prompted, or denied.
Attach domain expertise to your Agent.
Review Agent configuration.
Manage session lifecycle.