Universal Tools Migration Guide

October 1, 2025 · View on GitHub

This guide helps you migrate from deprecated resource-specific tools to the new universal tool system. The universal tools consolidate 40+ individual tools into 13 powerful operations while maintaining full functionality.

Migration Overview

What Changed?

  • Tool Count: Reduced from 40+ tools to 13 universal operations (68% reduction)
  • Parameter Structure: Added resource_type parameter to specify target resource
  • Naming: Simplified tool names (e.g., search-companies → records.search)
  • Date Operators: Updated for Attio API compatibility

Benefits

  • Consistent API: Same patterns across all resource types
  • Better Performance: Fewer tools for AI systems to evaluate
  • Future-Proof: Easy to add new resource types without new tools

Complete Tool Migration Reference

Company Tools → Universal Equivalents

Deprecated ToolUniversal ToolResource TypeAdditional Parameters
search-companiesrecords.searchcompanies-
get-company-detailsrecords.get_detailscompanies-
create-companycreate-recordcompanies-
update-companyupdate-recordcompanies-
delete-companydelete-recordcompanies-
get-company-attributesrecords.get_attributescompanies-
discover-company-attributesrecords.discover_attributescompanies-
get-company-basic-inforecords.get_infocompaniesinfo_type: 'basic'
get-company-contact-inforecords.get_infocompaniesinfo_type: 'contact'
get-company-business-inforecords.get_infocompaniesinfo_type: 'business'
get-company-social-inforecords.get_infocompaniesinfo_type: 'social'
records.search_advanced-companiesrecords.search_advancedcompanies-
search-companies-by-notesrecords.search_by_contentcompaniescontent_type: 'notes'
search-companies-by-peoplerecords.search_by_relationshipcompaniesrelationship_type: 'people_to_company'

People Tools → Universal Equivalents

Deprecated ToolUniversal ToolResource TypeAdditional Parameters
search-peoplerecords.searchpeople-
get-person-detailsrecords.get_detailspeople-
create-personcreate-recordpeople-
records.search_advanced-peoplerecords.search_advancedpeople-
search-people-by-companyrecords.search_by_relationshippeoplerelationship_type: 'company_to_people'
search-people-by-activityrecords.search_by_contentpeoplecontent_type: 'activity'
search-people-by-notesrecords.search_by_contentpeoplecontent_type: 'notes'
search-people-by-creation-daterecords.search_by_timeframepeopletimeframe_type: 'created'
search-people-by-modification-daterecords.search_by_timeframepeopletimeframe_type: 'modified'
search-people-by-last-interactionrecords.search_by_timeframepeopletimeframe_type: 'last_interaction'

Record Tools → Universal Equivalents

Deprecated ToolUniversal ToolResource TypeAdditional Parameters
create-recordcreate-recordrecordsAlready universal
get-recordrecords.get_detailsrecords-
update-recordupdate-recordrecordsAlready universal
delete-recorddelete-recordrecordsAlready universal
list-recordsrecords.searchrecords-
batch-create-recordsrecords.batchrecordsoperation_type: 'create'
batch-update-recordsrecords.batchrecordsoperation_type: 'update'

Task Tools → Universal Equivalents

Deprecated ToolUniversal ToolResource TypeAdditional Parameters
create-taskcreate-recordtasks-
update-taskupdate-recordtasks-
delete-taskdelete-recordtasks-
list-tasksrecords.searchtasks-

Batch Tools → Universal Equivalents

Deprecated ToolUniversal ToolResource TypeAdditional Parameters
batch-create-companiesrecords.batchcompaniesoperation_type: 'create'
batch-update-companiesrecords.batchcompaniesoperation_type: 'update'
batch-delete-companiesrecords.batchcompaniesoperation_type: 'delete'
records.search_batch-companiesrecords.batchcompaniesoperation_type: 'search'
batch-get-company-detailsrecords.batchcompaniesoperation_type: 'get'

Visual Migration Comparison

🎯 Quick Before/After Reference

❌ Before (Deprecated) ✅ After (Universal) Key Changes 
// 40+ individual tools
search - companies;
search - people;
get - company - details;
get - person - details;
create - company;
create - person;
// ... 34+ more tools

// 13 universal tools
records.search;
records.get_details;
create - record;
update - record;
delete -record;
records.search_advanced;
// ... 7 more tools
  • 68% tool reduction
  • Consistent naming
  • Parameter-based routing
  • Same functionality
 
// Resource-specific parameters
await callTool('search-companies', {
  query: 'tech',
  limit: 10,
});

await callTool('search-people', {
  query: 'john',
  limit: 10,
});

// Universal with resource_type
await callTool('records.search', {
  resource_type: 'companies',
  query: 'tech',
  limit: 10,
});

await callTool('records.search', {
  resource_type: 'people',
  query: 'john',
  limit: 10,
});
  • Add resource_type
  • Single tool for all resources
  • Consistent API patterns
  • Same search functionality
 
// Different tools for similar operations
await callTool('get-company-basic-info', {
  record_id: 'comp_123',
});

await callTool('get-company-contact-info', {
  record_id: 'comp_123',
});

await callTool('get-company-social-info', {
  record_id: 'comp_123',
});

// Single tool with info_type parameter
await callTool('records.get_info', {
  resource_type: 'companies',
  record_id: 'comp_123',
  info_type: 'basic',
});

await callTool('records.get_info', {
  resource_type: 'companies',
  record_id: 'comp_123',
  info_type: 'contact',
});

await callTool('records.get_info', {
  resource_type: 'companies',
  record_id: 'comp_123',
  info_type: 'social',
});
  • Single tool replaces 3+
  • Consistent parameters
  • Add info_type parameter
  • Same data returned
 
// Old date operators (fail with API)
await callTool('records.search_advanced-companies', {
  filters: {
    and: [
      {
        attribute: 'created_at',
        condition: 'greater_than_or_equals',
        value: '2024-01-01',
      },
    ],
  },
});

// New date operators (API compatible)
await callTool('records.search_advanced', {
  resource_type: 'companies',
  filters: {
    and: [
      {
        attribute: 'created_at',
        condition: FilterConditionType.AFTER,
        value: '2024-01-01T00:00:00Z',
      },
    ],
  },
});
  • Updated date operators
  • ISO 8601 timestamps
  • FilterConditionType enum
  • API compatibility
 
// Batch operations per resource
await callTool('batch-create-companies', {
  companies: [{ name: 'Company 1' }, { name: 'Company 2' }],
});

await callTool('batch-create-people', {
  people: [{ name: 'Person 1' }, { name: 'Person 2' }],
});

// Universal batch operations
await callTool('records.batch', {
  resource_type: 'companies',
  operation_type: 'create',
  records: [{ name: 'Company 1' }, { name: 'Company 2' }],
});

await callTool('records.batch', {
  resource_type: 'people',
  operation_type: 'create',
  records: [{ name: 'Person 1' }, { name: 'Person 2' }],
});
  • Single batch tool
  • Add operation_type
  • Consistent records parameter
  • Same batch processing

Step-by-Step Migration Examples

❌ Before (Deprecated) ✅ After (Universal) 
await client.callTool('search-companies', {
  query: 'tech startup',
  limit: 10,
});

await client.callTool('records.search', {
  resource_type: 'companies',
  query: 'tech startup',
  limit: 10,
});

Migration Steps:

  1. Change tool name: search-companies → records.search
  2. Add parameter: resource_type: 'companies'
  3. Keep all other parameters the same

Example 2: Advanced People Search with Filters

❌ Before (Deprecated) ✅ After (Universal) 
await client.callTool('records.search_advanced-people', {
  filters: {
    and: [
      {
        attribute: 'job_title',
        condition: 'contains',
        value: 'Manager',
      },
      {
        attribute: 'created_at',
        condition: 'greater_than_or_equals',
        value: '2024-01-01',
      },
    ],
  },
  limit: 25,
});

await client.callTool('records.search_advanced', {
  resource_type: 'people',
  filters: {
    and: [
      {
        attribute: 'job_title',
        condition: FilterConditionType.CONTAINS,
        value: 'Manager',
      },
      {
        attribute: 'created_at',
        condition: FilterConditionType.AFTER,
        value: '2024-01-01T00:00:00Z',
      },
    ],
  },
  limit: 25,
});

Migration Steps:

  1. Change tool name: records.search_advanced-people → records.search_advanced
  2. Add parameter: resource_type: 'people'
  3. Update date operator: greater_than_or_equals → FilterConditionType.AFTER
  4. Use ISO 8601 timestamp: 2024-01-01 → 2024-01-01T00:00:00Z
  5. Use enum for conditions: 'contains' → FilterConditionType.CONTAINS

Example 3: Company Information Retrieval

❌ Before (Deprecated) ✅ After (Universal) 
// Multiple tool calls for different info types
const basic = await client.callTool('get-company-basic-info', {
  record_id: 'comp_123',
});

const contact = await client.callTool('get-company-contact-info', {
  record_id: 'comp_123',
});

const business = await client.callTool('get-company-business-info', {
  record_id: 'comp_123',
});

// Single tool with info_type parameter
const basic = await client.callTool('records.get_info', {
  resource_type: 'companies',
  record_id: 'comp_123',
  info_type: 'basic',
});

const contact = await client.callTool('records.get_info', {
  resource_type: 'companies',
  record_id: 'comp_123',
  info_type: 'contact',
});

const business = await client.callTool('records.get_info', {
  resource_type: 'companies',
  record_id: 'comp_123',
  info_type: 'business',
});

Migration Steps:

  1. Replace all info tools: get-company-*-info → records.get_info
  2. Add parameter: resource_type: 'companies'
  3. Add parameter: info_type with appropriate value ('basic', 'contact', 'business', 'social')
  4. Keep record_id parameter the same

Example 4: Batch Company Operations

❌ Before (Deprecated) ✅ After (Universal) 
// Create multiple companies
await client.callTool('batch-create-companies', {
  companies: [
    {
      name: 'TechCorp Inc.',
      website: 'techcorp.com',
      industry: 'Technology',
    },
    {
      name: 'DataSoft LLC',
      website: 'datasoft.io',
      industry: 'Software',
    },
  ],
});

// Get multiple company details
await client.callTool('batch-get-company-details', {
  company_ids: ['comp_123', 'comp_456'],
});

// Create multiple companies
await client.callTool('records.batch', {
  resource_type: 'companies',
  operation_type: 'create',
  records: [
    {
      name: 'TechCorp Inc.',
      website: 'techcorp.com',
      industry: 'Technology',
    },
    {
      name: 'DataSoft LLC',
      website: 'datasoft.io',
      industry: 'Software',
    },
  ],
});

// Get multiple company details
await client.callTool('records.batch', {
  resource_type: 'companies',
  operation_type: 'get',
  record_ids: ['comp_123', 'comp_456'],
});

Migration Steps:

  1. Replace all batch tools: batch-*-companies → records.batch
  2. Add parameter: resource_type: 'companies'
  3. Add parameter: operation_type ('create', 'update', 'delete', 'get', 'search')
  4. Rename data parameter: companies → records
  5. Rename ID parameter: company_ids → record_ids

Example 5: Date-Based Searches

❌ Before (Deprecated) ✅ After (Universal) 
// Search people by creation date
await client.callTool('search-people-by-creation-date', {
  dateRange: {
    start: '2024-01-01',
    end: '2024-01-31',
  },
});

// Search companies by modification date
await client.callTool('search-companies-by-modification-date', {
  preset: 'last_30_days', // Invalid preset!
});

// Search people by creation date
await client.callTool('records.search_by_timeframe', {
  resource_type: 'people',
  timeframe_type: 'created',
  date_range: {
    start_date: '2024-01-01T00:00:00Z',
    end_date: '2024-01-31T23:59:59Z',
  },
});

// Search companies by modification date
await client.callTool('records.search_by_timeframe', {
  resource_type: 'companies',
  timeframe_type: 'modified',
  preset: 'last_month', // Valid preset!
});

Migration Steps:

  1. Replace date-specific tools: search-*-by-*-date → records.search_by_timeframe
  2. Add parameter: resource_type (appropriate resource type)
  3. Add parameter: timeframe_type ('created', 'modified', 'last_contacted')
  4. Update date format: '2024-01-01' → '2024-01-01T00:00:00Z'
  5. Use valid presets: 'last_30_days' → 'last_month'

Example 6: Content and Relationship Searches

❌ Before (Deprecated) ✅ After (Universal) 
// Search companies by notes
await client.callTool('search-companies-by-notes', {
  searchText: 'quarterly review',
});

// Search people by company
await client.callTool('search-people-by-company', {
  company_id: 'comp_123',
});

// Search companies by notes
await client.callTool('records.search_by_content', {
  resource_type: 'companies',
  content_type: 'notes',
  search_query: 'quarterly review',
});

// Search people by company
await client.callTool('records.search_by_relationship', {
  resource_type: 'people',
  related_resource_type: 'companies',
  relationship_filter: {
    record_id: 'comp_123',
  },
});

Migration Steps:

  1. Content searches: search-*-by-notes → records.search_by_content
  2. Add parameters: resource_type, content_type: 'notes'
  3. Rename parameter: searchText → search_query
  4. Relationship searches: search-*-by-* → records.search_by_relationship
  5. Add parameters: resource_type, related_resource_type
  6. Wrap ID in filter: company_id → relationship_filter: { record_id }
}); ```

Example 2: People Search by Company

Before (deprecated):

await client.callTool('search-people-by-company', {
  company_id: 'comp_123',
  limit: 20,
});

After (universal):

await client.callTool('records.search_by_relationship', {
  relationship_type: 'company_to_people',
  source_id: 'comp_123',
  limit: 20,
});

Example 3: Company Info Retrieval

Before (deprecated):

await client.callTool('get-company-contact-info', {
  record_id: 'comp_123',
});

After (universal):

await client.callTool('records.get_info', {
  resource_type: 'companies',
  record_id: 'comp_123',
  info_type: 'contact',
});

Example 4: Batch Company Creation

Before (deprecated):

await client.callTool('batch-create-companies', {
  companies: [
    { name: 'Company A', domain: 'companya.com' },
    { name: 'Company B', domain: 'companyb.com' },
  ],
});

After (universal):

await client.callTool('records.batch', {
  resource_type: 'companies',
  operation_type: 'create',
  records: [
    { name: 'Company A', domain: 'companya.com' },
    { name: 'Company B', domain: 'companyb.com' },
  ],
});

Before (deprecated):

await client.callTool('search-people-by-creation-date', {
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-01-31T23:59:59Z',
});

After (universal):

await client.callTool('records.search_by_timeframe', {
  resource_type: 'people',
  timeframe_type: 'created',
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-01-31T23:59:59Z',
});

Breaking Changes and Important Updates

1. Date Filtering Operators ⚠️

The date operators have changed for Attio API compatibility:

❌ OLD (will cause API errors):

{
  condition: 'greater_than_or_equals', // ❌ Invalid
  condition: 'less_than_or_equals'     // ❌ Invalid
}

✅ NEW (correct):

{
  condition: 'after',  // ✅ Use instead of greater_than_or_equals
  condition: 'before'  // ✅ Use instead of less_than_or_equals
}

2. Valid Date Presets

Only these date presets are valid:

✅ Valid presets:

('today',
  'yesterday',
  'this_week',
  'last_week',
  'this_month',
  'last_month',
  'this_quarter',
  'last_quarter',
  'this_year',
  'last_year');

❌ Invalid preset:

'last_30_days'; // Will throw validation error

3. Query Parameter Requirements

  • Universal tool queries cannot be empty strings
  • Batch operations require meaningful search queries
  • Use specific search terms, not empty or generic values

❌ Invalid:

{
  resource_type: 'companies',
  query: ''  // Empty string not allowed
}

✅ Valid:

{
  resource_type: 'companies',
  query: 'tech startup'  // Meaningful search term
}

Migration Automation

Using getMigrationParams Utility

The universal tools system includes a utility function to help with migration:

import {
  getMigrationParams,
  getUniversalEquivalent,
} from './universal/index.js';

// Get the universal tool equivalent
const universalTool = getUniversalEquivalent('search-companies');
// Returns: 'records.search'

// Get migration parameters
const newParams = getMigrationParams('search-companies', {
  query: 'tech startup',
  limit: 10,
});
// Returns: { resource_type: 'companies', query: 'tech startup', limit: 10 }

Validation and Testing

Testing Your Migration

  1. Parameter Validation: Ensure all required parameters are included
  2. Resource Type: Verify correct resource_type values
  3. Date Operators: Use after/before instead of old operators
  4. Query Requirements: Provide meaningful search queries

Common Migration Errors

// ❌ Missing resource_type
await client.callTool('records.search', {
  query: 'tech startup', // Missing resource_type parameter
});

// ✅ Correct migration
await client.callTool('records.search', {
  resource_type: 'companies',
  query: 'tech startup',
});

Next Steps

  1. Update your tool calls using the migration table above
  2. Test your changes with the new universal tools
  3. Review the API Reference for detailed parameter schemas
  4. Check Troubleshooting if you encounter issues

Need Help?