Tools

Tool Registration

Registering a Tool

Register a new tool by sending a POST request to /mcp/tools. Each tool must belong to a toolkit and specify the backing function to invoke.

Required Fields

The following fields are required when registering a tool:

Field	Type	Description
toolkit_id	string	ID of the parent toolkit this tool belongs to
name	string	Unique identifier for the tool (e.g., "send-notification")
function_name	string	Name of the serverless function or HTTP endpoint that backs this tool

Optional Fields

Additional fields you can provide to configure behavior and access control:

Field	Type	Description
description	string	Human-readable description sent to the AI agent for context
display_name	string	Friendly name shown in the Agent Dojo UI
input_schema	object	JSON Schema defining the tool's expected input parameters
requires_credentials	boolean	Whether the tool needs credentials injected at call time
credential_provider_name	string	Name of the credential provider to resolve credentials from
allowed_roles	array	List of roles permitted to call this tool (e.g., ["admin", "editor"])
tags	array	Tags for categorization and filtering
timeout_seconds	number	Maximum execution time in seconds (default: 30)

Input Schema

The input_schema field uses JSON Schema format to define the arguments your tool accepts. This schema is sent to AI agents so they know what parameters to provide when calling the tool. Define the properties for each argument, their types, descriptions, and which fields are required.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "The notification message body"
    },
    "title": {
      "type": "string",
      "description": "Optional title for the notification"
    },
    "priority": {
      "type": "integer",
      "description": "Priority level: -2 (lowest) to 2 (emergency)",
      "minimum": -2,
      "maximum": 2,
      "default": 0
    },
    "url": {
      "type": "string",
      "description": "Optional URL to attach to the notification",
      "format": "uri"
    }
  },
  "required": ["message"]
}

Supported JSON Schema types include string,number,integer,boolean,array, and object. You can use additional schema keywords like enum,minimum,maximum,default, and format to further constrain inputs.

Full Registration Example

Here is a complete example of registering a custom tool with a full input schema:

Request:

curl -X POST https://api.agentdojo.dev/mcp/tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolkit_id": "tk_custom_001",
    "name": "create-support-ticket",
    "display_name": "Create Support Ticket",
    "description": "Create a new customer support ticket with priority and category",
    "function_name": "create-support-ticket",
    "input_schema": {
      "type": "object",
      "properties": {
        "subject": {
          "type": "string",
          "description": "Brief subject line for the ticket"
        },
        "body": {
          "type": "string",
          "description": "Detailed description of the issue"
        },
        "priority": {
          "type": "string",
          "description": "Ticket priority level",
          "enum": ["low", "medium", "high", "urgent"]
        },
        "category": {
          "type": "string",
          "description": "Support category",
          "enum": ["billing", "technical", "account", "general"]
        },
        "customer_email": {
          "type": "string",
          "description": "Email address of the customer",
          "format": "email"
        }
      },
      "required": ["subject", "body", "priority", "customer_email"]
    },
    "tags": ["support", "ticketing"],
    "timeout_seconds": 15
  }'

Response:

{
  "id": "tool_supp_001",
  "toolkit_id": "tk_custom_001",
  "name": "create-support-ticket",
  "display_name": "Create Support Ticket",
  "description": "Create a new customer support ticket with priority and category",
  "function_name": "create-support-ticket",
  "input_schema": {
    "type": "object",
    "properties": {
      "subject": { "type": "string", "description": "Brief subject line for the ticket" },
      "body": { "type": "string", "description": "Detailed description of the issue" },
      "priority": { "type": "string", "enum": ["low", "medium", "high", "urgent"] },
      "category": { "type": "string", "enum": ["billing", "technical", "account", "general"] },
      "customer_email": { "type": "string", "format": "email" }
    },
    "required": ["subject", "body", "priority", "customer_email"]
  },
  "requires_credentials": false,
  "dangerous": false,
  "timeout_seconds": 15,
  "is_active": true,
  "usage_count": 0,
  "tags": ["support", "ticketing"],
  "created_at": "2026-01-20T14:00:00.000Z"
}

Credential-Aware Tools

Some tools need API keys, tokens, or other credentials to interact with external services. Instead of hardcoding secrets, you can make a tool credential-aware by setting requires_credentials totrue and specifying a credential_provider_name.

When the tool is called, Agent Dojo automatically resolves the credentials from the linked provider and injects them into the function invocation. The AI agent never sees the raw credentials.

curl -X POST https://api.agentdojo.dev/mcp/tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolkit_id": "tk_notifications_001",
    "name": "send-sms",
    "description": "Send an SMS message via Twilio",
    "function_name": "twilio-send-sms",
    "requires_credentials": true,
    "credential_provider_name": "twilio",
    "input_schema": {
      "type": "object",
      "properties": {
        "to": {
          "type": "string",
          "description": "Recipient phone number in E.164 format"
        },
        "body": {
          "type": "string",
          "description": "The SMS message text"
        }
      },
      "required": ["to", "body"]
    }
  }'

Tip: The credential provider must be configured separately in the Credentials section before it can be referenced by a tool. See the Credentials documentation for setup instructions.