Skip to main content
POST
/
agents
/
{agent_id}
/
tools
Create Agent Tool
curl --request POST \
  --url https://api.example.com/agents/{agent_id}/tools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tool_key": "<string>",
  "instance_name": "<string>",
  "display_name": "<string>",
  "enabled": true,
  "config": {
    "description": "<string>",
    "disallow_interruptions": true,
    "requires_caller_consent": true,
    "cost_unit": "<string>",
    "goodbye_instructions": "<string>",
    "goodbye_max_duration_ms": 10250,
    "delete_room": true,
    "wait_for_playout": true,
    "record_end_reason": true,
    "default_inter_digit_ms": 1000,
    "inter_digit_ms": 1000,
    "default_duration_ms": 1020,
    "default_volume": 50,
    "ivr_detection": true,
    "allowed_digits": "<string>",
    "max_sequence_length": 64,
    "sip_trunk_id": "<string>",
    "sip_trunk_address": "<string>",
    "sip_headers": {},
    "hold_audio_url": "<string>",
    "hold_audio_loop": true,
    "transfer_briefing_prompt": "<string>",
    "transfer_briefing_voice_id": "<string>",
    "transfer_announcement_prompt": "<string>",
    "transfer_announcement": "<string>",
    "transfer_timeout_s": 150,
    "transfer_max_attempts": 5,
    "fallback_target_name": "<string>",
    "take_message_on_failure": true,
    "target_directory": [
      "<string>"
    ],
    "target_number": "<string>",
    "targets": [
      {}
    ],
    "play_dialtone": true,
    "cold_transfer_announcement_prompt": "<string>",
    "specialists": [
      {}
    ],
    "prefer_warm": true,
    "handoff_announcement_prompt": "<string>",
    "preserve_chat_ctx": true,
    "chat_ctx_token_cap": 32128,
    "service_account_email": "<string>",
    "oauth_refresh_token_ref": "<string>",
    "default_spreadsheet_id": "<string>",
    "allowed_spreadsheet_ids": [
      "<string>"
    ],
    "max_rows_per_read": 5000,
    "max_rows_per_write": 2500,
    "result_summarization": true,
    "spreadsheet_id": "<string>",
    "sheet_name": "<string>",
    "credentials_json": {},
    "column_mapping": {},
    "data_source_url": "<string>",
    "auth_secret_ref": "<string>",
    "query_template": "<string>",
    "allowed_filters": [
      "<string>"
    ],
    "default_limit": 250,
    "max_limit": 500,
    "pii_redaction": true,
    "cache_ttl_s": 43200,
    "top_k_default": 10,
    "similarity_threshold": 0.5,
    "knowledge_namespace": "<string>",
    "account_sid_ref": "<string>",
    "auth_token_ref": "<string>",
    "from_e164": "<string>",
    "default_from": "<string>",
    "allowed_destination_country_codes": [
      "<string>"
    ],
    "allow_send_to_caller_only": true,
    "max_message_length": 1000,
    "template_id": "<string>",
    "template": "<string>",
    "daily_quota_per_number": 500,
    "require_explicit_consent": true,
    "url": "<string>",
    "url_allowlist": [
      "<string>"
    ],
    "allowed_methods": [
      "<string>"
    ],
    "default_headers": {},
    "method": "<string>",
    "headers": {},
    "auth": {
      "type": "none",
      "token": "<string>",
      "username": "<string>",
      "password": "<string>",
      "api_key_header": "X-API-Key",
      "api_key_value": "<string>"
    },
    "signing_secret_ref": "<string>",
    "timeout_s": 60,
    "timeout_seconds": 60,
    "max_retries": 5,
    "max_body_bytes": 5000064,
    "redact_response_pii": true,
    "body_template": "<string>",
    "retry_policy": {},
    "simulate_latency_ms": 15000,
    "simulate_error_rate": 0.5,
    "expected_inputs": {},
    "canned_response": "<string>",
    "response_template": "<string>",
    "latency_ms": 15000,
    "handler_ref": "<string>",
    "raw_schema": {},
    "parameters_schema": {},
    "execution_endpoint": "<string>",
    "python_code": "<string>",
    "rpc_method": "<string>",
    "mcp_url": "<string>",
    "mcp_allowlist": [
      "<string>"
    ],
    "bearer_token": "<string>",
    "extra_headers": {},
    "is_end_call": true,
    "is_transfer": true,
    "webhook_url": "<string>",
    "auth_config": {}
  },
  "tool_type": "function",
  "description": "<string>"
}
'
{
  "id": "<string>",
  "agent_id": "<string>",
  "tool_key": "<string>",
  "instance_name": "<string>",
  "display_name": "<string>",
  "tool_type": "<string>",
  "enabled": true,
  "is_active": true,
  "version": 123,
  "config": {},
  "description": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "raw_schema": {},
  "rpc_method": "<string>",
  "parameters_schema": {},
  "registry_info": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.mrassistant.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
agent_id
string<uuid>
required

Body

application/json

Schema for creating a new agent_tool instance.

The user is configuring a specific instance — a tool type (tool_key) plus a meaningful instance_name plus per-instance config. A tool cannot be added "raw" (just a type with no instance_name and no config) — the controller enforces this:

  • tool_key MUST exist in the registry (tool_registry table)
  • instance_name is REQUIRED (no silent default to tool_key)
  • per-type required CFG fields are validated (e.g. http_webhook needs url_allowlist; send_text_tool needs provider+from_e164+secret refs)
​
tool_key
string
required

Tool type identifier from the registry. Must match an entry from GET /agents/{agent_id}/tools/registry/available.

​
instance_name
string
required

Stable identifier the LLM will use to call this tool. Must be meaningful (e.g. 'transfer_to_billing', 'end_call_polite'); the same tool_key can be instanced multiple times with different configs. Must be unique per agent. Pattern: ^[A-Za-z][A-Za-z0-9_-]{0,118}[A-Za-z0-9]?$

Required string length: 1 - 120
​
display_name
string | null

Human-friendly UI label.

​
enabled
boolean
default:true
​
config
ToolConfig · object

Aggregate config for a tool instance — full v2 Field Reference superset.

Frontend may submit any subset of these fields. Whatever is non-None is persisted into the agent_tool.config JSON blob. The runtime reads only the fields relevant to the resolved tool_type.

Section numbers below cite mr-assistant-tools-field-reference v2.

​
tool_type
string | null
default:function
​
description
string | null

Response

Successful Response

Schema for tool response.

​
id
string
required
​
agent_id
string
required
​
tool_key
string
required
​
instance_name
string
required
​
display_name
string | null
required
​
tool_type
string
required
​
enabled
boolean
required
​
is_active
boolean
required
​
version
integer
required
​
config
Config · object
required
​
description
string | null
required
​
created_at
string<date-time>
required
​
raw_schema
Raw Schema · object
​
rpc_method
string | null
​
parameters_schema
Parameters Schema · object
​
registry_info
Registry Info · object