# Tomba Local MCP Tools

## MCP Tools

This document provides detailed information about all thirteen tools available in the Tomba MCP Server. Each tool offers specific email intelligence capabilities with comprehensive input validation and structured output.

## Tools Overview

| Tool                | Purpose                           | Input                    | Output Type                  |
| ------------------- | --------------------------------- | ------------------------ | ---------------------------- |
| `domain_search`     | Find emails by domain             | Domain name + options    | Email list with metadata     |
| `email_finder`      | Generate email from name + domain | First/last name + domain | Single email with confidence |
| `email_verifier`    | Verify email deliverability       | Email address            | Verification status + score  |
| `email_enrichment`  | Enrich email with contact data    | Email address            | Complete contact profile     |
| `email_count`       | Get total email counts for domain | Domain name              | Email count statistics       |
| `author_finder`     | Find author emails from articles  | Article URL              | Author contact list          |
| `linkedin_finder`   | Find emails from LinkedIn         | LinkedIn profile URL     | Contact with verification    |
| `phone_finder`      | Find phone numbers                | Email/domain/LinkedIn    | Phone numbers with details   |
| `phone_validator`   | Validate phone numbers            | Phone number             | Validation results + carrier |
| `technology_finder` | Discover tech stacks              | Domain name              | Technology list + categories |
| `similar_finder`    | Find similar companies            | Domain name              | Similar domain list          |
| `companies_search`  | Search companies by query         | Natural language query   | Company list with filters    |

---

## Prompts (16 pre-built workflows)

### Contact Discovery & Enrichment

- **find_contact** - Find complete contact info for a person
- **enrich_lead** - Enrich a lead with all available data
- **prospect_enrichment** - Enrich company prospects with comprehensive data

### Email & Phone Verification

- **verify_email_list** - Batch verify email addresses
- **finder_phone** - Find phone numbers for contacts
- **validate_phone** - Validate a phone number

### Company & Market Research

- **research_company** - Research company contacts and structure
- **domain_insights** - Get comprehensive insights about a domain including email count and technology
- **bulk_domain_research** - Research multiple domains for email counts and basic information
- **market_research** - Research companies in a specific market segment
- **industry_analysis** - Analyze companies within a specific industry and location

### Competitive Intelligence

- **competitor_analysis** - Analyze competitors using similar domains and technology
- **technology_audit** - Comprehensive technology audit of a website

### Lead Generation & Targeting

- **find_target_companies** - Find companies matching specific criteria using natural language search
- **lead_generation** - Generate leads by finding companies and their contacts
- **find_journalists** - Find journalist contacts from articles

---

## Domain Search

**Purpose**: Discover all email addresses associated with a specific domain name.

### Input Schema

```json
{
    "domain": "string (required)",
    "limit": "number (optional, default: 10)",
    "offset": "number (optional, default: 0)",
    "type": "string (optional: 'personal' | 'generic')",
    "sources": "boolean (optional, default: true)"
}
```

### Parameters

| Parameter | Type    | Required | Description                    | Example        |
| --------- | ------- | -------- | ------------------------------ | -------------- |
| `domain`  | string  | Yes      | Target domain name             | `"github.com"` |
| `limit`   | number  | No       | Max results to return (1-100)  | `25`           |
| `offset`  | number  | No       | Results to skip for pagination | `0`            |
| `type`    | string  | No       | Filter by email type           | `"personal"`   |
| `sources` | boolean | No       | Include source information     | `true`         |

### Example Usage

```json
// MCP Request
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "domain_search",
        "arguments": {
            "domain": "github.com",
            "limit": 10,
            "type": "personal",
            "sources": true
        }
    }
}
```

### Response Format

```json
{
    "domain": "github.com",
    "emails": [
        {
            "email": "john.doe@github.com",
            "first_name": "John",
            "last_name": "Doe",
            "position": "Senior Developer",
            "department": "Engineering",
            "type": "personal",
            "confidence": 95,
            "sources": [
                {
                    "uri": "https://github.com/about",
                    "website_piece": "team",
                    "extracted_on": "2024-01-15",
                    "last_seen_on": "2024-01-15",
                    "still_on_page": true
                }
            ]
        }
    ],
    "total": 147,
    "limit": 10,
    "offset": 0
}
```

### Use Cases

- Lead generation for sales teams
- Competitive intelligence research
- Contact discovery for partnerships
- Email list building for marketing

---

## Email Finder

**Purpose**: Generate the most likely email address for a person based on their name and company domain.

### Input Schema

```json
{
    "domain": "string (required)",
    "firstName": "string (required)",
    "lastName": "string (required)"
}
```

### Parameters

| Parameter   | Type   | Required | Description         | Example           |
| ----------- | ------ | -------- | ------------------- | ----------------- |
| `domain`    | string | Yes      | Company domain      | `"microsoft.com"` |
| `firstName` | string | Yes      | Person's first name | `"Satya"`         |
| `lastName`  | string | Yes      | Person's last name  | `"Nadella"`       |

### Example Usage

```json
{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "email_finder",
        "arguments": {
            "domain": "microsoft.com",
            "firstName": "Satya",
            "lastName": "Nadella"
        }
    }
}
```

### Response Format

```json
{
    "email": "satya.nadella@microsoft.com",
    "score": 98,
    "first_name": "Satya",
    "last_name": "Nadella",
    "full_name": "Satya Nadella",
    "gender": "male",
    "country": "US",
    "position": "CEO",
    "twitter": "@satyanadella",
    "linkedin": "https://linkedin.com/in/satya-nadella",
    "phone_number": null,
    "company": "Microsoft Corporation",
    "sources": [
        {
            "uri": "https://microsoft.com/leadership",
            "website_piece": "executive-team",
            "extracted_on": "2024-01-10",
            "last_seen_on": "2024-01-15",
            "still_on_page": true
        }
    ]
}
```

### Use Cases

- Sales prospecting with known contacts
- Recruiting specific individuals
- Journalist source identification
- Partnership outreach

---

## Email Verifier

**Purpose**: Verify email address deliverability and check if it exists in Tomba's database.

### Input Schema

```json
{
    "email": "string (required)"
}
```

### Parameters

| Parameter | Type   | Required | Description             | Example              |
| --------- | ------ | -------- | ----------------------- | -------------------- |
| `email`   | string | Yes      | Email address to verify | `"test@example.com"` |

### Example Usage

```json
{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
        "name": "email_verifier",
        "arguments": {
            "email": "satya.nadella@microsoft.com"
        }
    }
}
```

### Response Format

```json
{
    "email": {
        "email": "satya.nadella@microsoft.com",
        "gibberish": false,
        "disposable": false,
        "webmail": false,
        "result": "deliverable",
        "score": 95
    },
    "sources": [
        {
            "uri": "https://microsoft.com/leadership",
            "website_piece": "executive-bio",
            "extracted_on": "2024-01-10",
            "last_seen_on": "2024-01-15",
            "still_on_page": true
        }
    ]
}
```

### Verification Results

| Result          | Description                           |
| --------------- | ------------------------------------- |
| `deliverable`   | Email exists and can receive messages |
| `undeliverable` | Email doesn't exist or bounces        |
| `risky`         | Email exists but may have issues      |
| `unknown`       | Cannot determine deliverability       |

### Use Cases

- Email list cleaning before campaigns
- Lead qualification and scoring
- Contact database maintenance
- Fraud prevention and validation

---

## Email Enrichment

**Purpose**: Get comprehensive contact information and social profiles for an email address.

### Input Schema

```json
{
    "email": "string (required)"
}
```

### Parameters

| Parameter | Type   | Required | Description     | Example                 |
| --------- | ------ | -------- | --------------- | ----------------------- |
| `email`   | string | Yes      | Email to enrich | `"contact@company.com"` |

### Example Usage

```json
{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
        "name": "email_enrichment",
        "arguments": {
            "email": "satya.nadella@microsoft.com"
        }
    }
}
```

### Response Format

```json
{
    "email": "satya.nadella@microsoft.com",
    "first_name": "Satya",
    "last_name": "Nadella",
    "full_name": "Satya Nadella",
    "gender": "male",
    "country": "United States",
    "position": "Chief Executive Officer",
    "twitter": "satyanadella",
    "linkedin": "https://linkedin.com/in/satya-nadella",
    "phone_number": "+1-425-882-8080",
    "company": "Microsoft Corporation",
    "industry": "Technology",
    "website": "microsoft.com"
}
```

### Use Cases

- CRM data enrichment
- Lead scoring and qualification
- Personalized outreach preparation
- Contact profile completion

---

## Author Finder

**Purpose**: Extract email addresses of authors from article URLs.

### Input Schema

```json
{
    "url": "string (required)"
}
```

### Parameters

| Parameter | Type   | Required | Description              | Example                         |
| --------- | ------ | -------- | ------------------------ | ------------------------------- |
| `url`     | string | Yes      | Article or blog post URL | `"https://example.com/article"` |

### Example Usage

```json
{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
        "name": "author_finder",
        "arguments": {
            "url": "https://github.blog/2024-01-15-new-features/"
        }
    }
}
```

### Response Format

```json
{
    "emails": [
        {
            "email": "author@github.com",
            "first_name": "Jane",
            "last_name": "Smith",
            "position": "Technical Writer",
            "twitter": "janesmith_dev",
            "linkedin": "https://linkedin.com/in/janesmith"
        },
        {
            "email": "editor@github.com",
            "first_name": "Mike",
            "last_name": "Johnson",
            "position": "Content Editor",
            "twitter": "mikejohnson",
            "linkedin": "https://linkedin.com/in/mikejohnson"
        }
    ]
}
```

### Use Cases

- Journalist contact discovery
- Guest posting outreach
- Expert source identification
- Content collaboration

---

## LinkedIn Finder

**Purpose**: Find email addresses associated with LinkedIn profile URLs.

### Input Schema

```json
{
    "url": "string (required)"
}
```

### Parameters

| Parameter | Type   | Required | Description          | Example                              |
| --------- | ------ | -------- | -------------------- | ------------------------------------ |
| `url`     | string | Yes      | LinkedIn profile URL | `"https://linkedin.com/in/username"` |

### Example Usage

```json
{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
        "name": "linkedin_finder",
        "arguments": {
            "url": "https://linkedin.com/in/satya-nadella"
        }
    }
}
```

### Response Format

```json
{
    "email": "satya.nadella@microsoft.com",
    "first_name": "Satya",
    "last_name": "Nadella",
    "full_name": "Satya Nadella",
    "country": "United States",
    "gender": "male",
    "position": "Chief Executive Officer",
    "twitter": "satyanadella",
    "phone_number": null,
    "company": "Microsoft",
    "verification": {
        "date": "2024-01-15",
        "signature": "verified_profile_abc123"
    }
}
```

### Use Cases

- Sales prospecting from LinkedIn
- Recruiting pipeline development
- Professional networking
- Contact verification from social profiles

---

### Use Cases

- Market research and analysis
- Competitive intelligence gathering
- Partnership opportunity identification
- Industry mapping and analysis

---

## Phone Finder

**Purpose**: Search for phone numbers based on email address, domain, or LinkedIn profile.

### Input Schema

```json
{
    "email": "string (optional)",
    "domain": "string (optional)",
    "linkedin": "string (optional)"
}
```

**Note**: At least one parameter is required.

### Parameters

| Parameter  | Type   | Required | Description          | Example                          |
| ---------- | ------ | -------- | -------------------- | -------------------------------- |
| `email`    | string | No\*     | Email address        | `"contact@company.com"`          |
| `domain`   | string | No\*     | Company domain       | `"company.com"`                  |
| `linkedin` | string | No\*     | LinkedIn profile URL | `"https://linkedin.com/in/user"` |

\*At least one parameter is required.

### Example Usage

```json
{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
        "name": "phone_finder",
        "arguments": {
            "email": "satya.nadella@microsoft.com"
        }
    }
}
```

### Response Format

```json
{
    "phone_number": "+1-425-882-8080",
    "country": "United States",
    "local_format": "(425) 882-8080",
    "intl_format": "+1 425 882 8080",
    "carrier": "Verizon",
    "line_type": "landline"
}
```

### Use Cases

- Multi-channel contact strategies
- Lead enrichment with phone data
- Customer service contact verification
- Sales outreach diversification

---

## Phone Validator

**Purpose**: Validate phone numbers and retrieve carrier information.

### Input Schema

```json
{
    "phone": "string (required)"
}
```

### Parameters

| Parameter | Type   | Required | Description              | Example             |
| --------- | ------ | -------- | ------------------------ | ------------------- |
| `phone`   | string | Yes      | Phone number to validate | `"+1-425-882-8080"` |

### Example Usage

```json
{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
        "name": "phone_validator",
        "arguments": {
            "phone": "+14258828080"
        }
    }
}
```

### Response Format

```json
{
    "phone_number": "+14258828080",
    "valid": true,
    "country": "United States",
    "country_code": "US",
    "local_format": "(425) 882-8080",
    "intl_format": "+1 425 882 8080",
    "carrier": "Verizon Business",
    "line_type": "landline",
    "is_mobile": false
}
```

### Validation Results

| Field          | Description                       |
| -------------- | --------------------------------- |
| `valid`        | Whether the phone number is valid |
| `country`      | Country name                      |
| `country_code` | ISO country code                  |
| `local_format` | Local formatting                  |
| `intl_format`  | International formatting          |
| `carrier`      | Telecom carrier name              |
| `line_type`    | "mobile", "landline", or "voip"   |
| `is_mobile`    | Boolean indicating mobile number  |

### Use Cases

- Contact data validation
- SMS campaign preparation
- Fraud prevention
- Call routing optimization

---

## Email Count

**Purpose**: Get total email count available in Tomba's database for a specific domain.

### Input Schema

```json
{
    "domain": "string (required)"
}
```

### Parameters

| Parameter | Type   | Required | Description        | Example        |
| --------- | ------ | -------- | ------------------ | -------------- |
| `domain`  | string | Yes      | Target domain name | `"stripe.com"` |

### Example Usage

```json
{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
        "name": "email_count",
        "arguments": {
            "domain": "stripe.com"
        }
    }
}
```

### Response Format

```json
{
    "total": 347,
    "personal": 312,
    "generic": 35,
    "department": {
        "engineering": 156,
        "sales": 78,
        "marketing": 45,
        "support": 33
    }
}
```

### Use Cases

- Market research and TAM analysis
- Lead generation planning
- Competitive intelligence
- Database coverage assessment

---

## Technology Finder

**Purpose**: Discover the technology stack used by a website (6000+ technologies tracked).

### Input Schema

```json
{
    "domain": "string (required)"
}
```

### Parameters

| Parameter | Type   | Required | Description        | Example         |
| --------- | ------ | -------- | ------------------ | --------------- |
| `domain`  | string | Yes      | Target domain name | `"shopify.com"` |

### Example Usage

```json
{
    "jsonrpc": "2.0",
    "id": 11,
    "method": "tools/call",
    "params": {
        "name": "technology_finder",
        "arguments": {
            "domain": "shopify.com"
        }
    }
}
```

### Response Format

```json
{
    "domain": "shopify.com",
    "technologies": [
        {
            "name": "Google Analytics",
            "category": "Analytics",
            "icon": "https://d12h6n0d1mbsct.cloudfront.net/technologies/google-analytics.png",
            "website": "https://analytics.google.com"
        },
        {
            "name": "Stripe",
            "category": "Payment Processing",
            "icon": "https://d12h6n0d1mbsct.cloudfront.net/technologies/stripe.png",
            "website": "https://stripe.com"
        },
        {
            "name": "Cloudflare",
            "category": "CDN",
            "icon": "https://d12h6n0d1mbsct.cloudfront.net/technologies/cloudflare.png",
            "website": "https://cloudflare.com"
        }
    ],
    "categories": {
        "Analytics": 3,
        "Payment Processing": 2,
        "CDN": 1,
        "Marketing Automation": 2,
        "CRM": 1
    }
}
```

### Technology Categories

Common categories include:

- Analytics & Tracking
- Payment Processing
- CDN & Hosting
- Marketing Automation
- CRM & Sales
- E-commerce Platforms
- Email Services
- Customer Support
- Security & Compliance
- Development Tools

### Use Cases

- Competitive analysis
- Sales intelligence (know what tools prospects use)
- Partnership opportunities
- Market research on technology adoption
- Lead qualification based on tech stack

---

## Similar Finder

**Purpose**: Find companies similar to a target domain based on industry, size, and characteristics.

### Input Schema

```json
{
    "domain": "string (required)",
    "limit": "number (optional, default: 10)"
}
```

### Parameters

| Parameter | Type   | Required | Description        | Example            |
| --------- | ------ | -------- | ------------------ | ------------------ |
| `domain`  | string | Yes      | Target domain name | `"salesforce.com"` |
| `limit`   | number | No       | Max results (1-50) | `20`               |

### Example Usage

```json
{
    "jsonrpc": "2.0",
    "id": 12,
    "method": "tools/call",
    "params": {
        "name": "similar_finder",
        "arguments": {
            "domain": "salesforce.com",
            "limit": 10
        }
    }
}
```

### Response Format

```json
{
    "domain": "salesforce.com",
    "similar_domains": [
        {
            "domain": "hubspot.com",
            "similarity_score": 95,
            "industry": "CRM & Marketing Automation",
            "employees": "1001-5000",
            "website": "https://hubspot.com"
        },
        {
            "domain": "zoho.com",
            "similarity_score": 92,
            "industry": "CRM & Business Software",
            "employees": "5001-10000",
            "website": "https://zoho.com"
        },
        {
            "domain": "pipedrive.com",
            "similarity_score": 88,
            "industry": "Sales CRM",
            "employees": "501-1000",
            "website": "https://pipedrive.com"
        }
    ],
    "total": 47
}
```

### Similarity Scoring

Similarity is calculated based on:

- Industry classification
- Company size (employees)
- Technology stack overlap
- Business model
- Target market

| Score    | Meaning                           |
| -------- | --------------------------------- |
| 90-100   | Very similar (direct competitors) |
| 80-89    | Highly similar (same space)       |
| 70-79    | Similar (adjacent markets)        |
| 60-69    | Somewhat similar                  |
| Below 60 | Different but related             |

### Use Cases

- Competitive intelligence
- TAM (Total Addressable Market) expansion
- Partnership opportunity discovery
- Market mapping
- Lead generation (find lookalike companies)

---

## Companies Search

**Purpose**: Search for companies using natural language queries with advanced filters.

### Input Schema

```json
{
    "query": "string (required)",
    "page": "number (optional, default: 1)",
    "limit": "number (optional, default: 50)",
    "filters": "object (optional)"
}
```

### Parameters

| Parameter | Type   | Required | Description                 | Example                     |
| --------- | ------ | -------- | --------------------------- | --------------------------- |
| `query`   | string | Yes      | Natural language search     | `"SaaS startups in Europe"` |
| `page`    | number | No       | Page number                 | `1`                         |
| `limit`   | number | No       | Results per page (max: 100) | `50`                        |
| `filters` | object | No       | Advanced filter object      | See filters below           |

### Example Usage

**Simple Natural Language Query:**

```json
{
    "jsonrpc": "2.0",
    "id": 13,
    "method": "tools/call",
    "params": {
        "name": "companies_search",
        "arguments": {
            "query": "Real Estate companies in Europe",
            "limit": 50
        }
    }
}
```

**Advanced Query with Filters:**

```json
{
    "jsonrpc": "2.0",
    "id": 14,
    "method": "tools/call",
    "params": {
        "name": "companies_search",
        "arguments": {
            "query": "E-commerce companies",
            "limit": 50,
            "filters": {
                "country": ["US", "UK"],
                "employees": "51-200",
                "revenue": "$10M-$50M",
                "technologies": ["Shopify", "Stripe"]
            }
        }
    }
}
```

### Response Format

```json
{
    "companies": [
        {
            "domain": "example-ecommerce.com",
            "organization": "Example E-commerce Inc",
            "industry": "E-commerce",
            "country": "US",
            "city": "San Francisco",
            "employees": "51-200",
            "revenue": "$10M-$50M",
            "founded": 2018,
            "description": "Leading online retailer for sustainable products",
            "technologies": ["Shopify", "Stripe", "Google Analytics"],
            "email_count": 67,
            "website": "https://example-ecommerce.com"
        }
    ],
    "total": 1247,
    "page": 1,
    "limit": 50,
    "has_more": true
}
```

### Available Filters

| Filter         | Type          | Description                  | Example                         |
| -------------- | ------------- | ---------------------------- | ------------------------------- |
| `country`      | array[string] | Country codes (ISO 2-letter) | `["US", "UK", "FR"]`            |
| `industry`     | array[string] | Industry categories          | `["Technology", "Finance"]`     |
| `employees`    | string        | Employee range               | `"51-200"`                      |
| `revenue`      | string        | Revenue range                | `"$10M-$50M"`                   |
| `founded`      | object        | Year founded range           | `{"min": 2010, "max": 2020}`    |
| `technologies` | array[string] | Technologies used            | `["AWS", "Stripe"]`             |
| `city`         | array[string] | City names                   | `["San Francisco", "New York"]` |

### Employee Ranges

- `"1-10"` - Micro
- `"11-50"` - Small
- `"51-200"` - Medium
- `"201-500"` - Large
- `"501-1000"` - Very Large
- `"1001-5000"` - Enterprise
- `"5001+"` - Mega Enterprise

### Revenue Ranges

- `"$0-$1M"` - Bootstrapped
- `"$1M-$10M"` - Growing
- `"$10M-$50M"` - Established
- `"$50M-$100M"` - Large
- `"$100M-$500M"` - Very Large
- `"$500M-$1B"` - Major
- `"$1B+"` - Enterprise

### Use Cases

- Lead generation with specific criteria
- Market research and analysis
- Competitive landscape mapping
- Partnership opportunity identification
- Investment research (VC/PE)
- Account-Based Marketing (ABM) list building

---

## Common Parameters

### Pagination

Many tools support pagination through `limit` and `offset`:

```json
{
    "limit": 25, // Items per page (max: 100)
    "offset": 50 // Items to skip (for page 3 with limit 25)
}
```

### Confidence Scoring

Results include confidence scores (0-100):

- **90-100**: Very High - Verified or highly likely
- **70-89**: High - Strong indicators
- **50-69**: Medium - Some evidence
- **30-49**: Low - Weak indicators
- **0-29**: Very Low - Speculative

### Source Attribution

Many results include source information:

```json
{
    "sources": [
        {
            "uri": "https://example.com/page",
            "website_piece": "contact",
            "extracted_on": "2024-01-15",
            "last_seen_on": "2024-01-15",
            "still_on_page": true
        }
    ]
}
```

## Error Handling

All tools return consistent error formats:

```json
{
    "content": [
        {
            "type": "text",
            "text": "Error: Invalid email format provided"
        }
    ],
    "isError": true
}
```

### Common Error Types

- **Invalid Input**: Malformed parameters
- **Rate Limit**: API quota exceeded
- **Authentication**: Invalid API credentials
- **Not Found**: No results for query
- **Network Error**: Connection issues

## Usage Tips

### Best Practices

1. **Start Small**: Use small limits while testing
2. **Verify Inputs**: Validate parameters before sending
3. **Handle Errors**: Always check for error responses
4. **Rate Limiting**: Respect API limits and implement backoff
5. **Data Quality**: Use confidence scores for filtering

### Performance Optimization

- Use pagination for large result sets
- Batch similar requests when possible
- Cache results when appropriate
- Monitor API quota usage

### Data Privacy

- Only request necessary data
- Handle personal information securely
- Respect opt-out requests
- Follow local privacy regulations

---

Ready to use these tools? Check out the [LLM Integration Guide](llm-files.md) for connecting with AI applications.