Skip to main content
POST
Register Tool

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

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".
string
required
Human-readable name for the tool, shown in dashboards and approval workflows.
string
Detailed description of the tool’s functionality, expected inputs, and outputs.
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.
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.
boolean
Whether invocations require human approval before execution. Default: false. Automatically set to true for "critical" risk tools.
integer
Maximum invocations per agent per minute. Default: 60. Range: 1-10000.
string
Organizational category. Default: "general". Examples: "search", "communication", "database", "payment", "analytics".
object
Arbitrary key-value metadata for the tool. Useful for storing endpoint URLs, auth configuration, schema references, or integration details.

Response

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

Example


Risk Level Auto-Elevation

The platform scans tool names and scope requirements for dangerous action verbs. If detected, the risk level is automatically elevated: 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>