Tools
Execute Tool
Execute one Tool Hub action
POST
Tool execution endpoints use:
If no matching end-user connection exists, the endpoint returns
Path Parameters
string
required
Tool slug.
Request Body
string
required
Tool action name.
object
Action parameters.
string
Optional credential isolation mode. Use
end_user with endUser for customer-owned product integrations. In end-user mode, Tool Hub never uses per-request, installed, org, or builder credentials.object
Optional per-request credentials. Prefer stored secrets or OAuth connections for production.
object
Map tool credential field names to secret names so values stay server-side.
credentials and credentialOverrides are accepted only on direct Tool Hub API/SDK calls. Agent-runtime tool calls use an internal signed capability and cannot provide credential fields in request JSON.
object
Optional account selector for OAuth-backed tools. Use
oauth.account for a human-readable email, username, display name, provider account ID, or connection ID. Use oauth.connectionId when you need an exact Connected Apps connection.object
App-scoped customer identity for Hosted Connect. Requires
endUser.appId and endUser.externalUserId. When present, credentialScope is treated as end_user.Response
boolean
Whether execution succeeded.
object
Tool-specific result when successful.
object
Tool-specific error when unsuccessful. Tool failures can return a non-2xx HTTP status.
number
Server-side execution duration.
Tool calls are billed before execution. If the organization does not have enough credits, the endpoint returns
402 insufficient_credits. If billing is temporarily unavailable, it returns 503 billing_unavailable.Credential Resolution
For org-scoped tool execution, RunTools resolves credentials in this order:- Per-request
credentials credentialOverridesthat point at stored secrets- Stored credentials for the installed tool
- Matching organization or user secrets
- Connected OAuth account when the tool declares an OAuth provider
oauth.account or oauth.connectionId.
For end-user execution, RunTools resolves credentials only from the matching Hosted Connect scope:
409 connect_required. It does not fall back to builder credentials, org secrets, installed-tool credentials, or another product user’s connection.