Use this file to discover all available pages before exploring further.
Custom tools allow agents to interact with your APIs, databases, and services seamlessly through the Model Context Protocol (MCP), enabling domain-specific capabilities beyond built-in tools.
The Custom Tools primitive extends agent capabilities by connecting external services, APIs, and databases through the Model Context Protocol (MCP). While agents come with powerful built-in tools for file operations, web browsing, and code execution, custom tools enable domain-specific functionality unique to your business needs.Custom tools are essential for:
API Integration: Connect agents to your internal and external APIs
Database Access: Query and manipulate data in your databases
Business Logic: Expose company-specific operations and workflows
Third-Party Services: Integrate with CRM, payment processors, analytics platforms
Legacy Systems: Bridge modern AI agents with existing infrastructure
MCP Protocol
Built on the open Model Context Protocol standard for maximum compatibility and flexibility
Automatic Discovery
Agents automatically discover and use available tools based on task requirements
import { Agentbase } from '@agentbase/sdk';const agentbase = new Agentbase({ apiKey: process.env.AGENTBASE_API_KEY});// Connect to custom MCP serverconst result = await agentbase.runAgent({ message: "Get customer data for user ID 12345", mcpServers: [ { serverName: "customer-api", serverUrl: "https://api.yourcompany.com/mcp" } ]});// Agent automatically discovers and uses available tools
// Predefined database queries as toolsconst result = await agentbase.runAgent({ message: "Show me all active users from California", datastores: [ { id: "ds_1234567890abcdef", name: "production-db" } ], queries: [ { name: "getUsersByState", description: "Fetch users filtered by state", query: "SELECT * FROM users WHERE state = ? AND status = 'active'" }, { name: "getUserById", description: "Fetch user details by their ID", query: "SELECT * FROM users WHERE id = ?" }, { name: "getOrderHistory", description: "Get order history for a specific user", query: "SELECT * FROM orders WHERE user_id = ? ORDER BY created_at DESC" } ]});
Query financial databases and perform calculations:
const financial = await agentbase.runAgent({ message: "Calculate Q4 revenue by region and compare to last year", datastores: [ { id: "ds_financial_db", name: "financial-data" } ], queries: [ { name: "getRevenueByRegion", description: "Get total revenue for a specific region and time period", query: `SELECT region, SUM(amount) as total_revenue FROM transactions WHERE date BETWEEN ? AND ? AND region = ? GROUP BY region` }, { name: "getYearOverYearGrowth", description: "Calculate year-over-year revenue growth", query: `SELECT current.region, current.revenue as current_revenue, previous.revenue as previous_revenue, ((current.revenue - previous.revenue) / previous.revenue * 100) as growth_pct FROM revenue_summary current JOIN revenue_summary previous ON current.region = previous.region WHERE current.year = ? AND previous.year = ?` } ]});
// Good: Focused, single-purpose tools{ "name": "get_customer", "description": "Retrieve customer details by ID"}{ "name": "update_customer_email", "description": "Update a customer's email address"}// Avoid: Kitchen-sink tools doing too much{ "name": "manage_customer", "description": "Get, create, update, or delete customers"}
Descriptive Naming
// Good: Clear, descriptive names"get_order_by_id""calculate_shipping_cost""send_password_reset_email"// Avoid: Vague or unclear names"fetch_data""do_calculation""send_email"
Idempotent Operations
// Design tools to be safely repeatable{ name: "create_or_update_user", description: "Create user if not exists, update if exists (idempotent)", // Uses upsert pattern}// Or provide clear state-checking tools{ name: "user_exists", description: "Check if user exists"}{ name: "create_user", description: "Create new user (fails if exists)"}
Error Handling
// Return structured errors{ "error": { "code": "CUSTOMER_NOT_FOUND", "message": "No customer found with ID: 12345", "details": { "customer_id": "12345", "suggestion": "Verify the customer ID and try again" } }}// Not just generic errors{ "error": "An error occurred"}
const result = await agentbase.runAgent({ message: "Help customer with order status", system: `You are a customer support agent.When helping with orders:1. Use get_order_status tool to check current status2. Use get_tracking_info if order is shipped3. Use estimate_delivery for pending orders4. Always provide tracking numbers when available`, mcpServers: [ { serverName: "order-tools", serverUrl: "https://api.yourcompany.com/mcp" } ]});
const result = await agentbase.runAgent({ message: "I need help", system: "You are a routing agent. Transfer to appropriate specialist.", agents: [ { name: "Order Support", description: "Handles order-related questions", // Order support agent gets order tools }, { name: "Technical Support", description: "Handles technical issues", // Technical support gets different tools } ]});
Problem: Agent doesn’t call your custom toolsSolutions:
Improve tool descriptions to be more specific
Add guidance in system prompt about when to use tools
Verify MCP server is accessible and returning tool list
Check authentication is configured correctly
Ensure tool parameters match task requirements
// Add explicit guidancesystem: `You are a customer service agent.Available tools:- get_customer(id): Always use this to fetch customer details- get_order(id): Use this to check order status- create_ticket(details): Use this to escalate issuesAlways retrieve customer information before helping them.`
Remember: Custom tools are most powerful when they expose domain-specific operations that agents can’t accomplish with built-in tools alone. Focus on business logic unique to your application.