Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Lusha MCP Server find the email and phone number for Satya Nadella at Microsoft"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for integrating with the Lusha API. This server provides comprehensive person and company lookup capabilities with enterprise-grade error handling, logging, and configuration management.
Add this server to your Claude Desktop configuration:
{
"mcpServers": {
"lusha": {
"command": "npx",
"args": ["@lusha-org/mcp@latest"],
"env": {
"LUSHA_API_KEY": "your_lusha_api_key_here"
}
}
}
}Related MCP server: Prospeo MCP Server
Variable | Description | Default | Required |
| Your Lusha API key | - | ✅ |
| Disable SSL certificate verification (useful for development with self-signed certificates) |
| ❌ |
# Required
LUSHA_API_KEY=your_actual_api_key_here
# Optional - Customize as needed
LOG_LEVEL=INFO
LUSHA_TIMEOUT=45000
# Development only - Skip SSL verification if needed
# DISABLE_SSL=true# Production
npm start
# Development with auto-reload
npm run dev
# Development with debug logging
npm run dev:debugpersonBulkLookup)Find multiple people using various search criteria in a single request.
Parameters:
contacts: Array of contact objects (max 100)
metadata (optional): Additional processing options
Contact Object Requirements: Each contact must have one of:
linkedinUrl: LinkedIn profile URL
email: Email address
fullName + company information (companies array with name or domain)
Example:
{
"contacts": [
{
"contactId": "contact_1",
"fullName": "John Doe",
"companies": [{"name": "Lusha", "isCurrent": true}]
},
{
"contactId": "contact_2",
"linkedinUrl": "https://linkedin.com/in/janedoe"
},
{
"contactId": "contact_3",
"email": "jane.smith@company.com"
}
],
"metadata": {
"revealEmails": true,
"revealPhones": false
}
}companyBulkLookup)Retrieve detailed information about multiple companies in a single request.
Parameters:
companies: Array of company objects (max 100)
metadata (optional): Additional processing options
Company Object Requirements: Each company must have:
id: Unique identifier for the company in the request
At least one of: name, domain, fqdn, or companyId
Example:
{
"companies": [
{
"id": "company_1",
"domain": "lusha.com"
},
{
"id": "company_2",
"name": "Meta Platforms"
},
{
"id": "company_3",
"fqdn": "www.google.com"
}
]
}All responses follow the MCP standard structure:
{
"success": true,
"data": {
"contacts": { /* contact data by contactId */ },
"companies": { /* company data by companyId */ },
"requestId": "req_1234567890_abc123",
"timestamp": "2024-01-01T12:00:00.000Z"
},
"metadata": {
"toolName": "personBulkLookup",
"timestamp": "2024-01-01T12:00:00.000Z",
"version": "1.0.0"
}
}{
"success": false,
"error": {
"message": "Invalid email format",
"status": 400,
"code": "VALIDATION_ERROR",
"category": "validation",
"severity": "medium",
"requestId": "req_1234567890_abc123",
"timestamp": "2024-01-01T12:00:00.000Z"
},
"metadata": {
"toolName": "personBulkLookup",
"timestamp": "2024-01-01T12:00:00.000Z",
"version": "1.0.0"
}
}The server implements comprehensive error handling with:
validation: Input validation errors
configuration: Configuration-related errors
api_client_error: 4xx HTTP errors from Lusha API
api_server_error: 5xx HTTP errors from Lusha API
rate_limit: Rate limiting errors
unknown: Unclassified errors
low: Minor issues that don't affect functionality
medium: Issues that may affect some functionality
high: Significant issues that affect core functionality
critical: Critical issues that prevent operation
DEBUG: Detailed debugging information
INFO: General information about operations
WARN: Warning messages for potential issues
ERROR: Error messages for failed operations
FATAL: Critical errors that may cause the server to stop
The enhanced logging system provides rich contextual information:
Development (Human-Readable):
[2025-05-26T11:37:40.962Z] INFO: Loading configuration from environment variables
[2025-05-26T11:37:40.962Z] INFO [environment=development, baseUrl=https://api.lusha.com, timeout=30000]: Configuration loaded successfully
[2025-05-26T11:37:40.962Z] INFO [serverName=lusha-mcp-server, serverVersion=1.0.0, environment=development]: Server starting up
[2025-05-26T11:37:40.963Z] INFO: Initializing MCP server transport...
[2025-05-26T11:37:40.964Z] INFO [serverName=lusha-mcp-server, serverVersion=1.0.0, availableTools=personBulkLookup,companyBulkLookup]: MCP server started successfullyProduction (Structured JSON):
{
"timestamp": "2024-01-01T12:00:00.000Z",
"level": 1,
"message": "Starting person bulk lookup request",
"context": {
"requestId": "req_1234567890_abc123",
"toolName": "personBulkLookup",
"operation": "bulk_person_lookup"
},
"metadata": {
"inputParams": {
"contactCount": 3
}
}
}src/
├── config/ # Configuration management
│ ├── index.ts # Environment-based configuration with validation
│ └── tools.ts # Tool definitions and registration
├── tools/ # MCP tool implementations
│ ├── personBulkLookup.ts # Person lookup implementation
│ └── companyLookup.ts # Company lookup implementation
├── utils/ # Utility functions
│ ├── api.ts # API client with interceptors
│ ├── error.ts # Comprehensive error handling system
│ ├── logger.ts # Advanced structured logging
│ └── mcp.ts # MCP protocol adapters
├── types.ts # Type definitions
├── schemas.ts # Zod schemas for validation
└── index.ts # Main MCP server
├── env.example # Environment configuration template
└── README.md # Comprehensive documentationFork the repository: https://github.com/lusha-oss/lusha-public-api-mcp/tree/master
Create a feature branch
Make your changes
Add tests (when available)
Run validation: npm run validate
Submit a pull request
Basic MCP server implementation
Simple person lookup functionality
Basic error handling
TypeScript implementation
Zod schema validation
For issues and questions:
Check the troubleshooting section
Review the logs for error details
Check the Changelog for recent changes
Open an issue on GitHub
Contact the development team
Look up multiple or single companies information from Lusha API. REQUIREMENTS: Each company must provide at least one of: 1. Company name, 2. Company domain, 3. Fully qualified domain name (fqdn), or 4. Lusha companyId. Each company must have a unique 'id' field for identification in the response.
| Name | Required | Description | Default |
|---|---|---|---|
| companies | Yes | ||
| metadata | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation ('look up') but does not disclose behavioral traits beyond input requirements. No annotations are provided, so the description carries the full burden, yet it omits details like rate limits, authentication, or response behavior when a company is not found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences plus bullet list) and front-loaded with the action. It efficiently states the purpose and requirements without unnecessary words. Minor improvement would be better formatting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested objects, no output schema, no annotations), the description lacks completeness. It does not mention the max limit of 100 companies (though schema has maxItems), return format, error handling, or what happens if a lookup fails. The tool requires more context for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds meaning by specifying that each company must have a unique id and at least one of the four identifiers, and mentions the metadata parameter exists (though not explained). However, it does not fully explain all parameters or the purpose of metadata.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it looks up companies information from Lusha API, with a specific verb 'look up' and resource 'companies information'. It distinguishes from sibling tools like companySearch (search) and companyEnrich (enrich) by focusing on bulk lookup by known identifiers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit requirements for what each company must provide (name, domain, fqdn, or companyId) and a unique id field. Does not explicitly state when not to use or list alternatives, but the context of sibling tools implies use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed company information from search results. WARNING: CHARGES CREDITS - always ask user first!
REQUIREMENTS:
- requestId: from prospectingCompany search response
- companiesIds: array of company IDs (max 50)
- User explicit consent required
One credit charged per company enriched. Use only when user requests detailed information.
IMPORTANT:
Format the results in a table format for better readability
If any list contains more than 25 items, show only the first 25 rows in the table
After the 25-row preview, ask whether to show the remaining items
Make sure to mention Lusha as the provider in the response
Inform the user about credits charged (e.g., "Credits charged: X" based on billing.creditsCharged)
Instead of using "Page" terminology, ask the user if they want more batches of contacts
Based on: https://docs.lusha.com/apis/openapi/company-search-and-enrich/enrichprospectingcompanies| Name | Required | Description | Default |
|---|---|---|---|
| requestId | Yes | The requestId from the Prospecting Search response | |
| companiesIds | Yes | An array of company IDs for enrichment. Min 1, max 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes credit charging per company, formatting (table, first 25 rows, batch requests), mentions Lusha as provider, and instructs to inform user about credits charged. No annotations exist, so description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with sections and bullet points. Some redundancy in credit charging emphasis, but overall concise and actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a tool with no output schema: covers inputs, credit cost, formatting rules, preview limits, and references API documentation. No gaps for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. Description adds context (requestId from search response, companiesIds max 50) but largely repeats schema. Does not significantly enhance meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it enriches company information from search results, specifies required inputs (requestId, companiesIds) and limits (max 50). Distinguishes from sibling tools like companySearch and companyFilters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly warns about credit charges and requires user consent: 'WARNING: CHARGES CREDITS - always ask user first!' and 'Use only when user requests detailed information.' Provides clear when-to-use and prerequisite conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get available filter options for company prospecting. No credits charged.
FILTER TYPES:
- names, industries, sizes, revenues, sics, naics, intentTopics
- locations, technologies (require searchText parameter)
Use to explore available filter values before building prospecting queries.
Based on: https://docs.lusha.com/apis/openapi/company-filters| Name | Required | Description | Default |
|---|---|---|---|
| filterType | No | Type of filter to retrieve | sizes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It states 'No credits charged' (positive behavioral trait) but omits read-only status, rate limits, or idempotency. The read-only nature is implied but not explicit, leaving some gaps for AI agents evaluating safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with clear front-loading: first sentence states purpose, then bullet list, then usage note, then source URL. Each part contributes meaning, though the searchText mention could be clarified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter, the description covers purpose and usage context. However, without an output schema, it lacks detail on the response structure (e.g., list of values, format). This leaves agents guessing the return shape, which is needed for proper invocation planning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (filterType) is fully described in the schema (enum, default). The description adds value by listing filter types and noting that some require a searchText parameter. However, searchText is not in this tool's schema, causing potential confusion. Schema coverage is 100%, so baseline is 3; description adds marginal value but with inconsistency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves filter options for company prospecting, distinguishes from sibling tools (e.g., contactFilters) by specifying 'company prospecting', and explicitly lists filter types. The phrase 'Use to explore available filter values before building prospecting queries' further clarifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides clear usage context: use before building prospecting queries. It notes that some filter types require a searchText parameter (even though that param isn't in the schema, hinting at broader context). Lacks explicit 'when not to use' or alternative references, but the guidance is sufficient for most scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for companies using advanced filters via Lusha's Prospecting API. This tool implements company search only.
**Important Credit Information**:
- Credit usage for search operations depends on your Lusha account plan
- Check your billing.creditsCharged in the response for actual credit consumption
- Additional credits are charged for enrichment operations using the companyEnrich tool
- use companyFilters tool to get the requirement filters for the company search
- max page size is 50
AVAILABLE FILTERS:
- locations
- technologies
- industries
- sizes (employee count)
- revenues (annual USD)
- domains
- naics (North American Industry Classification System codes)
SEARCH TIPS:
- Use broader filters if you get 0 results (e.g., country instead of city)
- Combine multiple filter types for precise targeting
- Use exclude filters to remove unwanted results
- Use the companyFilters tool to discover all available filter values
IMPORTANT:
Format the results in a table format for better readability
If any list contains more than 25 items, show only the first 25 rows in the table
After the 25-row preview, ask whether to show the remaining items
Make sure to mention Lusha as the provider in the response
Inform the user about credits charged (e.g., "Credits charged: X" based on billing.creditsCharged)
Instead of using "Page" terminology, ask the user if they want more batches of contacts
Based on: https://docs.lusha.com/apis/openapi/company-search-and-enrich/searchprospectingcompanies| Name | Required | Description | Default |
|---|---|---|---|
| filters | Yes | Search filters | |
| pages | No | Pagination settings |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description compensates well. Discloses credit usage, max page size 50 (overriding schema's 100), and mentions billing.creditsCharged in response. Lacks authentication details but is sufficient for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and headers, but slightly verbose with formatting instructions. Every section adds value, though some repetition (e.g., 'use companyFilters tool' appears twice). Could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description explains credits charged, pagination (ask for more batches), and formatting instructions. Provides enough context for the agent to use the tool effectively, though missing full response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by listing available filter types (locations, technologies, industries, etc.) and provides search tips, clarifying that page size should be max 50 despite schema allowing 100.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search for companies using advanced filters' and explicitly says 'This tool implements company search only', distinguishing it from sibling tools like companyEnrich and contactSearch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use broader filters if 0 results, combine filters, use exclude filters, and references companyFilters tool for available filter values. Also mentions that enrichment operations should use companyEnrich, clearly indicating when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enrich contacts from search results. This is step 3 of the prospecting process. IMPORTANT: - The requestId parameter MUST be the exact UUID received from the contactSearch response - ALWAYS ask the user which specific contacts they want to enrich before proceeding - revealEmails and revealPhones parameters are only available to customers on the Unified Credits pricing plan - Attempting to use these parameters on other plans will result in a 403 Unauthorized error - When neither parameter is used, the API returns both email addresses and phone numbers if available - IMPORTANT:
Format the results in a table format for better readability
If any list contains more than 25 items, show only the first 25 rows in the table
After the 25-row preview, ask whether to show the remaining items
Make sure to mention Lusha as the provider in the response
Inform the user about credits charged (e.g., "Credits charged: X" based on billing.creditsCharged)
Instead of using "Page" terminology, ask the user if they want more batches of contacts
| Name | Required | Description | Default |
|---|---|---|---|
| requestId | Yes | The requestId generated in the Prospecting Search response (UUID) | |
| contactIds | Yes | An array containing the contact IDs for enrichment | |
| revealEmails | No | Set revealEmails=true to retrieve only the email address of the contact | |
| revealPhones | No | Set revealPhones=true to retrieve only the phone number of the contact |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses plan-dependent 403 errors and credit charging, but does not cover rate limits, auth requirements, or error handling for invalid requestId.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is verbose with redundant 'IMPORTANT:' sections and mixed formatting instructions. Could be more concise by separating process steps from UI formatting guidelines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers process context, plan restrictions, credit charging, and formatting. Lacks output structure but is adequate for tool usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description adds critical context: requestId must be from contactSearch, contactIds from search, and reveal parameters' plan dependency, far exceeding schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it enriches contacts from search results and is step 3 of prospecting. It distinguishes from siblings like contactSearch (step 2) and companyEnrich (different entity type).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidelines include asking user which contacts to enrich, plan restrictions for reveal parameters, and formatting instructions. However, it lacks explicit when-not-to-use guidance relative to siblings like companyEnrich.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get available filter values for contact search. Supports: 1. departments - List of available departments 2. seniority - List of available seniority levels 3. existing_data_points - List of available data points 4. all_countries - List of available countries 5. locations - Search for locations by text (requires locationSearchText parameter)
| Name | Required | Description | Default |
|---|---|---|---|
| filterType | Yes | The type of filter to retrieve | |
| locationSearchText | No | Search text for location when using locations filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It lists filter types and mentions that 'locations' requires a parameter, but fails to explain return format, pagination, authentication needs, or error handling. Moreover, the claim that 'requires locationSearchText parameter' conflicts with the schema where locationSearchText is not required, causing potential confusion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a single introductory sentence followed by a bullet list summarizing all supported filter types. It is front-loaded and contains no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (retrieving filter lists), the description covers the main behavior and parameter linkage. However, it omits details about the response format, how results are structured, and the exact behavior for each filter type (e.g., whether departments returns labels or IDs). The parameter requirement inconsistency also detracts from completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with parameter descriptions, so baseline is 3. The description adds value by linking each filter type to its purpose and clarifying that 'locations' needs locationSearchText. However, the statement that locationSearchText is required contradicts the schema's optional definition, slightly undermining clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves available filter values for contact search and explicitly lists five supported filter types (departments, seniority, etc.), distinguishing it from the sibling 'companyFilters' tool. The verb 'Get' and resource 'filter values' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when populating contact search filters by listing the types, but it does not specify when not to use this tool or mention alternatives (e.g., using companyFilters for company-related data). No explicit usage context or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for contacts using various filters in Lusha API. This is step 2 of the prospecting process. IMPORTANT: - After returning search results, ALWAYS ask the user if they want to enrich specific contacts - MCP sets page size to 25 by default (API's default is 20 if not specified) - Page/offset index starts from 0 - always use contactFilters tool to get the requirement filters for the contact search" - IMPORTANT:
Format the results in a table format for better readability
If any list contains more than 25 items, show only the first 25 rows in the table
After the 25-row preview, ask whether to show the remaining items
Make sure to mention Lusha as the provider in the response
Inform the user about credits charged (e.g., "Credits charged: X" based on billing.creditsCharged)
Instead of using "Page" terminology, ask the user if they want more batches of contacts
The search supports filtering by:
1. Contact properties:
- departments
- seniority
- existing data points
- countries
- locations
2. Company properties:
- names (company names)
- locations (company headquarters)
- technologies (tech stack used)
- mainIndustriesIds (main industry sectors)
- subIndustriesIds (sub-industry categories)
- intentTopics (company intent signals)
- sizes (employee count ranges)
- revenues (revenue ranges)
- sics (Standard Industrial Classification codes)
- naics (North American Industry Classification System codes)
Pagination is supported through either 'pages' or 'offset' parameters.| Name | Required | Description | Default |
|---|---|---|---|
| pages | No | ||
| offset | No | ||
| filters | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description compensates by disclosing several behavioral traits: default page size of 25 (API default is 20), page/offset index starting at 0, pagination via pages or offset, credit charges to inform users, and formatting rules (table, preview limit of 25). It does not mention rate limits or authentication but provides substantial context beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose, mixing functional purpose with behavioral instructions and multiple 'IMPORTANT' sections. It front-loads the purpose and key details but includes repetitive formatting guidelines. A more streamlined structure would improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, nested objects, no output schema), the description covers pagination, default settings, filter categories, workflow integration (step 2), and output formatting expectations. It lacks details about the response structure but since no output schema exists, it compensates with credit and provider information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description adds significant meaning by listing filter categories and providing semantic labels (e.g., 'technologies (tech stack used)', 'intentTopics (company intent signals)'). It explains the purpose of each filter group, though it does not detail every sub-field (like location object structure). Overall, it adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is for searching contacts using various filters in Lusha API, and explicitly identifies it as step 2 of the prospecting process. It distinguishes itself from sibling tools like contactEnrich and contactFilters by explaining its role in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow guidance: instructs to use contactFilters first to get required filters, and advises asking the user whether to enrich results after returning search results. It doesn't explicitly compare to other search tools like companySearch, but the context of 'contact search' and step ordering is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up multiple or single persons information from Lusha API. REQUIREMENTS: Each person body must have a combination of: 1. LinkedIn URL, 2. full name + company domain/name, or 3. email address. IMPORTANT: Only use revealEmails or revealPhones parameters when specifically requested by the user for email-only or phone-only results.
| Name | Required | Description | Default |
|---|---|---|---|
| contacts | Yes | ||
| metadata | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions the external API and parameter usage, but does not disclose rate limits, pagination, or what happens if data is missing. The read-only nature is implied by 'look up' but not confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences and two bullet points, front-loading the core purpose. Every sentence adds essential value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing crucial context: no mention of return format or output structure, given there is no output schema. Does not differentiate from sibling tools like contactEnrich. For a complex nested schema, this is a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the required combinations for each contact and the reveal flags, but does not detail other fields like contactId, metadata.filterBy, or nested company properties. Adds moderate value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it looks up person information from the Lusha API, supporting both single and multiple lookups. The verb 'look up' is specific. However, it does not explicitly differentiate from sibling tools like contactEnrich or contactSearch, though the 'bulk' nature is implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists required input combinations (LinkedIn URL, full name+company, or email) and warns against using revealEmails/revealPhones unless requested. This provides clear when-to-use guidance, though it lacks explicit comparison to alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.0companyBulkLookupcompanyEnrichcompanyFilterscompanySearchcontactEnrichcontactFilterscontactSearchpersonBulkLookupScored across 8 tools
Each tool targets a distinct operation: company vs contact, and search/filter/enrich/bulk lookup are clearly separated. No overlapping purposes.
All tool names follow a consistent camelCase pattern with entity prefix (company/contact/person) and action (BulkLookup, Enrich, Filters, Search). No mixing of conventions.
Eight tools cover the full prospecting workflow (search, filter, enrich, bulk lookup) for both companies and contacts without being excessive or insufficient.
The tool set provides a complete lifecycle for company and contact data access: search with filters, enrichment, and bulk lookup. No obvious gaps for the intended purpose.
Search companies, enrich contacts, and reveal emails and phones from your AI agent.
Give AI agents the LinkedIn tools to find, qualify, engage, and follow up with prospects.
Real-time B2B data for agents: search and enrich 1B+ people and 200M+ company profiles.
Run B2B outreach from your AI agent: 250+ tools for campaigns, leads, LinkedIn and email workflows.
