mcp

Lusha Add Entities to Table

table_add_entities

Lusha Workspace: adds known Lusha entity ids (contacts or companies) to a table; duplicates are deduped.

Use when: adding specific Lusha ids from a prior search/enrich result into an existing table. Do not use when: searching-and-saving in one step (use a search tool) or removing rows (table_remove_entities).

For contacts tables, pass company_ids index-aligned with entity_ids so the workspace can enrich each contact (person + company pair); ignored for companies tables. Returns: counts of added, alreadyPresent, and invalidIds, plus attribution and billing (creditsCharged, lowBalance). Credits: free for contacts tables. For companies tables, consumes Lusha credits per newly added company at the account's revealCompany rate (see account_usage). Credits for every resolvable company sent are reserved before the add, so a balance that cannot cover them fails with HTTP 402 and adds nothing; alreadyPresent duplicates and invalidIds are not charged. billing.creditsCharged reports the actual charge.

Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "entity_type": "<entity_type>",
      "table_id": "<table_id>",
      "entity_ids": "<entity_ids>",
      "reason_for_invocation": "<reason_for_invocation>"
    },
    "name": "table_add_entities"
  }
}

Input Schema

Name	Required	Description
`email`	No	Owner email: the user in the account that owns the table (the API resolves it to a userId). Needed only when the credential has no associated user, such as an API key that does not resolve to a specific user. With OAuth, or an API key already scoped to a user, the caller's own userId identifies the owner and email can be omitted; it may still be passed to act on behalf of another owner.
`table_id`	Yes	The target Workspace table's UUID, as returned by table_create or table_list.
`entity_ids`	Yes	Lusha entity ids to add (deduped automatically). Up to 500 per call.
`company_ids`	No	Contacts tables only: lushaCompanyId per contact, index-aligned with entity_ids, so the workspace can enrich the contact (person + company pair). Ignored for companies tables.
`entity_type`	Yes	Which Lusha entity the table holds: 'contacts' or 'companies'. Routes the call to /v3/contacts/* or /v3/companies/*; a table only ever holds one entity type.
`next_step_ref`	No	Next-step reference: the ref of the next step this call carries out, when the user chose it from the next_step_hints of an earlier Lusha tool response, passed back unchanged. Absent otherwise.
`conversation_id`	No	Conversation correlation ID: the conversation_id returned by the most recent Lusha tool response in this conversation that included one, passed back unchanged. Calls that carry the same value are linked as one conversation. Absent on the first call of a conversation.
`reason_for_invocation`	Yes	Brief explanation of why you chose this tool for the current task. Required; at least 20 characters and at most 500 (longer values are truncated). Plain text only.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 2, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing billing semantics (free for contacts tables, per-company revealCompany rate for companies tables), pre-reservation of credits, HTTP 402 on insufficient balance that 'adds nothing', exclusion of duplicates/invalid ids from charges, HTTP 429 rate-limit behavior, and the returned counters. The one nuance is that 'duplicates are deduped' and 'alreadyPresent ... not charged' reads nearly idempotent while idempotentHint=false, but this is a mild tension rather than a contradiction given the write side effects (credits, row inserts).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Effectively front-loaded: purpose first, then Use when / Do not use when, then returns, credits, rate limits. The length is earned by the cost-bearing side effects an agent must understand before invoking a credit-consuming write.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers everything needed for a non-idempotent, credit-consuming write with no output schema: which ids to pass, how contacts get enriched, what the return payload contains (added/alreadyPresent/invalidIds/attribution/billing), failure modes (402, 429), and where to check rates (account_usage). Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage the schema already documents every parameter, but the description adds real semantics: the index-aligned company_ids ↔ entity_ids pairing for contact enrichment and its no-op on companies tables, plus that deduplication is automatic. It does not restate email, next_step_ref, conversation_id, or reason_for_invocation, which are already well covered in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('adds known Lusha entity ids (contacts or companies) to a table') plus scope limits (dedup, existing table). It clearly distinguishes itself from the search-and-save path and from table_remove_entities, so an agent can place it correctly among the ~55 siblings without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit 'Use when' condition (adding specific Lusha ids from a prior search/enrich result into an existing table) and an explicit 'Do not use when' covering both alternatives: one-step search-and-save tools and row removal via table_remove_entities. No inference required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All mcp tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.