Registering Custom Tools

Why register custom tools?

Ploton’s built-in tools cover popular services — CRMs, payment processors, storage, messaging. But you probably have internal APIs or domain-specific services that no built-in tool covers.

Registering a custom tool teaches your subagents how to talk to your service. It works the same way as built-in tools (tool knowledge plus execution memory), except you provide the initial knowledge: your API shape, auth method, and data model.

Once registered, your custom tool is available to any subagent whose domain matches. Subagents pick tools based on the task prompt, same as built-in tools. As tasks run through it, execution memory accumulates and it gets faster and more reliable.

Tool definition structure

A tool definition tells your subagents what the tool does, what parameters it takes, and how it authenticates.

{
	"name": "internal-crm",
	"description": "Queries and updates records in our internal CRM system. Supports contacts, companies, and deals.",
	"version": "1.0.0",
	"base_url": "https://crm.internal.yourcompany.com/api/v2",
	"auth": {
		"type": "api_key",
		"header": "X-API-Key",
		"env_var": "INTERNAL_CRM_API_KEY"
	},
	"capabilities": [
		{
			"name": "search_contacts",
			"description": "Search contacts by name, email, or company",
			"parameters": {
				"query": {
					"type": "string",
					"required": true,
					"description": "Search query"
				},
				"limit": {
					"type": "number",
					"default": 20,
					"description": "Max results"
				}
			}
		},
		{
			"name": "create_deal",
			"description": "Create a new deal record",
			"parameters": {
				"contact_id": { "type": "string", "required": true },
				"deal_name": { "type": "string", "required": true },
				"amount": { "type": "number", "required": true },
				"stage": { "type": "string", "default": "prospecting" }
			}
		},
		{
			"name": "update_contact",
			"description": "Update fields on an existing contact",
			"parameters": {
				"contact_id": { "type": "string", "required": true },
				"fields": {
					"type": "object",
					"required": true,
					"description": "Key-value pairs of fields to update"
				}
			}
		}
	]
}

Key fields

Authentication types

Custom tools support these auth methods:

API key

{
	"auth": {
		"type": "api_key",
		"header": "X-API-Key",
		"env_var": "INTERNAL_CRM_API_KEY"
	}
}

Bearer token

{
	"auth": {
		"type": "bearer",
		"env_var": "INTERNAL_SERVICE_TOKEN"
	}
}

OAuth 2.0

{
	"auth": {
		"type": "oauth2",
		"authorize_url": "https://auth.yourservice.com/authorize",
		"token_url": "https://auth.yourservice.com/token",
		"scopes": ["read", "write"],
		"client_id_env": "YOUR_SERVICE_CLIENT_ID",
		"client_secret_env": "YOUR_SERVICE_CLIENT_SECRET"
	}
}

OAuth tools plug into Ploton’s managed OAuth flow. When a task needs user authorization, Ploton handles the consent redirect and token management, same as built-in tools.

No authentication

{
	"auth": {
		"type": "none"
	}
}

For internal services behind network-level security (VPN, private subnet, etc.).

Registering a custom tool

POST your tool definition to the API:

curl -X POST https://api.ploton.ai/v1/tools \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d @tool-definition.json

{
	"id": "tool_custom_abc123",
	"name": "internal-crm",
	"status": "active",
	"created_at": "2025-06-15T10:00:00Z"
}

Done. Subagents whose domain overlaps with this tool will use it automatically when a task prompt matches its capabilities.

How custom tools get trained

flowchart LR
    A["Register tool"] --> B["First tasks run"]
    B --> C["Execution memory builds"]
    C --> D["Trained tool"]
    D -->|"More tasks"| C

    style A fill:#1a1630,stroke:#3B82F6,color:#e8e0f0
    style B fill:#1a1630,stroke:#FACC15,color:#e8e0f0
    style C fill:#1a1630,stroke:#FACC15,color:#e8e0f0
    style D fill:#1a1630,stroke:#50FA7B,color:#e8e0f0

Custom tools build execution memory the same way built-in tools do. After a few task runs, your custom tool starts learning things like:

• Which API endpoints return the best data for common prompts
• How your service handles load (rate limits, timeouts)
• Common failure patterns and how to recover from them
• What parameter values work best for your specific API

None of this requires configuration. It happens automatically as tasks run.

Testing custom tools

Use mode: "test" to verify a subagent selects your custom tool for a given prompt:

curl -X POST https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Search our internal CRM for contacts at Acme Corp",
    "sub_agent": "crm-agent",
    "mode": "test"
  }'

{
	"id": "task_test_xyz",
	"status": "complete",
	"sub_agent": "crm-agent",
	"mode": "test",
	"validation": {
		"tools_selected": ["internal-crm"],
		"planned_steps": ["authenticate", "search_contacts"],
		"matched_capability": "search_contacts"
	}
}

If the subagent picks the wrong tool, make your description and capability descriptions more specific. That fixes it most of the time.

Best practices

Capability descriptions matter. Subagents use them to match prompts to capabilities. “Search contacts” works, but “Search contacts by name, email, or company in the internal CRM” gives the subagent more to match against.

Start read-only. Register query and search capabilities first, confirm they work, then add write operations.

When your API changes, bump the tool version and update capabilities. Execution memory adapts to the new version automatically.

Pick meaningful names. internal-crm tells you something. my-tool-1 doesn’t. The name shows up in task traces and logs, so make it count.

Next steps

• Deploying — Production configuration for tools and webhooks
• Trained Tasks — How training works under the hood
• Prompt Engineering — Write prompts that activate your custom tools