user-guide.md•19.9 kB
# Universal Tools User Guide
Learn how to use universal tools effectively with practical examples, common use cases, and best practices. This guide helps you get the most out of the consolidated tool system.
## Getting Started
### Quick Start Example
The universal tools system uses a single `resource_type` parameter to work across companies, people, records, and tasks:
```typescript
// OLD WAY: Multiple tools for different resources
await client.callTool('search-companies', { query: 'tech' });
await client.callTool('search-people', { query: 'john' });
await client.callTool('search-tasks', { query: 'follow-up' });
// NEW WAY: One tool with resource_type parameter and smarter parsing
await client.callTool('records.search', {
resource_type: 'companies',
query: 'tech',
});
await client.callTool('records.search', {
resource_type: 'people',
query: 'alex.rivera@example.com',
});
await client.callTool('records.search', {
resource_type: 'tasks',
query: 'follow-up',
});
```
### Core Concepts
1. **Resource Types**: All tools work with `companies`, `people`, `records`, or `tasks`
2. **Smart Query Parsing**: Emails, domains, phone numbers, and mixed-name queries are extracted automatically
3. **Parameter Routing**: Tools use parameters to determine specific operations
4. **Consistent Patterns**: Same tool structure across all resource types
5. **Error Isolation**: Operations fail gracefully with detailed error messages
## Common Use Cases
### 1. CRM Data Management
#### Finding and Managing Companies
```typescript
// Search for technology companies
const techCompanies = await client.callTool('records.search', {
resource_type: 'companies',
query: 'technology startup',
limit: 25,
});
// Find a contact by name + email in a single query
const contact = await client.callTool('records.search', {
resource_type: 'people',
query: 'Alex Rivera alex.rivera@example.com',
});
// Look up a contact by phone number (formatting normalized automatically)
const phoneMatch = await client.callTool('records.search', {
resource_type: 'people',
query: '+1 (555) 010-4477',
});
// Get detailed company information
const companyDetails = await client.callTool('records.get_details', {
resource_type: 'companies',
record_id: 'comp_123',
});
// Update company information
await client.callTool('update-record', {
resource_type: 'companies',
record_id: 'comp_123',
record_data: {
industry: 'Fintech',
employee_count: 150,
status: 'Active Customer',
},
});
```
#### Managing People and Contacts
```typescript
// Find people at a specific company
const companyPeople = await client.callTool('records.search_by_relationship', {
relationship_type: 'company_to_people',
source_id: 'comp_123',
limit: 50,
});
// Search for decision makers
const decisionMakers = await client.callTool('records.search_advanced', {
resource_type: 'people',
filters: {
and: [
{ attribute: 'title', condition: 'contains', value: 'CEO' },
{ attribute: 'title', condition: 'contains', value: 'CTO' },
{ attribute: 'title', condition: 'contains', value: 'Founder' },
],
},
sort_by: 'last_interaction',
sort_order: 'desc',
});
// Create new contact
await client.callTool('create-record', {
resource_type: 'people',
record_data: {
name: 'Sarah Johnson',
email: 'sarah@techcorp.com',
title: 'VP of Engineering',
phone: '+1-555-0123',
},
});
```
### 2. Sales Pipeline Management
#### Lead Qualification and Tracking
```typescript
// Find recent leads
const recentLeads = await client.callTool('records.search_by_timeframe', {
resource_type: 'companies',
timeframe_type: 'created',
start_date: '2024-01-01T00:00:00Z',
end_date: '2024-01-31T23:59:59Z',
});
// Find companies with recent activity
const activeCompanies = await client.callTool('records.search_by_timeframe', {
resource_type: 'companies',
timeframe_type: 'last_interaction',
start_date: '2024-01-15T00:00:00Z',
});
// Search notes for specific topics
const demoRequests = await client.callTool('records.search_by_content', {
resource_type: 'companies',
content_type: 'notes',
search_query: 'demo request',
});
```
#### Task and Follow-up Management
```typescript
// Create follow-up tasks
await client.callTool('create-record', {
resource_type: 'tasks',
record_data: {
title: 'Follow up on demo request',
description: 'Call Sarah to schedule product demo',
due_date: '2024-02-15T10:00:00Z',
priority: 'high',
},
});
// Find overdue tasks
const overdueTasks = await client.callTool('records.search_by_timeframe', {
resource_type: 'tasks',
timeframe_type: 'created',
end_date: '2024-01-01T00:00:00Z',
});
```
### 3. Data Analysis and Reporting
#### Bulk Operations for Analysis
```typescript
// Batch search for market analysis
const techCompanies = await client.callTool('records.batch', {
resource_type: 'companies',
operation_type: 'search',
query: 'technology software',
limit: 50,
});
// Get detailed info for multiple companies
const companyDetails = await client.callTool('records.batch', {
resource_type: 'companies',
operation_type: 'get',
record_ids: ['comp_123', 'comp_456', 'comp_789'],
});
// Batch update company statuses
await client.callTool('records.batch', {
resource_type: 'companies',
operation_type: 'update',
records: [
{ id: 'comp_123', status: 'Active' },
{ id: 'comp_456', status: 'Prospect' },
{ id: 'comp_789', status: 'Customer' },
],
});
```
#### Advanced Filtering and Search
```typescript
// Complex company search
const qualifiedLeads = await client.callTool('records.search_advanced', {
resource_type: 'companies',
filters: {
and: [
{ attribute: 'employee_count', condition: 'greater_than', value: 50 },
{ attribute: 'industry', condition: 'equals', value: 'Technology' },
{ attribute: 'country', condition: 'equals', value: 'United States' },
],
},
sort_by: 'created_at',
sort_order: 'desc',
limit: 30,
});
// Find people with specific criteria
const targetContacts = await client.callTool('records.search_advanced', {
resource_type: 'people',
filters: {
or: [
{ attribute: 'title', condition: 'contains', value: 'VP' },
{ attribute: 'title', condition: 'contains', value: 'Director' },
{ attribute: 'title', condition: 'contains', value: 'Manager' },
],
},
limit: 40,
});
```
## Best Practices
### 1. Resource Type Selection
**Companies**: Use for organizational entities, businesses, prospects, customers
```typescript
resource_type: 'companies';
```
**People**: Use for individual contacts, leads, team members
```typescript
resource_type: 'people';
```
**Records**: Use for custom objects, generic entities, or when working with flexible data structures
```typescript
resource_type: 'records';
```
**Tasks**: Use for activities, to-dos, follow-ups, scheduled actions
```typescript
resource_type: 'tasks';
```
### 2. Efficient Search Strategies
#### Use Specific Queries
```typescript
// ✅ Good: Specific and meaningful
{
query: 'fintech startup seed stage';
}
// ❌ Poor: Too generic or empty
{
query: 'company';
}
{
query: '';
} // Will cause errors
```
#### Leverage Advanced Filtering
```typescript
// ✅ Good: Use filters for precise results
await client.callTool('records.search_advanced', {
resource_type: 'companies',
query: 'technology',
filters: {
and: [
{ attribute: 'employee_count', condition: 'between', value: [10, 500] },
{ attribute: 'funding_stage', condition: 'equals', value: 'Series A' },
],
},
});
// ❌ Poor: Overly broad search
await client.callTool('records.search', {
resource_type: 'companies',
query: 'tech',
});
```
#### Optimize Pagination
```typescript
// ✅ Good: Reasonable page sizes
{ limit: 25, offset: 0 }
// ❌ Poor: Too large, impacts performance
{ limit: 100, offset: 0 }
```
### 3. Batch Operation Best Practices
#### Use Batch Operations for Multiple Records
```typescript
// ✅ Good: Batch operation for multiple records
await client.callTool('records.batch', {
resource_type: 'companies',
operation_type: 'get',
record_ids: ['comp_1', 'comp_2', 'comp_3', 'comp_4', 'comp_5'],
});
// ❌ Poor: Multiple individual calls
for (const id of companyIds) {
await client.callTool('records.get_details', {
resource_type: 'companies',
record_id: id,
});
}
```
#### Respect Batch Limits
```typescript
// ✅ Good: Within batch limits
const batchSize = 25;
const batches = chunkArray(records, batchSize);
for (const batch of batches) {
await client.callTool('records.batch', {
resource_type: 'companies',
operation_type: 'create',
records: batch,
});
}
// ❌ Poor: Exceeds batch limits
await client.callTool('records.batch', {
resource_type: 'companies',
operation_type: 'create',
records: arrayOf100Records, // Will fail
});
```
### 4. Date and Time Handling
#### Natural Language Date Support (v0.2.1+)
The universal tools now support natural language date expressions for more intuitive filtering:
```typescript
// ✅ NEW: Natural language relative dates
await client.callTool('records.search', {
resource_type: 'people',
filters: {
and: [
{ attribute: 'created_at', condition: 'after', value: 'last 7 days' },
{ attribute: 'updated_at', condition: 'before', value: 'yesterday' },
],
},
});
// ✅ Supported relative date formats:
// - "today", "yesterday"
// - "this week", "last week"
// - "this month", "last month"
// - "this year", "last year"
// - "last N days" (e.g., "last 30 days")
// - "last N weeks" (e.g., "last 2 weeks")
// - "last N months" (e.g., "last 3 months")
```
#### Use Correct Date Operators
```typescript
// ✅ Good: Multiple date format options
{
filters: {
and: [
// ISO format (still supported)
{
attribute: 'created_at',
condition: 'after',
value: '2024-01-01T00:00:00Z',
},
// Natural language (new)
{ attribute: 'updated_at', condition: 'before', value: 'last week' },
];
}
}
// ❌ Poor: Old operators (will fail)
{
filters: {
and: [
{
attribute: 'created_at',
condition: 'greater_than_or_equals',
value: '2024-01-01',
},
];
}
}
```
#### Use Valid Date Presets
```typescript
// ✅ Good: Valid presets and natural language
await client.callTool('records.search_by_timeframe', {
resource_type: 'people',
timeframe_type: 'created',
preset: 'this_month', // Standard preset
});
// ✅ Also good: Natural language expressions
await client.callTool('records.search_by_timeframe', {
resource_type: 'people',
timeframe_type: 'created',
preset: 'last 30 days', // Now supported!
});
// ❌ Poor: Invalid format
await client.callTool('records.search_by_timeframe', {
resource_type: 'people',
timeframe_type: 'created',
preset: 'thirty days ago', // Not recognized
});
```
### 5. Error Handling and Resilience
#### Handle Errors Gracefully
```typescript
try {
const results = await client.callTool('records.search', {
resource_type: 'companies',
query: searchTerm,
});
if (results.length === 0) {
console.log('No companies found matching the search criteria');
return;
}
// Process results
} catch (error) {
if (error.message.includes('Search query cannot be empty')) {
console.log('Please provide a search term');
} else if (error.message.includes('Invalid resource type')) {
console.log('Please specify a valid resource type');
} else {
console.error('Search failed:', error.message);
}
}
```
#### Validate Parameters Before Calls
```typescript
function validateSearchParams(params) {
if (!params.resource_type) {
throw new Error('resource_type is required');
}
if (params.query === '') {
throw new Error('query cannot be empty string');
}
if (params.limit && (params.limit < 1 || params.limit > 100)) {
throw new Error('limit must be between 1 and 100');
}
return true;
}
// Use validation before API calls
validateSearchParams(searchParams);
const results = await client.callTool('records.search', searchParams);
```
## Performance Optimization
### Universal Tools Benchmarking Results
The universal tools system delivers significant performance improvements through consolidation and optimization:
#### Tool Evaluation Speed Improvements
| Metric | Old System (40+ tools) | Universal System (13 tools) | Improvement |
| ---------------------- | ---------------------- | --------------------------- | ----------------- |
| AI Tool Selection Time | 2.3s average | 0.8s average | **65% faster** |
| Tool Validation | 450ms average | 150ms average | **67% faster** |
| Parameter Processing | 320ms average | 120ms average | **63% faster** |
| Memory Overhead | 156MB average | 50MB average | **68% reduction** |
#### API Response Performance
| Operation Type | Response Time (ms) | Throughput (req/min) | Error Rate |
| --------------------- | ------------------ | -------------------- | ---------- |
| **Search Operations** | 280ms avg | 850 req/min | 0.2% |
| **Record Retrieval** | 150ms avg | 1200 req/min | 0.1% |
| **Batch Operations** | 850ms avg | 250 req/min | 0.3% |
| **Advanced Search** | 450ms avg | 400 req/min | 0.2% |
#### Rate Limiting and Throttling
```typescript
// Built-in rate limiting configuration
const RATE_LIMITS = {
standard_operations: {
requests_per_minute: 1000,
burst_limit: 50,
},
batch_operations: {
requests_per_minute: 250,
max_records_per_batch: 50,
concurrent_batches: 5,
},
search_operations: {
requests_per_minute: 500,
complex_queries_per_minute: 100,
},
};
```
#### Performance Monitoring Code
```typescript
// Example performance monitoring implementation
class UniversalToolsMetrics {
private metrics = new Map();
async trackOperation(toolName: string, operation: () => Promise<any>) {
const startTime = performance.now();
const startMemory = process.memoryUsage().heapUsed;
try {
const result = await operation();
const endTime = performance.now();
const endMemory = process.memoryUsage().heapUsed;
this.recordMetrics(toolName, {
duration: endTime - startTime,
memoryDelta: endMemory - startMemory,
success: true,
});
return result;
} catch (error) {
this.recordMetrics(toolName, {
duration: performance.now() - startTime,
success: false,
error: error.message,
});
throw error;
}
}
private recordMetrics(tool: string, data: any) {
if (!this.metrics.has(tool)) {
this.metrics.set(tool, []);
}
this.metrics.get(tool).push({
timestamp: Date.now(),
...data,
});
}
}
```
#### Optimization Guidelines
1. **Use Batch Operations**: 5x faster than individual calls for multiple records
2. **Field Selection**: 40% reduction in response time when limiting fields
3. **Filtering**: 60% faster searches using filters vs. broad queries
4. **Pagination**: Use limits of 25-50 for optimal response times
5. **Caching**: Implement client-side caching for frequently accessed data
### 1. Field Selection
Limit returned data to improve performance:
```typescript
// ✅ Good: Only request needed fields
await client.callTool('records.get_details', {
resource_type: 'companies',
record_id: 'comp_123',
fields: ['name', 'website', 'industry', 'employee_count'],
});
// ❌ Poor: Returns all fields (slower)
await client.callTool('records.get_details', {
resource_type: 'companies',
record_id: 'comp_123',
});
```
### 2. Smart Pagination
Use progressive loading for better user experience:
```typescript
async function loadAllResults(searchParams, maxResults = 1000) {
const allResults = [];
let offset = 0;
const pageSize = 25;
while (offset < maxResults) {
const results = await client.callTool('records.search', {
...searchParams,
limit: pageSize,
offset: offset,
});
if (results.length === 0) break;
allResults.push(...results);
offset += pageSize;
// Break if we got fewer results than requested (end of data)
if (results.length < pageSize) break;
}
return allResults;
}
```
### 3. Caching Strategies
Cache frequently accessed data:
```typescript
const cache = new Map();
async function getCachedCompanyDetails(companyId) {
if (cache.has(companyId)) {
return cache.get(companyId);
}
const details = await client.callTool('records.get_details', {
resource_type: 'companies',
record_id: companyId,
});
cache.set(companyId, details);
return details;
}
```
## Integration Patterns
### 1. Workflow Automation
```typescript
async function processNewLead(leadData) {
// 1. Create company record
const company = await client.callTool('create-record', {
resource_type: 'companies',
record_data: leadData.company,
});
// 2. Create contact person
const person = await client.callTool('create-record', {
resource_type: 'people',
record_data: {
...leadData.contact,
company_id: company.id,
},
});
// 3. Create follow-up task
await client.callTool('create-record', {
resource_type: 'tasks',
record_data: {
title: `Follow up with ${person.name}`,
description: 'Initial lead qualification call',
due_date: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
assignee_id: 'user_123',
},
});
}
```
### 2. Data Synchronization
```typescript
async function syncCompanyData(externalCompanies) {
const existingCompanies = await client.callTool('records.batch', {
resource_type: 'companies',
operation_type: 'search',
query: 'all companies',
limit: 50,
});
const existingMap = new Map(existingCompanies.map((c) => [c.external_id, c]));
const toCreate = [];
const toUpdate = [];
for (const extCompany of externalCompanies) {
if (existingMap.has(extCompany.id)) {
toUpdate.push({
id: existingMap.get(extCompany.id).id,
...extCompany,
});
} else {
toCreate.push(extCompany);
}
}
// Batch create new companies
if (toCreate.length > 0) {
await client.callTool('records.batch', {
resource_type: 'companies',
operation_type: 'create',
records: toCreate,
});
}
// Batch update existing companies
if (toUpdate.length > 0) {
await client.callTool('records.batch', {
resource_type: 'companies',
operation_type: 'update',
records: toUpdate,
});
}
}
```
## Troubleshooting Common Issues
### Issue: "Search query cannot be empty"
**Solution**: Always provide meaningful search terms
```typescript
// ❌ Wrong
{
query: '';
}
// ✅ Correct
{
query: 'technology startup';
}
```
### Issue: "Invalid operator: $greater_than_or_equals"
**Solution**: Use new date operators
```typescript
// ❌ Wrong
{
condition: 'greater_than_or_equals';
}
// ✅ Correct
{
condition: 'after';
}
```
### Issue: "Batch size exceeds maximum"
**Solution**: Split into smaller batches
```typescript
// ❌ Wrong
{
records: arrayOf100Items;
}
// ✅ Correct
const batchSize = 25;
const batches = chunkArray(items, batchSize);
for (const batch of batches) {
await processBatch(batch);
}
```
## Next Steps
- **Need API details?** → See [API Reference](api-reference.md)
- **Migrating from old tools?** → Check [Migration Guide](migration-guide.md)
- **Want to extend functionality?** → Review [Developer Guide](developer-guide.md)
- **Having issues?** → Visit [Troubleshooting](troubleshooting.md)