Adding Tools

Tools extend what your agent can do. There are seven types of tools.

Tool Types

All tools are managed in one place: the Tools tab.

Adding an App Tool

1. Open your agent's settings
2. Go to the Tools tab
3. Click Add Tool → App Tool
4. Search and select an app

The agent can now call this app.

What happens automatically:

• Name is extracted from the app
• Input schema becomes tool parameters
• You can customize the description shown to the agent

Configuring Setup & Default Inputs

App tools support two types of pre-configuration:

To configure:

1. After adding an app tool, click Configure Setup or Configure Default Inputs
2. Fill in the form fields
3. Save the agent

Example: An image generation tool might have:

• Setup: API key, default model, safety settings
• Default Inputs: Default resolution, style preset

The agent only sees input parameters — setup values are hidden from the LLM.

Adding an Agent Tool

Agents can delegate to other agents:

1. Go to Tools tab
2. Click Add Tool → Agent Tool
3. Select another agent

The main agent can now delegate tasks to it.

1Main Agent2├── Research Agent (gathers information)3├── Writing Agent (creates content)4└── Editor Agent (reviews and polishes)

See Sub-Agents for more details.

Adding a Webhook Tool

Connect your agent to external services:

1. Go to Tools tab
2. Click Add Tool → Webhook Tool
3. Enter a name and webhook URL
4. Optionally add a secret and input schema

When called, the hook receives:

• Tool arguments
• A callback URL to return results

See Webhooks for implementation details.

Adding a Connector Tool

Connector tools call tools on MCP servers you've connected to — Linear, Slack, GitHub, and more.

1. Go to Tools tab
2. Click Add Tool → Connector Tool
3. Select a connected MCP server
4. Choose which tools to expose

The agent sees each tool with its name and description. Authentication is handled automatically at runtime.

1tools:2  - name: list_issues3    type: mcp4    description: List Linear issues5    mcp:6      server: "linear"7      tool_name: "list_issues"

See Connectors for full documentation.

Adding a Call Tool

Call tools make HTTP requests to external APIs. Unlike webhooks, call tools execute directly — the agent sends a request and gets the response back immediately.

1. Go to Tools tab
2. Click Add Tool → Call Tool
3. Configure the tool:

Authentication

Call tools support multiple auth methods. Credentials are injected at runtime — never exposed to the agent.

Bearer auth is the most common. Set it up:

1. Store your API key as a workspace secret: belt secrets set my_api_key (prompts for the value; or pipe it on stdin)
2. In the tool config, set auth type to Bearer and reference the secret name

1auth:2  type: bearer3  secret: my_api_key

Context Templates

URLs can include {{context.X}} placeholders that resolve from per-chat context values. This lets one agent definition work across different resources.

1https://api.example.com/projects/{{context.project_id}}/tasks

When starting a chat, pass context values:

1{2  "agent_id": "agent_abc123",3  "context": {4    "project_id": "proj_456"5  }6}

Context is set once per chat and cannot change. See Context below.

Require Approval

For destructive or expensive operations, enable Require Approval. The agent pauses and waits for user confirmation before calling the tool.

Context

Context provides per-chat variables for the agent's tools. Declare the fields your agent expects, then pass values when creating a chat. The server puts the values into tool calls, call tool URLs and headers.

Declaring Context Fields

In the agent config, declare what context the agent needs:

1context:2  - name: project_id3    description: The project to operate on4    required: true5  - name: environment6    description: Target environment (staging or production)7    default: staging8    in_prompt: true

Passing Context

Context values are passed when creating a chat or running an agent:

REST API:

1{2  "agent_id": "agent_abc123",3  "context": {4    "project_id": "proj_456",5    "environment": "staging"6  }7}

Belt CLI:

1belt agent run myteam/my-agent "do the thing" \2  --context project_id=proj_456 \3  --context environment=staging

Context is immutable — once set on a chat, it cannot change. This ensures all tool calls within a conversation operate on the same resource.

How the agent uses context

Context values are not written into the system prompt. The prompt lists the variables the chat has (names and declared descriptions) and tells the agent to write {{context.NAME}} in a tool call's arguments. The server substitutes the value when the tool runs:

1{ "project": "{{context.project_id}}", "status": "open" }

• Substitution applies to app, http, call, MCP, hook and client tools.
• Sub-agents, spawn, internal tools and remote_exec get the placeholder as written.
• A sub-agent starts with no context variables. The delegating agent passes the ones it chooses in the call's variables argument, for example {"customer_id": "{{context.customer_id}}"}. The server fills the value in from the parent chat and stores it as the sub-chat's context, so neither model sees it. A placeholder the parent can't fill is dropped.
• The model's own history keeps the placeholder, so the value does not reach the model through its tool calls.
• A placeholder that names no variable is left as written.
• Keys the caller sends that the agent does not declare are variables too, listed by name.
• {{context.X}} in http and call tool URL and header templates is resolved too.

Fields with in_prompt: true are the exception: their values appear in the system prompt under a section that labels them as the caller's data and tells the model not to follow them. Use it only for values the model needs to read, such as a customer's display name.

Client Tools

Client tools execute in your application code. They're defined with a handler function that runs when the agent calls the tool.

1import { tool, string } from '@inferencesh/sdk'23const myTool = tool('search_ui')4  .describe('Scans the UI for interactive elements')5  .param('query', string('Search query'))6  .handler(async (args) => {7    // Your code runs here8    return JSON.stringify({ results: [...] })9  })

A client tool's result can also carry files, such as a screenshot: upload them first and return them as attachments. Images reach models that accept images. See Returning files.

Client tools are useful for:

• Browser automation (DOM interaction)
• Accessing local resources
• Custom business logic
• Integrating with frontend frameworks

The inference.sh browser extension follows this pattern. Its agent, infsh/browser-agent, declares client tools (read_page, get_source, fill, click, press_key, scroll, edit_dom, navigate, screenshot, list_tabs, switch_tab) that run in the extension against the user's active tab. screenshot uploads the visible tab and returns it as a tool-result attachment.

Internal Tools

Internal tools are built-in capabilities provided by the runtime. They're automatically available based on agent configuration.

Plan Tools

Task planning for complex multi-step operations:

Memory Tools

Per-chat scratch key-value notes: only this chat sees them. Use knowledge tools for facts that should reach later chats.

Widget Tool

UI rendering for interactive forms (top-level agents only):

Finish Tool

For agents to report structured output:

When output_schema is set on the agent config, the finish tool validates results against the schema. See Structured Output for details.

Skills Tool

Load skill content on-demand (when agent has skills defined):

See Skills for more details on defining and using skills.

Example App Tools

How Agents Use Tools

When you chat:

1You: Generate a sunset image23Agent: I'll create that for you.4       [Calling stable-diffusion with prompt "sunset"]56       Here's your sunset image!

The agent decides when to use which tool based on your request.

Tool Descriptions

Each tool has a description that tells the agent what it does. Good descriptions help the agent choose the right tool:

Generic:

1Search the web

Better:

1Search the web for current information. Use when you need up-to-date2facts, news, or information not in your training data.

Next

→ Sub-Agents