mcpengine/servers/apollo/src/tools/accounts.ts

/**
 * Apollo.io Account/Organization Tools
 */

import type { Tool } from '@modelcontextprotocol/sdk/types.js';

export const listAccountsTool: Tool = {
  name: 'list_accounts',
  description: 'Lists accounts (companies/organizations) from Apollo.io with pagination support. Use when the user wants to browse their account database, review target companies, or export organization data. Returns paginated results with up to 100 accounts per page. Supports filtering by labels, owner, or industry.',
  inputSchema: {
    type: 'object',
    properties: {
      page: {
        type: 'number',
        description: 'Page number to retrieve (starts at 1)',
        default: 1,
      },
      per_page: {
        type: 'number',
        description: 'Number of accounts per page (max 100)',
        default: 25,
      },
      label_ids: {
        type: 'array',
        items: { type: 'string' },
        description: 'Filter by label IDs',
      },
      owner_id: {
        type: 'string',
        description: 'Filter by account owner user ID',
      },
    },
  },
  _meta: {
    category: 'accounts',
    access_level: 'read',
    complexity: 'low',
  },
};

export const getAccountTool: Tool = {
  name: 'get_account',
  description: 'Retrieves a single account/organization by ID from Apollo.io. Use when the user asks for detailed information about a specific company, including employee count, revenue, industry, technologies, funding, and all custom fields. Returns complete account record with all available enrichment data.',
  inputSchema: {
    type: 'object',
    properties: {
      id: {
        type: 'string',
        description: 'The unique ID of the account to retrieve',
      },
    },
    required: ['id'],
  },
  _meta: {
    category: 'accounts',
    access_level: 'read',
    complexity: 'low',
  },
};

export const searchAccountsTool: Tool = {
  name: 'search_accounts',
  description: 'Searches for accounts/companies in Apollo.io using advanced filters including industry, employee count, revenue, location, technology stack, and funding. Use when the user wants to find companies matching specific criteria (e.g., "find all SaaS companies in NYC with 50-200 employees"). Supports complex boolean queries and returns paginated results with up to 100 matches per page. Essential for account-based prospecting and market research.',
  inputSchema: {
    type: 'object',
    properties: {
      q_keywords: {
        type: 'string',
        description: 'Keywords to search in company name, domain, or description',
      },
      organization_locations: {
        type: 'array',
        items: { type: 'string' },
        description: 'Filter by location (city, state, or country)',
      },
      organization_num_employees_ranges: {
        type: 'array',
        items: { type: 'string' },
        description: 'Filter by employee count ranges (e.g., ["1,10", "11,50", "201,500"])',
      },
      organization_industry_tag_ids: {
        type: 'array',
        items: { type: 'string' },
        description: 'Filter by industry tag IDs',
      },
      revenue_range: {
        type: 'object',
        properties: {
          min: { type: 'number', description: 'Minimum annual revenue' },
          max: { type: 'number', description: 'Maximum annual revenue' },
        },
        description: 'Filter by revenue range',
      },
      label_ids: {
        type: 'array',
        items: { type: 'string' },
        description: 'Filter by label IDs',
      },
      page: {
        type: 'number',
        description: 'Page number (starts at 1)',
        default: 1,
      },
      per_page: {
        type: 'number',
        description: 'Results per page (max 100)',
        default: 25,
      },
    },
  },
  _meta: {
    category: 'accounts',
    access_level: 'read',
    complexity: 'medium',
  },
};

export const createAccountTool: Tool = {
  name: 'create_account',
  description: 'Creates a new account/organization in Apollo.io. Use when the user wants to add a new company to their target account list, such as after identifying a prospect company or importing from external sources. Accepts account details including name, domain, industry, location, and custom fields. Apollo will attempt to enrich the account with additional data. Returns the newly created account with assigned ID.',
  inputSchema: {
    type: 'object',
    properties: {
      name: {
        type: 'string',
        description: 'Company/organization name',
      },
      domain: {
        type: 'string',
        description: 'Company website domain (e.g., "example.com")',
      },
      website_url: {
        type: 'string',
        description: 'Full website URL',
      },
      phone_number: {
        type: 'string',
        description: 'Primary phone number',
      },
      industry: {
        type: 'string',
        description: 'Industry or sector',
      },
      city: {
        type: 'string',
        description: 'City',
      },
      state: {
        type: 'string',
        description: 'State or province',
      },
      country: {
        type: 'string',
        description: 'Country',
      },
      label_ids: {
        type: 'array',
        items: { type: 'string' },
        description: 'Array of label IDs to assign',
      },
    },
    required: ['name'],
  },
  _meta: {
    category: 'accounts',
    access_level: 'write',
    complexity: 'medium',
  },
};

export const updateAccountTool: Tool = {
  name: 'update_account',
  description: 'Updates an existing account/organization in Apollo.io. Use when the user needs to modify company information such as updating industry classification, changing ownership, adding labels, or correcting account details. Only specified fields will be updated; others remain unchanged. Returns the updated account record.',
  inputSchema: {
    type: 'object',
    properties: {
      id: {
        type: 'string',
        description: 'The unique ID of the account to update',
      },
      name: {
        type: 'string',
        description: 'Updated company name',
      },
      domain: {
        type: 'string',
        description: 'Updated domain',
      },
      industry: {
        type: 'string',
        description: 'Updated industry',
      },
      owner_id: {
        type: 'string',
        description: 'Updated owner user ID',
      },
      label_ids: {
        type: 'array',
        items: { type: 'string' },
        description: 'Updated array of label IDs (replaces existing)',
      },
    },
    required: ['id'],
  },
  _meta: {
    category: 'accounts',
    access_level: 'write',
    complexity: 'medium',
  },
};