Tool Execution Contract

When a Thinklio agent invokes your registered tool, the tool service sends a POST request to your configured endpoint. This page describes the execution contract your endpoint must implement.

Request Format

Thinklio sends a JSON POST request to your endpoint:

``json { "tool_call_id": "tc_01hxyz...", "tool_name": "crm.get_customer", "parameters": { "customer_id": "cust_abc123", "include_history": true }, "context": { "agent_id": "agt_01hxyz...", "interaction_id": "int_01hxyz...", "user_id": "usr_01hxyz..." } } ``

Response Format

Your endpoint must return a JSON response conforming to the tool's registered return_schema:

``json { "result": { "customer_name": "Acme Corp", "plan": "enterprise", "mrr": 4900 } } ``

For errors, return a non-2xx status with an error object:

``json { "error": { "code": "customer_not_found", "message": "No customer with ID cust_abc123 exists." } } ``

Verifying Requests

Verify that requests to your endpoint originated from Thinklio using the X-Thinklio-Signature header. The signature is an HMAC-SHA256 of the raw request body, signed with your tool's signing secret.

Timeouts

Your endpoint must respond within the configured timeout (default: 10 seconds). Requests that exceed the timeout are cancelled and the agent receives a tool error. Design your endpoint to be fast; for slow operations, return a job reference and implement a polling or callback pattern.

Idempotency

Tool calls may be retried on transient failure. If your tool has side effects, use the tool_call_id as an idempotency key.