Tool Registration

Tool registration makes your external system available as a capability that Thinklio agents can invoke. Once registered and approved, your tool appears in the tool registry and can be assigned to agents through Agent Studio or the Platform API.

Registration Fields

A tool registration includes:

  • name — unique identifier for the tool (e.g., crm.get_customer)
  • display_name — human-readable name shown in Agent Studio
  • description — what the tool does (used by the agent to decide when to invoke it)
  • parameter_schema — JSON Schema defining the tool's input parameters
  • return_schema — JSON Schema defining the tool's output shape
  • endpoint_url — the URL Thinklio will call to execute the tool
  • auth_config — how Thinklio should authenticate to your endpoint
  • trust_level — the minimum trust level required to use this tool
  • rate_limit — maximum invocations per minute

Approval

Tool registrations require organisational approval before they become active. An org admin reviews the registration and approves or rejects it. This governance step ensures external tools meet the organisation's security and compliance requirements.

Versioning

Tools are versioned. When you need to change the parameter schema or endpoint, create a new version of the tool. Existing agent assignments continue using the previous version until explicitly migrated.

Health Monitoring

Thinklio monitors the health of registered external tools by sending periodic health check requests. Unhealthy tools are circuit-broken to prevent agent interactions from failing due to unreachable external systems. You will receive webhook notifications when your tool enters or exits the unhealthy state.

Endpoints

POST/v1/toolsComing Soon

Register a tool

Register your external system as a tool available to Thinklio agents. The registration is submitted for organisational approval before becoming active.

Request Body

{
  "name": "string (required, e.g. crm.get_customer)",
  "display_name": "string (required)",
  "description": "string (required — used by the agent to decide when to invoke the tool)",
  "parameter_schema": "object (required, JSON Schema)",
  "return_schema": "object (required, JSON Schema)",
  "endpoint_url": "string (required)",
  "auth_config": {
    "type": "bearer | hmac | api_key",
    "secret_name": "string"
  },
  "trust_level": "low | standard | elevated",
  "rate_limit": {
    "requests_per_minute": "integer"
  }
}

Response

{
  "id": "tool_01hxyz",
  "name": "crm.get_customer",
  "status": "pending_approval",
  "created_at": "2026-03-19T12:00:00Z"
}