Copy page

Local MCP Server

Tomba Local MCP Tools

MCP Tools

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

Tools Overview (28 tools)

Email Discovery

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
author_finder	Find author emails from articles	Article URL	Author contact list
linkedin_finder	Find emails from LinkedIn	LinkedIn profile URL	Contact with verification
email_count	Get total email counts for domain	Domain name	Email count statistics
email_sources	Find where an email was found	Email address	Source URLs with dates
email_format	Get email format patterns	Domain name	Format patterns + confidence

Verification

Tool	Purpose	Input	Output Type
email_verifier	Verify email deliverability	Email address	Verification status + score

Enrichment

Tool	Purpose	Input	Output Type
email_enrichment	Enrich email with contact data	Email address	Complete contact profile
person_enrichment	Person data by email	Email address	Name, position, social
company_enrichment	Company data by domain	Domain name	Industry, size, social
combined_enrichment	Person + company by email	Email address	Combined person & company

Phone

Tool	Purpose	Input	Output Type
phone_finder	Find phone numbers	Email/domain/LinkedIn	Phone numbers with details
phone_validator	Validate phone numbers	Phone number	Validation results + carrier

Domain Intelligence

Tool	Purpose	Input	Output Type
domain_status	Check webmail or disposable	Domain name	Webmail/disposable flags
autocomplete	Company name suggestions	Partial query	Company names + domains
similar_finder	Find similar companies	Domain name	Similar domain list
technology_finder	Discover tech stacks	Domain name	Technology list + categories
location	Employee locations by country	Domain name	Country counts

Company Search

Tool	Purpose	Input	Output Type
companies_search	Search companies by query	Natural language query	Company list with filters

Account & Management

Tool	Purpose	Input	Output Type
account_info	Get account information	None	Plan, credits, limits
usage_info	Get API usage statistics	None	Usage stats per endpoint
list_flags	List submitted data flags	Page, limit	Flags with status
create_flag	Report incorrect data	flag_type, value, reason	Flag confirmation
list_leads	List leads	Page, limit, domain	Leads list
create_lead	Create a new lead	email, list_id	Created lead ID
list_keys	List API keys	None	Keys list
get_logs	Get API request logs	Page, limit	Recent API logs

---

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
• phone_finder - 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

Code
{
    "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

Code
// 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

Code
{
    "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

Code
{
    "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

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

Response Format

Code
{
    "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

Code
{
    "email": "string (required)"
}

Parameters

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

Example Usage

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

Response Format

Code
{
    "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

Code
{
    "email": "string (required)"
}

Parameters

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

Example Usage

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

Response Format

Code
{
    "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

Code
{
    "url": "string (required)"
}

Parameters

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

Example Usage

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

Response Format

Code
{
    "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

Code
{
    "url": "string (required)"
}

Parameters

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

Example Usage

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

Response Format

Code
{
    "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

Code
{
    "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

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

Response Format

Code
{
    "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

Code
{
    "phone": "string (required)"
}

Parameters

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

Example Usage

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

Response Format

Code
{
    "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

Code
{
    "domain": "string (required)"
}

Parameters

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

Example Usage

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

Response Format

Code
{
    "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

Code
{
    "domain": "string (required)"
}

Parameters

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

Example Usage

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

Response Format

Code
{
    "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

Code
{
    "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

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

Response Format

Code
{
    "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

Code
{
    "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:

Code
{
    "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:

Code
{
    "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

Code
{
    "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

---

Email Sources

Purpose: Find where an email address was found on the web.

Parameters

Parameter	Type	Required	Description	Example
email	string	Yes	Email address to search	"m@wordpress.org"

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 14,
    "method": "tools/call",
    "params": {
        "name": "email_sources",
        "arguments": {
            "email": "m@wordpress.org"
        }
    }
}

---

Email Format

Purpose: Get the email format patterns used by a specific domain.

Parameters

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

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 15,
    "method": "tools/call",
    "params": {
        "name": "email_format",
        "arguments": {
            "domain": "stripe.com"
        }
    }
}

---

Domain Status

Purpose: Check if a domain is a webmail provider or disposable email service.

Parameters

Parameter	Type	Required	Description	Example
domain	string	Yes	Target domain name	"gmail.com"

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 16,
    "method": "tools/call",
    "params": {
        "name": "domain_status",
        "arguments": {
            "domain": "gmail.com"
        }
    }
}

---

Autocomplete

Purpose: Company name suggestions with logo and domain information.

Parameters

Parameter	Type	Required	Description	Example
query	string	Yes	Partial company name/domain	"stripe"

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 17,
    "method": "tools/call",
    "params": {
        "name": "autocomplete",
        "arguments": {
            "query": "stripe"
        }
    }
}

---

Location

Purpose: Get employees location count by country for a domain.

Parameters

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

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 18,
    "method": "tools/call",
    "params": {
        "name": "location",
        "arguments": {
            "domain": "stripe.com"
        }
    }
}

---

Person Enrichment

Purpose: Find person data by email including name, position, company, and social profiles.

Parameters

Parameter	Type	Required	Description	Example
email	string	Yes	Email address to enrich	"m@wordpress.org"

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 19,
    "method": "tools/call",
    "params": {
        "name": "person_enrichment",
        "arguments": {
            "email": "m@wordpress.org"
        }
    }
}

---

Company Enrichment

Purpose: Find company data by domain including industry, size, location, and social profiles.

Parameters

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

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 20,
    "method": "tools/call",
    "params": {
        "name": "company_enrichment",
        "arguments": {
            "domain": "stripe.com"
        }
    }
}

---

Combined Enrichment

Purpose: Combined person and company enrichment by email — returns both person and company data.

Parameters

Parameter	Type	Required	Description	Example
email	string	Yes	Email address to enrich	"m@wordpress.org"

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 21,
    "method": "tools/call",
    "params": {
        "name": "combined_enrichment",
        "arguments": {
            "email": "m@wordpress.org"
        }
    }
}

---

Account Info

Purpose: Get current Tomba account information including plan, credits, and usage limits.

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 22,
    "method": "tools/call",
    "params": {
        "name": "account_info",
        "arguments": {}
    }
}

---

Usage Info

Purpose: Get current API usage statistics across all endpoints.

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 23,
    "method": "tools/call",
    "params": {
        "name": "usage_info",
        "arguments": {}
    }
}

---

List Flags

Purpose: List submitted data flags with their status and credit refund information.

Parameters

Parameter	Type	Required	Description	Default
page	number	No	Page number	1
limit	number	No	Results per page (max 100)	10

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 24,
    "method": "tools/call",
    "params": {
        "name": "list_flags",
        "arguments": { "page": 1, "limit": 10 }
    }
}

---

Create Flag

Purpose: Report incorrect data (hard bounces, invalid emails, wrong company info) for credit recovery.

Parameters

Parameter	Type	Required	Description
flag_type	string	Yes	email, organization, phone, author_url, website
value	string	Yes	The flagged item (2-255 chars)
reason	string	Yes	Reason (must match flag_type)
comment	string	No	Additional details (max 1000 chars)

Flag Type / Reason Validation

Flag Type	Valid Reasons
email	hard_bounce, invalid_email, wrong_person, outdated, other
organization	wrong_company, outdated, other
phone	wrong_phone, outdated, other
author_url	broken_url, wrong_person, outdated, other
website	broken_url, wrong_company, outdated, other

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 25,
    "method": "tools/call",
    "params": {
        "name": "create_flag",
        "arguments": {
            "flag_type": "email",
            "value": "bounced@example.com",
            "reason": "hard_bounce",
            "comment": "Email hard bounced on send"
        }
    }
}

---

List Leads

Purpose: List leads with optional domain filter and pagination.

Parameters

Parameter	Type	Required	Description	Default
page	number	No	Page number	1
limit	number	No	Results per page	10
domain	string	No	Filter by domain	—

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 26,
    "method": "tools/call",
    "params": {
        "name": "list_leads",
        "arguments": { "domain": "stripe.com" }
    }
}

---

Create Lead

Purpose: Add a new lead to a list.

Parameters

Parameter	Type	Required	Description
email	string	Yes	Lead's email address
list_id	number	Yes	Lead list ID
first_name	string	No	First name
last_name	string	No	Last name
company	string	No	Company name
position	string	No	Job title

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 27,
    "method": "tools/call",
    "params": {
        "name": "create_lead",
        "arguments": {
            "email": "john@stripe.com",
            "list_id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "company": "Stripe",
            "position": "Software Engineer"
        }
    }
}

---

List Keys

Purpose: List all API keys for the account.

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 28,
    "method": "tools/call",
    "params": {
        "name": "list_keys",
        "arguments": {}
    }
}

---

Get Logs

Purpose: Get recent API request logs.

Parameters

Parameter	Type	Required	Description	Default
page	number	No	Page number	1
limit	number	No	Results per page	10

Example Usage

Code
{
    "jsonrpc": "2.0",
    "id": 29,
    "method": "tools/call",
    "params": {
        "name": "get_logs",
        "arguments": { "page": 1, "limit": 20 }
    }
}

---

Performance & Reliability

Timeout

All API calls have a 120-second timeout. Tomba searches run in real time against live infrastructure — response times vary with the target company's SMTP server speed, website responsiveness, and the depth of catch-all detection.

Retry with Exponential Backoff

All API calls automatically retry up to 3 times with exponential backoff on 429 Too Many Requests and 5xx server errors. Retry delays: 1s → 2s → 4s.

---

Common Parameters

Pagination

Many tools support pagination through limit and offset:

Code
{
    "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:

Code
{
    "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:

Code
{
    "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 for connecting with AI applications.