Skip to main content
POST
/
v1
/
tools
Register Tool
curl --request POST \
  --url https://api.truthlocks.com/v1/tools \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "sentiment-analysis",
  "description": "Analyzes text sentiment",
  "schema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string"
      }
    },
    "required": [
      "text"
    ]
  },
  "agent_id": "550e8400-e29b-41d4-a716-446655440000"
}
'
{
  "tool_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "description": "<string>",
  "schema": {},
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z"
}

​
Register Tool

POST /v1/tools Registers a new tool in the tenant’s MAIP tool registry. Tools represent external capabilities (APIs, functions, services) that machine agents can invoke. Each tool is associated with a required scope, risk level, and optional approval gate. The platform automatically elevates the risk level to "high" if the tool name or required scope contains dangerous action verbs (write, delete, send, execute, deploy, destroy, drop, truncate).
Tool names must be unique per tenant. Attempting to register a tool with a name that already exists returns 409 Conflict.

​
Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

​
Request Body

​
name
string
required
Unique machine-readable name for the tool. Used as the identifier in invocation URLs. Must contain only alphanumeric characters, hyphens, underscores, and dots. Examples: "search.web", "crm-contact-lookup", "payment_process".
​
display_name
string
required
Human-readable name for the tool, shown in dashboards and approval workflows.
​
description
string
Detailed description of the tool’s functionality, expected inputs, and outputs.
​
scope_required
string
required
The permission scope an agent must have to invoke this tool. Uses resource:action format (e.g., "tool:search.web", "data:write"). The agent’s scope set is checked against this value at invocation time.
​
risk_level
string
Risk classification for the tool. One of: "low", "medium", "high", "critical". Default: "medium". Automatically elevated to "high" if the tool name or scope contains dangerous verbs.
​
requires_approval
boolean
Whether invocations require human approval before execution. Default: false. Automatically set to true for "critical" risk tools.
​
rate_limit_per_minute
integer
Maximum invocations per agent per minute. Default: 60. Range: 1-10000.
​
category
string
Organizational category. Default: "general". Examples: "search", "communication", "database", "payment", "analytics".
​
metadata
object
Arbitrary key-value metadata for the tool. Useful for storing endpoint URLs, auth configuration, schema references, or integration details.

​
Response

​
id
string
UUID of the newly registered tool.
​
tenant_id
string
UUID of the owning tenant.
​
name
string
Machine-readable tool name.
​
display_name
string
Human-readable tool name.
​
description
string
Tool description.
​
scope_required
string
Required scope for invocation.
​
risk_level
string
Effective risk classification (may be auto-elevated).
​
requires_approval
boolean
Whether human approval is required.
​
rate_limit_per_minute
integer
Per-agent rate limit.
​
category
string
Tool category.
​
status
string
Tool status. Always "active" on creation.
​
metadata
object
Tool metadata.
​
created_at
string
ISO 8601 creation timestamp.
​
updated_at
string
ISO 8601 last-updated timestamp.

​
Example

curl -X POST https://api.truthlocks.com/v1/tools \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search.web",
    "display_name": "Web Search",
    "description": "Performs web searches via SerpAPI and returns structured results",
    "scope_required": "tool:search.web",
    "risk_level": "low",
    "rate_limit_per_minute": 30,
    "category": "search",
    "metadata": {
      "endpoint_url": "https://serpapi.com/search",
      "auth_type": "api_key",
      "max_results": 10
    }
  }'

​
Risk Level Auto-Elevation

The platform scans tool names and scope requirements for dangerous action verbs. If detected, the risk level is automatically elevated:
Detected VerbAuto-Elevation
write, delete, sendElevated to "high"
execute, deploy, destroyElevated to "high"
drop, truncateElevated to "high"
Tools with "critical" risk level always require human approval regardless of the requires_approval setting.

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
name
string
required

Unique tool name

​
agent_id
string<uuid>
required

Owning agent

​
description
string

Human-readable tool description

​
schema
object

JSON Schema defining the tool input arguments

Response

Tool registered

​
tool_id
string<uuid>
​
name
string
​
description
string
​
schema
object
​
agent_id
string<uuid>
​
created_at
string<date-time>