Tools API

The Tools API lets developers run a configured Tool with explicit field values before the tool is used by an AI Agent stencil in live workflow execution.

Key concepts

Term	Definition
Tool ID	Identifier of the saved REST API or Script tool.
AI fields	Named inputs the AI Agent supplies during workflow execution.
Test fields	Explicit values supplied by a developer or tester for a test run.
Runtime message	Optional user-facing message configured for execution, delay, or failure states.

What you can do

Action	Endpoint
Test a tool	POST /llm-chain/tool/test

Test a tool

Use the test endpoint for automated verification, regression checks, or integration setup validation.

curl -X POST "$OCTO_BASE_URL/llm-chain/tool/test" \
  -H "Authorization: Bearer $OCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolId": "tool_123",
    "fields": {
      "email": "customer@example.com",
      "orderId": "ORDER-123"
    }
  }'

The fields object should match the AI fields configured on the Tool page. REST API tools can reference those values with template variables such as ${fields.email} in URLs, query parameters, headers, or body JSON. Script tools receive equivalent runtime context from the platform.

Interpreting results

Result area	Meaning
Status	Whether the tool test completed successfully.
Summary	HTTP status, status text, duration, or script execution status.
Headers	Response headers returned by a REST API tool.
Body	Response body or script return payload.
Error	Runtime, timeout, validation, network, or template-substitution failure.

Failure checks

1. Confirm required AI fields were supplied in fields.
2. Check template variables for spelling and casing.
3. Verify headers and credentials are stored in the tool configuration.
4. Confirm the external service is reachable from the Octo runtime.
5. Review timeout, failure message, delay message, and repeat settings on the Tool page.

FAQ

Should production users call this endpoint during conversations? No. Workflow execution invokes tools automatically through AI Agent and Tool stencils. This endpoint is for testing and developer automation.

Can I test a tool that has unsaved UI changes? Save the tool first so the backend test route runs the same configuration that workflows will use.

Related pages

• Tools - configure REST API and Script tools
• AI Workflows - expose tools to AI Agent stencils
• AI Workflow Execution - run workflows that may call tools