Integrate · Agent Tool Integrations

Custom Connection Tools

Create narrow agent tools on supported BotDojo connections using the provider's API without exposing credentials or a general request client to the agent.

5 min read

Custom connection tools let a project administrator add purpose-built actions to an existing connection. The administrator defines each tool in TypeScript, while the agent sees only its published name, description, and input schema.

Salesforce, HubSpot, and Oracle Fusion support custom connection tools. Oracle Fusion custom tools are read-only and accept only approved Fusion Financials, Supply Chain Management, and CRM REST resource paths. Other integrations may add the same capability as their provider-specific request policies become available.

How Custom Connection Tools Work

A custom connection tool has two separate interfaces:

Administrator interface: TypeScript code can call the connected provider through connection.http.request(...).
Agent interface: The agent can invoke only the published tool and provide values allowed by its input schema.

BotDojo supplies the provider base URL and current connection authentication. The program cannot choose another host or read the credentials, and BotDojo does not expose the request client itself as a general agent tool. Each provider also controls the allowed HTTP methods, paths, headers, request sizes, response sizes, and execution limits.

Custom tool programs run in BotDojo's restricted-network code sandbox. They can reach the selected integration only through the bound request client.

Before You Start

You need:

project administrator access;
a supported integration connection in the project;
the provider's API documentation;
permission in the connected system to perform the intended operation; and
a narrow definition of the values the agent may choose.

Start write actions against a provider sandbox or test tenant when one is available.

Create A Tool

Open the project and select Connections.
Open a connection that supports custom tools.
In Tools, select Add Custom Tool.

The Salesforce connection editor with the Add Custom Tool button

Edit the starter source in the TypeScript editor.
Review the Tool definition preview. This is the interface the agent will receive after publication.

The custom tool editor showing Salesforce request code and the agent-facing tool definition

Select Validate to check the source and schema.
Select Save draft to save work without changing the published tool.
Select Publish when the exact draft is ready for agents.
Enable the tool and choose Deny, Ask, or Allow under Tool Configuration, then save the connection.

Only a published, enabled tool is available to agents. A tool's first publication defaults to Ask. Publishing a later revision preserves its current permission.

The connection's tool settings control in-app use. An external MCP client is controlled by its resource-token policy.

Define The Agent Interface

Each source file declares exactly one tool. The path below illustrates the request shape; use the provider guide for a valid API path.

const tool = defineConnectionTool({
	name: "one_specific_action",
	description: "Explain exactly when the agent should use this action.",
	inputSchema: {
		type: "object",
		properties: {
			recordId: {
				type: "string",
				description: "The confirmed record ID.",
			},
		},
		required: ["recordId"],
		additionalProperties: false,
	},
	handler: async (input, { connection }) => {
		const response = await connection.http.request({
			method: "GET",
			path: "/provider/relative/path/" + input.recordId,
		});

		return { record: response.data };
	},
});

The top-level name, description, and inputSchema must be literal values so BotDojo can validate the agent interface without running the program. Tool names may contain 1–64 letters, numbers, underscores, and hyphens.

Use a closed object schema with additionalProperties: false. Add constraints such as pattern, enum, minimum, and maxLength when they reduce the chance of an invalid or overly broad operation.

Build A Narrow Action

The safest tool keeps policy decisions in administrator-authored code:

Let the agent provide only values that must vary for the task.
Keep the provider object, method, fields, and fixed state changes in code.
Return only the data the agent needs for its next decision.
Give write tools explicit names and descriptions, such as add_case_comment, instead of generic names such as api_request.
Use Ask while testing and for actions that need human approval.

Do not accept a URL, HTTP method, arbitrary request body, object API name, or field API name from the agent unless that variability is a deliberate part of the action's policy.

Drafts, Publishing, And Changes

Validate checks the current editor contents without saving or publishing.
Save draft creates a new saved revision. Agents continue using the last published revision.
Publish makes the exact saved draft current and refreshes the connection's discoverable tools.
Renaming a published tool moves its existing permission to the new name.
Archive removes the custom tool and its saved permission from the connection.

If another administrator changes the same connection while you are editing, reload it before saving or publishing. This prevents one editor from overwriting a newer revision.

Troubleshooting

The connection does not show Add Custom Tool

The integration provider has not enabled code-authored tools. Salesforce, HubSpot, and Oracle Fusion currently support them. Oracle Fusion allows only read-only requests to approved Fusion REST resource paths.

The tool is not available to an agent

Confirm that the tool is published, enabled, present in the connection's current tool snapshot, and permitted for the invoking user or agent. A saved draft alone is not discoverable.

Validation rejects the source

Keep one top-level const tool = defineConnectionTool({...}) declaration. Use literal tool metadata and a closed object input schema. Remove imports and ambient runtime APIs such as fetch, process, and require.

The provider rejects the request

Check the provider documentation for the HTTP method, relative path, query, and JSON body. Also verify that the connected account can perform the action. Provider permissions continue to apply even when BotDojo allows the tool.

The published tool still behaves like an older version

Open the tool and confirm its status is Published, with no Unpublished changes. Refresh the connection if publication reports that tool discovery did not refresh.