You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Custom Tools let you define your own functions that agents can call, without needing an external MCP server. You write a JSON schema describing the function and the JavaScript code that runs when the agent invokes it.
9
+
10
+
## What Is a Custom Tool?
11
+
12
+
A custom tool has three parts:
13
+
14
+
| Part | Description |
15
+
|------|-------------|
16
+
|**Schema**| OpenAI function-calling format — name, description, and parameters. This is what the agent sees when deciding whether to call the tool. |
17
+
|**Code**| JavaScript that runs when the tool is called. Parameters come in as variables matching the schema. |
18
+
|**Scope**| Custom tools are workspace-scoped and available to every agent in that workspace. |
19
+
20
+
Use custom tools when you need tightly-scoped logic that doesn't warrant spinning up a full MCP server — one-off API calls, formatting helpers, internal utilities, etc.
21
+
22
+
## Creating a Custom Tool
23
+
24
+
1. Navigate to **Settings → Custom Tools**
25
+
2. Click **Add**
26
+
3. Fill out the **Schema** tab with your function definition
27
+
4. Write your implementation in the **Code** tab
28
+
5. Click **Save**
29
+
30
+
<Callouttype="info">
31
+
You can also create a custom tool directly from an Agent block — click **Add tool… → Create Tool** in the tool dropdown. The schema editor has an AI-generation option that drafts the schema from a plain-English description.
32
+
</Callout>
33
+
34
+
## Schema Format
35
+
36
+
Custom tool schemas follow the OpenAI function-calling spec:
37
+
38
+
```json
39
+
{
40
+
"type": "function",
41
+
"function": {
42
+
"name": "get_weather",
43
+
"description": "Get the current weather for a city",
44
+
"parameters": {
45
+
"type": "object",
46
+
"properties": {
47
+
"city": {
48
+
"type": "string",
49
+
"description": "The city to get weather for"
50
+
}
51
+
},
52
+
"required": ["city"]
53
+
}
54
+
}
55
+
}
56
+
```
57
+
58
+
The `name` must be lowercase, use underscores, and match what your code expects as input.
59
+
60
+
## Using Custom Tools in Agents
61
+
62
+
Once created, your tools become available in any Agent block:
63
+
64
+
1. Open an **Agent** block
65
+
2. In the **Tools** section, click **Add tool…**
66
+
3. Under **Custom Tools**, click the tool you want to add
67
+
4. The agent can now call the tool the same way it calls MCP tools or built-in tools
68
+
69
+
## Custom Tools vs MCP Tools
70
+
71
+
||**Custom Tools**|**MCP Tools**|
72
+
|---|---|---|
73
+
|**Defined**| Inline — schema + code in Sim | External MCP server |
74
+
|**Hosting**| Runs inside Sim | Runs on your server |
You can also configure MCP servers directly from the toolbar in an Agent block for quick setup.
37
60
</Callout>
38
61
39
62
### Refresh Tools
40
63
41
-
Click **Refresh** on a server to fetch the latest tool schemas and automatically update any agent blocks using those tools with the new parameter definitions.
64
+
To auto-refresh an MCP tool already in use by an agent, go to **Settings → MCP Tools**, open the server's details, and click **Refresh**. This fetches the latest tool schemas and automatically updates any agent blocks using those tools with the new parameter definitions.
42
65
43
66
## Using MCP Tools in Agents
44
67
45
68
Once MCP servers are configured, their tools become available within your agent blocks:
46
69
47
70
<divclassName="flex justify-center">
48
71
<Image
49
-
src="/static/blocks/mcp-2.png"
72
+
src="/static/blocks/mcp-agent-dropdown.png"
50
73
alt="Using MCP Tool in Agent Block"
51
74
width={700}
52
75
height={450}
@@ -55,17 +78,33 @@ Once MCP servers are configured, their tools become available within your agent
55
78
</div>
56
79
57
80
1. Open an **Agent** block
58
-
2. In the **Tools** section, you'll see available MCP tools
59
-
3. Select the tools you want the agent to use
60
-
4. The agent can now access these tools during execution
81
+
2. In the **Tools** section, click **Add tool…**
82
+
3. Under **MCP Servers**, click a server to see its tools
83
+
84
+
<divclassName="flex justify-center">
85
+
<Image
86
+
src="/static/blocks/mcp-agent-tools.png"
87
+
alt="MCP tools list for a selected server"
88
+
width={400}
89
+
height={400}
90
+
className="my-6"
91
+
/>
92
+
</div>
93
+
94
+
4. Select individual tools, or choose **Use all N tools** to add every tool from that server
95
+
5. The agent can now access these tools during execution
96
+
97
+
<Callouttype="info">
98
+
If you haven't configured a server yet, click **Add MCP Server** at the top of the dropdown to open the setup modal without leaving the block.
99
+
</Callout>
61
100
62
101
## Standalone MCP Tool Block
63
102
64
103
For more granular control, you can use the dedicated MCP Tool block to execute specific MCP tools:
65
104
66
105
<divclassName="flex justify-center">
67
106
<Image
68
-
src="/static/blocks/mcp-3.png"
107
+
src="/static/blocks/mcp-tool-block.png"
69
108
alt="Standalone MCP Tool Block"
70
109
width={700}
71
110
height={450}
@@ -79,17 +118,14 @@ The MCP Tool block allows you to:
79
118
- Use the tool's output in subsequent workflow steps
80
119
- Chain multiple MCP tools together
81
120
82
-
### When to Use MCP Tool vs Agent
83
-
84
-
**Use Agent with MCP tools when:**
85
-
- You want the AI to decide which tools to use
86
-
- You need complex reasoning about when and how to use tools
87
-
- You want natural language interaction with the tools
121
+
## When to Use MCP Tool vs Agent
88
122
89
-
**Use MCP Tool block when:**
90
-
- You need deterministic tool execution
91
-
- You want to execute a specific tool with known parameters
92
-
- You're building structured workflows with predictable steps
123
+
||**Agent with MCP tools**|**MCP Tool block**|
124
+
|---|---|---|
125
+
|**Execution**| AI decides which tools to call | Deterministic — runs the tool you pick |
126
+
|**Parameters**| AI chooses at runtime | You set them explicitly |
0 commit comments