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.
Overview
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
Type-Safe
Strongly-typed tool definitions ensure reliable agent-tool interactions
Dynamic Configuration
Configure tools per-request for multi-tenant applications with different capabilities
How Custom Tools Work
When you provide MCP server configurations to an agent:- Registration: Agent connects to specified MCP servers and discovers available tools
- Tool Discovery: Each MCP server exposes its tool catalog with descriptions and parameters
- Automatic Selection: Agent evaluates available tools and selects appropriate ones for the task
- Execution: Agent calls tools with proper parameters and receives structured responses
- Integration: Tool results are incorporated into the agent’s reasoning and response
- Error Handling: Failed tool calls are handled gracefully with retry logic
Protocol Standard: Agentbase implements the full Model Context Protocol specification. Learn more at modelcontextprotocol.io
MCP Server Architecture
Basic MCP Server Structure
An MCP server exposes tools through HTTP endpoints:MCP Server Requirements
Your MCP server must provide:- Tool Listing Endpoint: Return available tools with descriptions and schemas
- Tool Execution Endpoint: Execute specific tools with provided parameters
- Authentication Handling: Support bearer tokens or OAuth for security
- Error Responses: Return structured error messages for failed operations
- Type Definitions: JSON Schema for parameters and return values
Code Examples
Basic Custom Tool Integration
Authentication with MCP Servers
Multiple MCP Servers
Database Query Tools
Building an MCP Server
MCP Server Implementation
Here’s a complete example of an MCP server implementation:Tool Schema Best Practices
Clear Tool Descriptions
Clear Tool Descriptions
Explicit Parameter Types
Explicit Parameter Types
Return Value Documentation
Return Value Documentation
Use Cases
1. CRM Integration
Connect agents to customer relationship management systems:2. E-Commerce Operations
Automate order processing and inventory management:3. Financial Analysis
Query financial databases and perform calculations:4. DevOps Automation
Integrate with infrastructure and deployment tools:5. Support Ticket Management
Automate customer support workflows:6. Content Management
Integrate with CMS and publishing platforms:Best Practices
Tool Design
Single Responsibility
Single Responsibility
Descriptive Naming
Descriptive Naming
Idempotent Operations
Idempotent Operations
Error Handling
Error Handling
Security
Input Validation
Input Validation
Rate Limiting
Rate Limiting
Audit Logging
Audit Logging
Performance
Caching
Cache frequently accessed data to reduce load on backend systems
Pagination
Return paginated results for large datasets instead of everything at once
Async Operations
Use async patterns for long-running operations with status checking
Connection Pooling
Reuse database connections instead of creating new ones per request
Integration with Other Primitives
With Prompts
Guide agents on when and how to use custom tools:With Rules
Enforce constraints on tool usage:With Multi-Agent Systems
Different agents with different tool access:With Datastores
Combine database access with custom business logic:Performance Considerations
Tool Discovery Overhead
- First Request: Agent discovers all available tools (~100-500ms)
- Subsequent Requests: Tool catalog cached within session
- Optimization: Minimize number of MCP servers when possible
Tool Execution Time
Monitor and optimize tool response times:Network Latency
Troubleshooting
Agent Not Using Custom Tools
Agent Not Using Custom 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
Tool Authentication Failures
Tool Authentication Failures
Problem: Tools returning 401/403 errorsSolutions:
- Verify auth token is valid and not expired
- Check token has required permissions
- Ensure auth type matches server expectations
- Test authentication with direct API call
Slow Tool Execution
Slow Tool Execution
Problem: Tools taking too long to executeSolutions:
- Add caching for frequently accessed data
- Optimize database queries
- Implement pagination for large datasets
- Use connection pooling
- Consider async operations for long tasks
Tool Errors Not Handled Gracefully
Tool Errors Not Handled Gracefully
Problem: Agent gets confused by tool errorsSolutions:
- Return structured error messages
- Include helpful error codes
- Provide suggested fixes in error response
- Document error scenarios in tool description
Related Primitives
Prompts
Guide agents on when and how to use tools
Rules
Enforce constraints on tool usage
Multi-Agent
Give different agents different tool access
Datastores
Database integration for custom queries