Skip to main content
POST
Tool execution endpoints use:

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:
  1. Per-request credentials
  2. credentialOverrides that point at stored secrets
  3. Stored credentials for the installed tool
  4. Matching organization or user secrets
  5. Connected OAuth account when the tool declares an OAuth provider
If more than one provider account is connected, the default connection is used unless the request includes oauth.account or oauth.connectionId. For end-user execution, RunTools resolves credentials only from the matching Hosted Connect scope:
If no matching end-user connection exists, the endpoint returns 409 connect_required. It does not fall back to builder credentials, org secrets, installed-tool credentials, or another product user’s connection.