> ## Documentation Index > Fetch the complete documentation index at: https://docs.engini.ai/llms.txt > Use this file to discover all available pages before exploring further. # Execute tool > Executes the named tool with the given input fields. The connection to use is resolved implicitly: an explicit connectionId takes precedence, then toolsetId scopes resolution to that toolset's connection for the tool's application, and otherwise the caller's default connection for the application is used. Tool-runtime failures - the downstream call itself failing - are reported as a 200 response with isSuccess=false and an errorMessage, not as a 4xx/5xx, so callers must check isSuccess even on a successful HTTP response. A 409 is returned only when no connection can be resolved at all (no toolset connection for the app, or no default connection configured), and a 403 with errorCode=CONNECTION_BLOCKED when the resolved connection is blocked (no licence, or licence expired) - the tool is not executed at all in that case, which is why it is a 403 rather than a 200 with isSuccess=false. Every other failure uses the standard error envelope. ## OpenAPI ````yaml /developers/api-reference/openapi.json post /v1/tools/{toolSlug}/execute openapi: 3.0.0 info: title: Engini API version: v1 description: The Engini public API. servers: - url: https://api.engini.io security: - Bearer: [] - ApiKey: [] tags: - name: Auth description: Identify the caller a Developer API request is authenticated as. - name: On-prem agents description: >- Provision and manage agents that run Engini tasks inside a customer's network. - name: Applications description: >- Discover the applications (toolkits) available in Engini and their connection requirements. - name: Tools description: Browse and execute the tools exposed by Engini applications. - name: Toolsets description: Manage toolsets - named groupings of connections and tools. - name: McpServers description: >- Inspect and maintain MCP servers - the account-wide endpoints that expose Engini tools and workflows over the Model Context Protocol. Distinct from the MCPClient connection kind, which is Engini consuming a third-party MCP server. - name: Connections description: >- Manage connections to applications, including OAuth sign-in and default-connection selection. - name: Triggers description: >- Create triggers that fire when something changes in a connected app, and manage the destinations their events are delivered to. paths: /v1/tools/{toolSlug}/execute: post: tags: - Tools summary: Execute tool description: >- Executes the named tool with the given input fields. The connection to use is resolved implicitly: an explicit connectionId takes precedence, then toolsetId scopes resolution to that toolset's connection for the tool's application, and otherwise the caller's default connection for the application is used. Tool-runtime failures - the downstream call itself failing - are reported as a 200 response with isSuccess=false and an errorMessage, not as a 4xx/5xx, so callers must check isSuccess even on a successful HTTP response. A 409 is returned only when no connection can be resolved at all (no toolset connection for the app, or no default connection configured), and a 403 with errorCode=CONNECTION_BLOCKED when the resolved connection is blocked (no licence, or licence expired) - the tool is not executed at all in that case, which is why it is a 403 rather than a 200 with isSuccess=false. Every other failure uses the standard error envelope. operationId: Tools_ExecuteTool parameters: - name: toolSlug in: path required: true description: The slug identifying the tool to execute. schema: type: string x-position: 1 - name: toolsetId in: query description: Optional toolset identifier used to scope connection resolution. schema: type: string nullable: true x-position: 3 - name: connectionId in: query description: >- Optional explicit connection identifier to use instead of the implicitly resolved connection. schema: type: integer format: int32 nullable: true x-position: 4 requestBody: x-name: request description: The execution request containing the tool's input arguments. content: application/json: schema: $ref: '#/components/schemas/ToolExecuteRequest' example: fields: to: recipient@example.com subject: Hello from Engini required: true x-position: 2 responses: '200': description: The tool execution result, including success status and any output. content: application/json: schema: $ref: '#/components/schemas/ToolExecuteResponse' example: isSuccess: true errorMessage: null executionInfo: statusCode: 200 executionTime: 182.4 dataSize: 512 output: messageId: 00000000-0000-0000-0000-000000000000 historyId: 123456 '400': description: Bad request - malformed body or invalid parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - missing or invalid bearer token or API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - the caller lacks access to the resource. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - the resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- Conflict - the tool has no resolvable connection: either the supplied toolset has no connection for the tool's application (NO_TOOLSET_CONNECTION), or the caller has no default connection configured and none can be resolved (NO_DEFAULT_CONNECTION). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests - rate limit exceeded. headers: Retry-After: description: Number of seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error - an unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - Bearer: [] - ApiKey: [] x-codeSamples: - lang: python label: Python source: |- from engini import Engini client = Engini() # reads ENGINI_API_KEY result = client.tools.execute( "salesforce_getrecords", {"sobject": "Account"}, connection_id=42 ) print(result.output, result.history_id) - lang: typescript label: TypeScript source: |- import { Engini } from "@engini/sdk"; const client = new Engini(); // reads ENGINI_API_KEY const result = await client.tools.execute( "salesforce_getrecords", { sobject: "Account" }, { connectionId: 42 }, ); console.log(result.output, result.historyId); - lang: bash label: CLI source: >- engini tools call salesforce_getrecords --args '{"sobject": "Account"}' --connection 42 components: schemas: ToolExecuteRequest: type: object description: >- Body shape for POST /v1/tools/{toolSlug}/execute. activityName is intentionally absent — the activity is resolved from the path slug (+ optional ?applicationSlug=). Connection is resolved implicitly from the caller's account-user, the tool's parent application, and the optional ?toolsetId= query param. additionalProperties: false properties: fields: type: object description: Input field values for the tool, keyed by field name. nullable: true additionalProperties: {} contextValue: type: string description: Optional context value passed to the tool. nullable: true filters: type: array description: Filter conditions to apply to the tool's results. nullable: true items: $ref: '#/components/schemas/ActivityCondition' sort: type: array description: Sort clauses to apply to the tool's results. nullable: true items: $ref: '#/components/schemas/ActivitySort' offset: type: integer description: Number of leading results to skip (pagination offset). format: int32 nullable: true top: type: integer description: Maximum number of results to return. format: int32 nullable: true subItems: type: object description: >- Accepted for forward compatibility but not yet honoured on this endpoint - a caller-supplied value here is silently ignored and never reaches the tool. nullable: true additionalProperties: {} customConnectionData: type: array description: >- Per-call overrides for the resolved connection's fields; only fields marked overridable are accepted. nullable: true items: $ref: '#/components/schemas/CustomConnectionDataItem' ToolExecuteResponse: type: object description: >- 200 response shape for POST /v1/tools/{toolSlug}/execute. Tool-runtime failures (downstream API errors) return 200 + IsSuccess=false + ErrorMessage — not the standard error envelope. All non-200 responses use the standard ErrorResponse envelope, not this type. additionalProperties: false required: - isSuccess properties: isSuccess: type: boolean description: >- Whether the tool executed successfully. When false, see ErrorMessage. errorMessage: type: string description: >- Human-readable failure reason when IsSuccess is false; otherwise null. nullable: true executionInfo: description: >- Metadata about the execution (HTTP status, headers, timing, payload size). nullable: true oneOf: - $ref: '#/components/schemas/ExecutionInfo' output: description: >- The tool's result payload. Intentionally free-form (any JSON): its shape is defined by the individual tool's output schema, not by this envelope. nullable: true historyId: type: integer description: >- Identifier of the workflow-history record for this execution, when one was created. format: int32 nullable: true ErrorResponse: type: object description: >- Unified machine-readable error envelope returned by every non-200 Developer API response. additionalProperties: false required: - errorCode - message - requestId - timestamp properties: errorCode: type: string description: Machine-readable error code identifying the failure. message: type: string description: Human-readable error message. requestId: type: string description: Identifier of the request, for support/correlation. timestamp: type: string description: Timestamp when the error occurred (ISO 8601). details: type: array description: Per-field validation details, when applicable. nullable: true items: $ref: '#/components/schemas/ErrorDetail' ActivityCondition: type: object additionalProperties: false required: - fieldName - operator - value properties: fieldName: type: string operator: type: string value: type: string ActivitySort: type: object additionalProperties: false required: - fieldName - orderDirection properties: fieldName: type: string orderDirection: $ref: '#/components/schemas/OrderDirection' CustomConnectionDataItem: type: object description: A single per-call override of a connection field value. additionalProperties: false required: - fieldName - value properties: fieldName: type: string description: Name of the connection field to override. value: type: string description: Override value for the field. ExecutionInfo: type: object description: >- Metadata about a tool execution (downstream HTTP status, headers, timing, payload size). additionalProperties: false properties: statusCode: type: integer description: HTTP status code returned by the downstream call. format: int32 nullable: true headers: type: object description: Response headers from the downstream call, keyed by header name. nullable: true additionalProperties: type: string executionTime: type: number description: Execution time in milliseconds. format: double nullable: true dataSize: type: integer description: Size of the response payload in bytes. format: int64 nullable: true ErrorDetail: type: object description: A single field-level error detail within an ErrorResponse. additionalProperties: false required: - field - issue properties: field: type: string description: Name of the field the issue relates to. issue: type: string description: Description of the issue with the field. OrderDirection: type: integer description: '' x-enumNames: - Ascending - Descending enum: - 1 - -1 securitySchemes: Bearer: type: http description: Enter your JWT token scheme: bearer bearerFormat: JWT ApiKey: type: apiKey description: >- Opaque Developer API key (prefix `eng_`). Authenticates as the key's owner and resolves the account automatically. name: x-api-key in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.