Registering Custom Tools

Why register custom tools?

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

Registering a custom tool teaches Ploton 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 task. Ploton picks it based on the prompt, same as a built-in tool. As tasks run through it, execution memory accumulates and it gets faster and more reliable.

Tool definition structure

A tool definition tells Ploton 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. Tasks whose prompts match the tool’s description and capabilities will route to it automatically.

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 Ploton 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",
    "mode": "test"
  }'

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

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

Best practices

Capability descriptions matter. Ploton uses them to match prompts to capabilities. “Search contacts” works, but “Search contacts by name, email, or company in the internal CRM” gives Ploton 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