Custom Tool Creation: Extend Agent Capabilities
Build and register custom tools that give your OpenClaw agent new abilities, from calling external APIs to running complex data transformations.
What You Will Get
By the end of this guide, your OpenClaw agent will have custom tools that extend its capabilities beyond the built-in feature set. You will create tools that call external APIs, process data, and perform specialized actions that the base agent cannot do on its own.
Custom tools are the most powerful way to extend your agent. While built-in tools cover common needs like web search and file handling, your specific use case likely requires integrations unique to your workflow. A custom tool bridges that gap by giving the agent a defined interface to perform any action you code.
You will define tool schemas, implement tool handlers, register tools with your agent, and test them end-to-end. The result is an agent with superpowers tailored to your exact needs.
Step-by-Step Setup
Follow these steps to create and deploy a custom tool.
Define the Tool Schema
Start by writing a schema that describes the tool's name, purpose, and parameters. The name should be a short verb phrase like 'lookup_order' or 'generate_invoice'. List each parameter with its type, description, and whether it is required. This schema tells the agent when and how to use the tool.
Implement the Tool Handler
Write the code that executes when the agent calls the tool. The handler receives the parameters defined in the schema and returns a result. Keep handlers focused on a single action. For example, a 'lookup_order' handler queries your order database and returns the order details.
Add Error Handling
Wrap your handler logic in error handling that returns useful error messages. If the tool cannot find a record, return a clear message like 'Order not found for ID 12345.' The agent uses these error messages to inform the user, so vague errors lead to confusing responses.
Register the Tool with Your Agent
Open the Tools tab in your agent's settings on RunTheAgent. Click Add Custom Tool and paste your schema and handler code. The system validates the schema and tests the handler with a sample input. Fix any validation errors before proceeding.
Write Tool Usage Instructions
Add instructions to your agent's system prompt that describe when to use the new tool. For example, 'When the user asks about their order status, use the lookup_order tool with the order ID.' Without clear instructions, the agent may not know when to invoke the tool.
Test with Real Scenarios
Chat with your agent and trigger scenarios that should invoke the tool. Verify that the agent calls the tool with the correct parameters, handles the response properly, and presents the result to the user in a natural way. Test error scenarios too, like invalid parameters or missing data.
Monitor Tool Usage
Check the tools analytics panel to see how often each custom tool is called, its average execution time, and error rate. High error rates suggest issues with the handler or the agent's tool usage instructions. Low usage might mean the agent does not recognize when to use the tool.
Tips and Best Practices
Keep Tools Small and Focused
Each tool should do one thing well. A tool that fetches data should not also transform it and send notifications. Split complex operations into separate tools that the agent can chain together as needed.
Write Descriptive Parameter Names
Parameter names and descriptions directly affect how well the agent uses the tool. 'order_id: The unique identifier of the customer order' is much better than 'id: An identifier'. The agent relies on these descriptions to pass correct values.
Version Your Tools
When updating a tool's schema or handler, create a new version rather than overwriting the existing one. This lets you roll back if the update causes issues and ensures existing conversations are not disrupted mid-flow.
Set Execution Timeouts
Configure a timeout for each tool handler to prevent long-running calls from blocking the agent. A typical timeout is 10 seconds for API calls. If the tool needs more time, consider making it a background task instead.
Frequently Asked Questions
Related Pages
Ready to get started?
Deploy your own OpenClaw instance in under 60 seconds. No VPS, no Docker, no SSH. Just your personal AI assistant, ready to work.
Starting at $24.50/mo. Everything included. 3-day money-back guarantee.
