> ## Documentation Index > Fetch the complete documentation index at: https://docs.slng.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run Tool > Test-run a prepared draft with sample input and confirmed side effects. Context-bound tool types return 400, curated tools return 403 (duplicate one first), and non-api_request tools must be built before running or return 409. An api_request run uses optimistic concurrency and returns 409 with code TOOL_CHANGED if the config hash changed mid-run. Updates last_run_status and the proven hash. ## OpenAPI ````yaml /api-reference/agents/tools.oas.yaml post /v1/agents/tools/{tool_id}/run openapi: 3.1.0 info: title: SLNG Agent Resources — Tools version: 1.0.0 description: >- Public API for organisation tools, MCP servers, Vault entries, and BYOK client models. contact: name: SLNG Support email: support@slng.ai servers: - url: https://api.agents.slng.ai description: Production security: - bearerAuth: [] paths: /v1/agents/tools/{tool_id}/run: post: summary: Run Tool description: >- Test-run a prepared draft with sample input and confirmed side effects. Context-bound tool types return 400, curated tools return 403 (duplicate one first), and non-api_request tools must be built before running or return 409. An api_request run uses optimistic concurrency and returns 409 with code TOOL_CHANGED if the config hash changed mid-run. Updates last_run_status and the proven hash. operationId: runTool parameters: - name: tool_id in: path required: true description: >- The tool UUID. Curated tools are visible but read-only, and a tool owned by another organisation returns 404. schema: type: string format: uuid title: Tool Id requestBody: required: true description: The sample input and side-effect confirmation for the test run. content: application/json: schema: $ref: '#/components/schemas/RunRequest' example: sample_input: customer_id: cus_123 confirm_side_effects: true responses: '200': description: >- The result of the test run: status, latency, any returned output, output-schema validation, logs, and the publish gate status. content: application/json: schema: $ref: '#/components/schemas/RunResult' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/ConflictError' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalServerError' components: schemas: RunRequest: properties: sample_input: additionalProperties: true type: object title: Sample Input confirm_side_effects: type: boolean const: true title: Confirm Side Effects type: object required: - confirm_side_effects title: RunRequest description: >- Test-run request with sample input and explicit confirmation of side effects. example: sample_input: customer_id: cus_123 confirm_side_effects: true RunResult: properties: status: type: string enum: - succeeded - failed - timed_out title: Status latency_ms: type: integer title: Latency Ms output_json: anyOf: - {} - type: 'null' title: Output Json logs: items: type: string type: array title: Logs validation: type: string enum: - valid - mismatch - na description: >- Whether the run output matched the declared output schema: `valid` (matched), `mismatch` (did not match), or `na` (no schema to check against). title: Validation error: anyOf: - type: string - type: 'null' title: Error proven_hash: anyOf: - type: string - type: 'null' title: Proven Hash gate_status: anyOf: - $ref: '#/components/schemas/GateStatus' - type: 'null' type: object required: - status - latency_ms - validation title: RunResult description: >- Outcome of a test run, including status, latency, output, and gate status. example: status: succeeded latency_ms: 142 output_json: id: cus_123 region: eu logs: [] validation: valid proven_hash: 9f2b7c1a3d4e5f60 GateStatus: properties: static: anyOf: - $ref: '#/components/schemas/StaticGate' - $ref: '#/components/schemas/TypedStaticGate' - type: 'null' title: Static green_run: anyOf: - $ref: '#/components/schemas/GreenRun' - type: 'null' config_valid: anyOf: - $ref: '#/components/schemas/CheckResult' - type: 'null' code_environment: anyOf: - $ref: '#/components/schemas/CheckResult' - type: 'null' content_current: anyOf: - $ref: '#/components/schemas/CheckResult' - type: 'null' type: object title: GateStatus description: |- Gate set is selected by tool_type (V2): data → static + green_run; code also reports config_valid; ctx-bound → config_valid ONLY. ApiErrorResponse: type: object required: - detail - error properties: detail: type: string error: $ref: '#/components/schemas/ApiErrorDetail' description: Standard error envelope returned for a failed request. example: detail: The tool is attached to an active agent. error: code: TOOL_DELETE_BLOCKED message: The tool is attached to an active agent. retryable: false StaticGate: properties: parse: $ref: '#/components/schemas/CheckResult' models: $ref: '#/components/schemas/CheckResult' schema: $ref: '#/components/schemas/CheckResult' secrets_exist: $ref: '#/components/schemas/CheckResult' name_unique: $ref: '#/components/schemas/CheckResult' type: object required: - parse - models - schema - secrets_exist - name_unique title: Static gate description: A publish readiness gate evaluated from static analysis. TypedStaticGate: properties: config_valid: $ref: '#/components/schemas/CheckResult' secrets_exist: $ref: '#/components/schemas/CheckResult' name_unique: $ref: '#/components/schemas/CheckResult' type: object required: - config_valid - secrets_exist - name_unique title: Typed static gate description: A typed publish readiness gate evaluated from static analysis. GreenRun: properties: passed: type: boolean title: Passed proven_hash: anyOf: - type: string - type: 'null' title: Proven Hash type: object required: - passed title: GreenRun description: >- Result of the green-run gate, with the hash proven by a successful test run. CheckResult: properties: passed: type: boolean title: Passed detail: anyOf: - type: string - type: 'null' title: Detail type: object required: - passed title: CheckResult description: >- Result of one publish readiness check, with a pass flag and optional detail. ApiErrorDetail: type: object required: - code - message properties: code: type: string description: Stable machine-readable error code. example: TOOL_DELETE_BLOCKED message: type: string example: The tool is attached to an active agent. request_id: type: - string - 'null' example: req_01HZYABCDEF retryable: type: boolean example: false fields: type: array example: [] items: type: object additionalProperties: true description: >- Structured error detail with a stable code, a human-readable message, and optional per-field errors. example: code: TOOL_DELETE_BLOCKED message: The tool is attached to an active agent. request_id: req_01HZYABCDEF retryable: false fields: [] responses: UnauthorizedError: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' ForbiddenError: description: >- The caller cannot perform this operation, or public resource access is disabled for the organisation. Disabled access returns code PUBLIC_SHARED_RESOURCES_DISABLED with retryable set to false. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' NotFoundError: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' ConflictError: description: The requested change conflicts with the current resource state. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' ValidationError: description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' RateLimitError: description: The organisation's request limit was exceeded. headers: Retry-After: schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' InternalServerError: description: The operation failed. The response does not expose secret values. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: SLNG API key description: Your SLNG consumer API key. ````