Register Tool
Agent Sessions & Tools
Register Tool
Register a tool in the MAIP tool registry with scope requirements, risk classification, and rate limits
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
RequiresX-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
API key for machine-to-machine authentication
Body
application/json

