Custom Tools
Need to connect agents to an API, database, or service that MeetLoyd does not have a pre-built connector for? Custom tools let you extend your agents with any capability you can imagine.
What Are Custom Tools?
Custom tools are user-defined actions that agents can call during conversations. They follow the Model Context Protocol (MCP) standard -- the same open protocol used by all of MeetLoyd's built-in integrations. When an agent decides it needs to use a tool, MeetLoyd executes it securely on the server side and returns the result.
You define three things for each custom tool:
- What it does -- a name and description so the agent knows when to use it
- What it needs -- an input schema describing the parameters
- How it runs -- the execution method (HTTP call, JavaScript logic, webhook, or database query)
Tool Types
| Type | Best For | How It Works |
|---|---|---|
| HTTP | REST APIs | MeetLoyd makes a server-side HTTP call with your configuration |
| JavaScript | Custom logic, data transformation | Your code runs in a secure sandbox with a 30-second timeout |
| Webhook | External processing on your own server | MeetLoyd calls your endpoint; your server processes and responds |
| Database | SQL queries | Direct connection to your database with parameterized queries |
Why Custom Tools?
How Agents Use Custom Tools
Once you create a custom tool and assign it to an agent, the agent can call it naturally during any conversation. For example, if you create a weather_lookup tool, a user can ask "What is the weather in Paris?" and the agent will call your tool, get the result, and respond conversationally.
You do not need to teach the agent special syntax -- the tool's name and description are enough for the agent to know when and how to use it.
Creating an HTTP Tool
HTTP tools let you connect to any REST API. You configure the URL, method, headers, query parameters, and body -- MeetLoyd handles the rest.
Configuration Options
| Option | Description |
|---|---|
url | The endpoint URL. Supports variable substitution (e.g., https://api.example.com/users/${userId}) |
method | HTTP method: GET, POST, PUT, PATCH, DELETE |
headers | Request headers. Use ${secrets.API_KEY} to inject secrets securely |
queryParams | Query string parameters with variable substitution |
body | Request body for POST/PUT/PATCH |
bodyType | Body encoding: json, form, or raw |
timeout | Timeout in milliseconds (default: 30000) |
followRedirects | Whether to follow HTTP redirects |
responseType | Expected response: json, text, or binary |
responseMapping | JSONPath expressions to extract specific fields from the response |
Example: Weather API
In the dashboard, go to Tools > Create Tool and configure:
- Name:
weather_lookup - Description: "Get current weather for a location"
- Type: HTTP
- URL:
https://api.weather.com/v1/current?q=${city}&units=${units} - Method: GET
- Headers:
Authorization: Bearer ${secrets.WEATHER_API_KEY} - Secrets Required:
WEATHER_API_KEY
Define the input schema with a required city (string) and optional units (metric or imperial).
Creating a JavaScript Tool
For custom logic that does not fit a simple HTTP call -- data transformation, validation, calculations, or multi-step processing.
Sandbox Environment
Your code has access to:
| Available | Description |
|---|---|
input | The parameters passed by the agent |
secrets | Your stored secrets (read-only) |
context | Execution context: agentId, conversationId, userId |
utils | Built-in utilities: uuid(), sha256(), base64Encode(), base64Decode(), now() |
fetch | HTTP fetch (limited to external URLs) |
Sandbox Limitations
| Constraint | Limit |
|---|---|
| Filesystem access | None |
| Process/OS access | None |
| Network | fetch only |
| Timeout | 30 seconds |
| Memory | 128 MB |
eval / Function constructor | Blocked |
Example: Data Transformer
Create a JavaScript tool that agents can use to aggregate, filter, sort, or group arrays of data. Define operations like "sum", "average", "filter", "sort", and "group" -- the agent picks the right one based on the user's request.
Creating a Webhook Tool
Webhook tools delegate execution to your own server. MeetLoyd sends the tool input to your endpoint and waits for the response.
How It Works
- Agent calls the tool during a conversation
- MeetLoyd sends a POST request to your configured URL with the tool input
- The request includes a signature header (
X-MeetLoyd-Signature) for verification - Your server processes the request and returns a JSON response
- MeetLoyd passes the result back to the agent
Configuration Options
| Option | Description |
|---|---|
url | Your server endpoint |
method | HTTP method (usually POST) |
headers | Custom headers, including webhook secret |
signatureHeader | Header name for the HMAC signature |
signatureAlgorithm | Signature algorithm (sha256) |
timeout | Timeout in milliseconds (default: 60000) |
async | If true, your server calls back with the result instead of responding synchronously |
Always verify the X-MeetLoyd-Signature header on your server to ensure the request is genuinely from MeetLoyd. The signature is an HMAC-SHA256 of the request body using your webhook secret.
Managing Secrets
Secrets are the credentials your tools need to authenticate with external services.
| Feature | Description |
|---|---|
| Encrypted at rest | AES-256 encryption |
| Never logged | Secrets never appear in logs or API responses |
| Runtime injection | Injected only when the tool executes |
| Per-tool isolation | Each tool has its own secret scope |
To add secrets, go to the tool's settings page in the dashboard and add key-value pairs under Secrets. Reference them in your tool config with ${secrets.SECRET_NAME}.
Tool Permissions
You can control who can use a tool and whether it requires approval:
| Setting | Description |
|---|---|
| Allowed Agents | Restrict the tool to specific agents |
| Allowed Roles | Restrict to users with specific roles |
| Require Approval | A human must approve each execution before it runs |
When requireApproval is enabled, the agent's tool call creates an approval request. An admin reviews and approves (or rejects) it, and only then does the tool execute.
Testing Tools
Before assigning a tool to an agent, test it from the dashboard:
- Go to Tools and select your tool
- Click Test
- Enter sample input parameters
- Review the output, duration, and any errors
You can also run a dry run that validates the input and shows the resolved URL and body without actually executing the tool.
Best Practices
Write clear descriptions. The agent uses the tool's name and description to decide when to call it. "Look up customer by email and return profile with order history" is much better than "Get customer."
Validate inputs with JSON Schema. Use format, minimum, maximum, enum, and required in your input schema. This prevents the agent from sending invalid data.
Handle errors gracefully. In JavaScript tools, return structured error objects with a retryable flag so the agent knows whether to try again.
Use response mapping for HTTP tools. Extract only the fields the agent needs instead of returning the entire API response. This keeps the agent's context clean and reduces token usage.
Start with least privilege. Use requireApproval: true for tools that modify data or cost money. You can relax this once you trust the agent's judgment.
Next: Explore Security Features for authentication and access control.