> ## Documentation Index > Fetch the complete documentation index at: https://docs.api.tamtam.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP tools > Input parameters, allowed values, defaults, and error behavior for every Tamtam MCP tool. This page documents the Model Context Protocol (MCP) tool surface. Each tool's input schema is generated directly from the server, so the parameters listed here are exactly what the MCP `tools/list` handshake exposes to your assistant. **36 tools** are registered. ## Error behavior Errors are uniform across every tool: * **Invalid arguments** (wrong type, malformed payload) return a tool error (`isError: true`) with a message prefixed `invalid arguments:`. The call is not billed. * **Internal failures** return a tool error with a generic message; details are logged server-side and not exposed to the caller. * A tool error is delivered as a normal MCP result with `isError: true` (not a transport-level failure), so the assistant can read the message and recover. Parameters not listed as **required** are optional. Where a default is shown, omitting the parameter applies that default. *** ## `add_companies_to_key_accounts` Add one or more companies to Key Accounts. This must be done before any deep-research tool can be called on a target company. Costs 1 credit per newly-added company; companies already in Key Accounts are not re-charged. Use a search tool (search\_companies\_by\_name, search\_companies\_by\_filters, etc.) first to obtain LinkedIn IDs. **Call `skill_research_key_account` first** to learn the full research workflow and the asynchronous nature of the generated outputs. | Parameter | Type | Required | Allowed values | Default | Description | | ---------------------- | -------------- | ------------ | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------- | | `company_linkedin_ids` | array\ | **required** | — | — | LinkedIn IDs of companies to add to Key Accounts. Resolve via search\_companies\_by\_name first. | | `tags` | array\ | optional | — | — | Optional free-form tags to attach to newly-unlocked companies (e.g. 'strategic', 'renewal-q2'). Omit if no tags. | | `tier_level` | number | optional | 1 – 3 | `1` | Optional priority tier (1-3). Higher = higher priority. Omit if user has no preference (defaults to 1). | ## `enrich_people` Enrich people with their professional email addresses and/or phone numbers. Identify people by LinkedIn URL (preferred), or by firstname + lastname + company domain. The domain field is required when enriching email addresses. Runs asynchronously: may return `status="PENDING"` — follow the `next_action` field. **Call `skill_find_people` first** to learn the recommended workflow. Costs 1 credit per email address and 10 credits per phone number. Maximum 100 people per request. | Parameter | Type | Required | Allowed values | Default | Description | | ---------- | -------------- | ------------ | -------------- | ------- | ------------------------- | | `requests` | array\ | **required** | — | — | List of people to enrich. | **`requests[]` fields:** | Parameter | Type | Required | Allowed values | Default | Description | | --------------- | -------------- | ------------ | ---------------------------------- | ------- | --------------------------------------------------------------------------- | | `enrich_fields` | array\ | **required** | `contact.emails`, `contact.phones` | — | Fields to enrich: 'contact.emails', 'contact.phones', or both. | | `company_name` | string | optional | — | — | Company name (optional, improves accuracy). | | `custom` | object | optional | — | — | Optional custom key-value pairs returned with results. | | `domain` | string | optional | — | — | Company domain (e.g. 'tamtam.ai'). Required when enriching email addresses. | | `firstname` | string | optional | — | — | Person's first name. | | `lastname` | string | optional | — | — | Person's last name. | | `linkedin_url` | string | optional | — | — | LinkedIn profile URL (optional, improves accuracy). | ## `extract_profile` Extract a person's full LinkedIn profile and create a contact in the Tamtam account. Provide `linkedin_url` for a direct lookup, or any combination of identity hints (`email`, `first_name`, `last_name`, `full_name`, `job_title`, `company_name`, `company_linkedin_id`, `free_text`, `context`) to find the best matching person. Returns the full profile: name, headline, photo, location, experiences, and contact lists. **Call `skill_find_people` first** to learn when to use this vs. search\_people. Costs 1 credit. | Parameter | Type | Required | Allowed values | Default | Description | | --------------------- | ------ | -------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `company_linkedin_id` | string | optional | — | — | LinkedIn numeric ID of the company (most precise company signal). | | `company_name` | string | optional | — | — | Current company name (significantly improves matching accuracy). | | `context` | string | optional | — | — | Free-form supplemental context (e.g. meeting titles, CRM notes) used to disambiguate. Not a resolvable signal on its own. | | `email` | string | optional | — | — | Email address of the person. | | `first_name` | string | optional | — | — | First name. | | `free_text` | string | optional | — | — | Loosely-structured input (e.g. 'find John Doe at Google' or a CSV row). Parsed automatically into the other fields. | | `full_name` | string | optional | — | — | Full name (use when first/last are not separated). | | `job_title` | string | optional | — | — | Current job title (improves disambiguation). | | `last_name` | string | optional | — | — | Last name. | | `linkedin_url` | string | optional | — | — | LinkedIn profile URL (e.g. '[https://www.linkedin.com/in/john-doe](https://www.linkedin.com/in/john-doe)'). When provided, used directly and other fields are ignored. | ## `get_account_mapping` Fetch the account mapping for a target company: its parent company (if any) and its subsidiaries. Use this when the user wants to understand the target's corporate structure, find related entities to approach, or expand the account footprint (e.g. "who owns them?", "what are their subsidiaries?", "are they part of a larger group?"). **Call `skill_research_key_account` first** to learn when to use this vs. the other research tools. | Parameter | Type | Required | Allowed values | Default | Description | | --------------------- | ------ | ------------ | -------------- | ------- | ------------------------------------------------------------- | | `company_linkedin_id` | string | **required** | — | — | LinkedIn numeric ID of the target company (e.g. "104924588"). | ## `get_account_planning` Fetch the account planning for a target company (identified by its LinkedIn ID). Account planning gives a structured strategic view of the target: revenue, organizational structure, geographies, competitive landscape, goals & 3-5Y plan, business challenges & risks, strategic priorities, and news & industry trends. Resolve the LinkedIn ID with `search_companies_by_name` if you do not have it. **Call `skill_research_key_account` first** to learn when to use this vs. the other research tools. | Parameter | Type | Required | Allowed values | Default | Description | | --------------------- | ------ | ------------ | -------------- | ------- | ------------------------------------------------------------- | | `company_linkedin_id` | string | **required** | — | — | LinkedIn numeric ID of the target company (e.g. "104924588"). | ## `get_companies_from_list` Retrieve companies inside a companies list, with custom-criteria column values inlined per company. Paginated. Use `list_companies_lists` first to discover available list IDs. | Parameter | Type | Required | Allowed values | Default | Description | | --------------- | ------- | ------------ | -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- | | `list_id` | string | **required** | — | — | UUID of the companies list to fetch companies from. | | `keep_obsolete` | boolean | optional | — | `false` | If true, returns custom-criteria values that are obsolete (criterion definition changed since computation). Default false. | | `limit` | number | optional | — | — | Max number of companies to return. | | `offset` | number | optional | — | `0` | Pagination offset (default 0). | ## `get_company_job_changes` Fetch recent job changes at a target company (identified by its LinkedIn ID). Returns who joined the company (INCOMING), got promoted internally (PROMOTION), or left and where they went (OUTGOING). For large companies the unfiltered result can be long — narrow with `change_type` when the user's intent is direction-specific ("who joined?" → INCOMING, "any departures?" → OUTGOING, "any internal promotions?" → PROMOTION) and tighten `months_back` when only the latest changes matter. Pair with `get_company_job_postings` for outbound hiring signals and with `search_people` for live org state. Resolve the LinkedIn ID with `search_companies_by_name` if you do not have it. | Parameter | Type | Required | Allowed values | Default | Description | | --------------------- | ------ | ------------ | ----------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `company_linkedin_id` | string | **required** | — | — | LinkedIn numeric ID of the target company (e.g. "104924588"). | | `change_type` | string | optional | `INCOMING`, `PROMOTION`, `OUTGOING` | — | Optional filter. One of "INCOMING" (joiners), "PROMOTION" (internal moves), "OUTGOING" (leavers). Strongly preferred whenever the user's question is direction-specific, and especially for large companies where unfiltered results can be long. Omit only when the user explicitly asks for all activity. | | `limit` | number | optional | ≤ 200 | `50` | Maximum number of job changes to return (default 50, max 200). | | `months_back` | number | optional | 1 – 3 | `2` | Number of calendar months back to include (1 = current + previous month, 2 = current + 2 previous months). Defaults to 2. Max is 3. | ## `get_company_job_postings` Fetch recent job postings for a target company (identified by its LinkedIn ID). Returns postings ordered by posting date (newest first), with title, city, technologies, and a link to the original listing. Use this to surface hiring signals — team growth, tech-stack changes, geographic expansion, new role types — to inform outreach and meeting preparation. Full job descriptions are omitted by default to keep responses compact; set `include_description` to true when you need to inspect the body of the role (e.g. responsibilities, requirements). Resolve the LinkedIn ID with `search_companies_by_name` if you do not have it. | Parameter | Type | Required | Allowed values | Default | Description | | --------------------- | ------- | ------------ | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `company_linkedin_id` | string | **required** | — | — | LinkedIn numeric ID of the target company (e.g. "104924588"). | | `include_description` | boolean | optional | — | `false` | If true, include the full job description text for each posting. Defaults to false to keep responses compact. Set to true when you need the body of the role (responsibilities, requirements, etc.). | | `limit` | number | optional | ≤ 500 | `100` | Maximum number of job postings to return (default 100, max 500). | | `since` | string | optional | — | — | Return job postings posted since this RFC3339 timestamp (e.g. "2026-04-01T00:00:00Z"). Defaults to 30 days ago. Max lookback is 90 days. | ## `get_company_news` Fetch recent news articles for a target company (identified by its LinkedIn ID). Returns articles ordered by publication date (newest first), with key points summarising each article and a per-account relevance assessment (whether the article matters for this customer's sales opportunities, why, and concrete actionable insights). Use this to surface buying signals, fundraising, leadership changes, product launches, or strategic moves to inform outreach and meeting preparation. Resolve the LinkedIn ID with `search_companies_by_name` if you do not have it. | Parameter | Type | Required | Allowed values | Default | Description | | --------------------- | ------- | ------------ | -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `company_linkedin_id` | string | **required** | — | — | LinkedIn numeric ID of the target company (e.g. "104924588"). | | `limit` | number | optional | ≤ 200 | `50` | Maximum number of news items to return (default 50, max 200). | | `relevant_only` | boolean | optional | — | — | If true, only return articles flagged as relevant to this account's sales opportunities. Defaults to true. Set to false to also include articles whose relevance has not been flagged or assessed. | | `since` | string | optional | — | — | Return news published since this RFC3339 timestamp (e.g. "2026-04-01T00:00:00Z"). Defaults to 30 days ago. Max lookback is 90 days. | ## `get_company_past_discussions` Refresh and return a human-readable summary of the seller's past discussions with a target company (identified by its LinkedIn ID): current/past deals, attendee history, engagement highlights, identified pains, objections, next steps, meeting tips, deal health, business case. Triggers an on-demand refresh first when the CRM has newer interactions than the stored summary; idempotent and a no-op when nothing has changed since the last run. Requires the seller's CRM (HubSpot or Salesforce) to be connected; returns an empty summary when no engagements are recorded. Resolve the LinkedIn ID with `search_companies_by_name` if you do not have it. | Parameter | Type | Required | Allowed values | Default | Description | | --------------------- | ------ | ------------ | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `company_linkedin_id` | string | **required** | — | — | LinkedIn numeric ID of the target company (e.g. "104924588"). | | `max_age_days` | number | optional | — | `30` | Force a refresh when the stored summary is older than this many days. Defaults to 30. Pass a smaller value when you specifically need very fresh data; pass a larger value to skip a refresh. | ## `get_company_research_answers` Fetch the answers to the customer's standing research questions for a specific target company. The set of questions themselves is account-wide (configured by the customer); this tool runs/retrieves their results for one given company. Each entry includes the question name, the question text, the run status, and the answers if available. Use this to get concrete, question-by-question insights about a specific company. Different from `get_account_planning` (broad strategic sections) and `get_seller_questions` (info about the customer themselves, not a target). **Call `skill_research_key_account` first** to learn when to use this vs. the other research tools. | Parameter | Type | Required | Allowed values | Default | Description | | --------------------- | ------ | ------------ | -------------- | ------- | ------------------------------------------------------------- | | `company_linkedin_id` | string | **required** | — | — | LinkedIn numeric ID of the target company (e.g. "104924588"). | ## `get_contact_list_contacts` Retrieve all contacts inside a contacts list. Returns each contact's identity, current experience, status, and the timestamp at which the contact was added to the list. Also returns `contact_brief`: AI-answered icebreaker questions per contact (may be empty if research has not yet been triggered from the UI for the contact's company). Use `list_contacts_lists` first to discover available list IDs. | Parameter | Type | Required | Allowed values | Default | Description | | ------------------ | ------ | ------------ | -------------- | ------- | ------------------------------------------------- | | `contacts_list_id` | string | **required** | — | — | UUID of the contacts list to fetch contacts from. | ## `get_contact_past_discussions` Refresh and return a human-readable summary of the seller's past discussions with a single contact (identified by its Tamtam contact UUID): engagement highlights, key topics, stated pains, objections, interests, sentiment, responsiveness, role signals, relationship history, next steps, talking points, and open questions. Triggers an on-demand refresh first when the CRM has newer interactions than the stored summary; idempotent and a no-op when nothing has changed since the last run. Requires the seller's CRM (HubSpot or Salesforce) to be connected; returns an empty summary when no engagements are recorded. Resolve the contact UUID via `get_contact_list_contacts` or `get_pipegen_list_leads` (the `id` field). | Parameter | Type | Required | Allowed values | Default | Description | | -------------- | ------ | ------------ | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `contact_id` | string | **required** | — | — | UUID of the contact (the `id` field returned by `get_contact_list_contacts` or `get_pipegen_list_leads`). | | `max_age_days` | number | optional | — | `30` | Force a refresh when the stored summary is older than this many days. Defaults to 30. Pass a smaller value when you specifically need very fresh data; pass a larger value to skip a refresh. | ## `get_deal_meddic` Fetch the latest MEDDIC qualification snapshot for every CRM deal (HubSpot or Salesforce) linked to a target company (identified by its LinkedIn ID). MEDDIC scores six dimensions (Metrics, Economic Buyer, Decision Criteria, Decision Process, Identify Pain, Champion) on a 0-10 scale, each with bullet points and grounding from CRM engagements. Use this to assess where each open deal stands and what is missing before advancing it. Resolve the LinkedIn ID with `search_companies_by_name` if you do not have it. MEDDIC is generated on-demand inside Tamtam — if a deal has no snapshot yet, ask the user to generate it from the deal in the app first. | Parameter | Type | Required | Allowed values | Default | Description | | --------------------- | ------ | ------------ | -------------- | ------- | ------------------------------------------------------------- | | `company_linkedin_id` | string | **required** | — | — | LinkedIn numeric ID of the target company (e.g. "104924588"). | ## `get_enrichment_results` Retrieve results for an `enrich_people` call that returned `status="PENDING"`. If still PENDING after this call, follow the `next_action` field to continue polling. Enrichment typically completes within 10 minutes. | Parameter | Type | Required | Allowed values | Default | Description | | ------------ | ------ | ------------ | -------------- | ------- | ------------------------------------------- | | `request_id` | string | **required** | — | — | The request\_id returned by enrich\_people. | ## `get_pain_hypothesis` Fetch the pain hypothesis for a target company (identified by its LinkedIn ID). The pain hypothesis gives a fitness score (how well the customer's offering fits the target), a list of actionable challenges the target likely faces (each with supporting facts from public sources and a suggested solution). Use this to assess fit and prepare targeted outreach or meeting talking points for a specific company. **Call `skill_research_key_account` first** to learn when to use this vs. the other research tools. | Parameter | Type | Required | Allowed values | Default | Description | | --------------------- | ------ | ------------ | -------------- | ------- | ------------------------------------------------------------- | | `company_linkedin_id` | string | **required** | — | — | LinkedIn numeric ID of the target company (e.g. "104924588"). | ## `get_pipegen_list_leads` Retrieve all leads inside a prospecting (PipeGen) list. Returns each lead's identity, current experience, status. Also returns `contact_brief`: AI-answered icebreaker questions per lead (may be empty if research has not yet been triggered from the UI for the lead's company). Use `list_pipegen_lists` first to discover available list IDs. | Parameter | Type | Required | Allowed values | Default | Description | | ----------------- | ------ | ------------ | -------------- | ------- | ----------------------------------------------------------- | | `pipegen_list_id` | string | **required** | — | — | UUID of the prospecting (PipeGen) list to fetch leads from. | ## `get_research_results` Wait for and retrieve research results previously started with `research_companies`. Polls internally until all companies are computed or a timeout is reached. Returns per-company status (pending, completed, error) and values. If `all_completed` is false after return, call again to continue waiting. | Parameter | Type | Required | Allowed values | Default | Description | | ---------------------- | -------------- | ------------ | -------------- | ------- | --------------------------------------------------- | | `company_linkedin_ids` | array\ | **required** | — | — | LinkedIn IDs of the companies to check results for. | | `criteria_id` | string | **required** | — | — | The criteria\_id returned by research\_companies. | ## `get_seller_questions` Fetch the seller questions and answers for the current customer account. Seller questions gives a comprehensive understanding of the customer as a company: their products, target market, value proposition, business outcomes, pain points, ROI, competitors, USPs, and competitive gaps. Use this when you need to understand the customer's business in depth to provide relevant and insightful assistance — for example before configurating their account for them or giving strategic advice when the user has not provided enough information. Not needed for tactical assistance (using Tamtam features, finding contact info) where the user's own description in the conversation is enough. *No input parameters.* ## `get_youtube_video_transcript` Fetch a YouTube video's full spoken transcript from its URL (or video ID). Returns the video metadata (title, channel description, length, views, publication date) together with the full transcript text. Use this to brief yourself on a video before a meeting, extract talking points, or feed the transcript into further reasoning (e.g. competitive analysis, executive prep, podcast intelligence). The transcript comes from YouTube's own subtitles when available, with an audio-transcription fallback otherwise; if neither works the tool returns an error and no credits are charged. Cost scales with video length: 1 credit per minute, minimum 10. A 5-min clip costs 10 credits; a 30-min talk costs 30; a 2h podcast costs 120. | Parameter | Type | Required | Allowed values | Default | Description | | --------- | ------ | ------------ | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `url` | string | **required** | — | — | YouTube video URL (e.g. "[https://www.youtube.com/watch?v=dQw4w9WgXcQ](https://www.youtube.com/watch?v=dQw4w9WgXcQ)") or bare video ID. | ## `list_companies_lists` List all existing companies lists. Returns each list's ID, name, tags, assignee, CreatedAt, and UpdatedAt. Results are ordered by UpdatedAt (most recently updated first). Use this to discover available companies lists before performing actions on them. *No input parameters.* ## `list_contacts_lists` List all existing contacts lists. Returns each list's ID, name, tags, and assignee. Use this to discover available contacts lists before performing actions on them. *No input parameters.* ## `list_key_accounts` List the companies the current user has in Key Accounts. Returns each company's LinkedIn ID, name, domain, LinkedIn slug, HQ country, industry, logo URL, employee count, and the timestamp it was last added/updated in Key Accounts. Use this to discover which companies the user has unlocked for deep research. *No input parameters.* ## `list_pipegen_lists` List all existing prospecting (PipeGen) lists. Returns each list's ID, name, owner, createdAt, updatedAt, archived state, visibility status, contact count, and whether it was auto-created. Results are ordered by updatedAt (most recently updated first). Use this to discover available prospecting lists before performing actions on them. *No input parameters.* ## `research_companies` Create a research criteria and compute it on specific companies. Results are computed asynchronously — use `get_research_results` with the returned criteria\_id to poll for completion. Supported criteria types and their required parameters: * 'nbJobOffers': title\_includes (required), title\_excludes, countries, posted\_at\_max\_age\_days, description\_includes, description\_excludes, job\_seniority\_or, employment\_statuses\_or, job\_technology\_slug\_or * 'membersCount': job\_titles\_includes or canonical\_job\_titles\_includes\_ids (one required), job\_titles\_excludes, canonical\_job\_titles\_excludes\_ids, countries, country\_excludes * 'technologiesBool': technologies (required, array of slugs) — checks whether a company uses specific software (any category: CRM, marketing, HR, engineering, etc.) * 'keywordSearchCompanyLinkedin': keywords\_includes (required), keywords\_excludes * 'lookalikeScores': linkedin\_ids or queries (one required) * 'technologies': returns all software and apps used by the company — not just engineering tools but also CRMs, marketing automation, HR platforms, analytics, ERP, collaboration tools, and more (detected from job postings, website, and other signals). No extra params needed * 'fundraising': no extra params needed * 'mau': no extra params needed (monthly website visits) * 'instagramFollowers': no extra params needed * 'peopleGrowthLastYear': no extra params needed Costs 1 credit per company for some criteria types. | Parameter | Type | Required | Allowed values | Default | Description | | ----------------------------------- | -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `company_linkedin_ids` | array\ | **required** | — | — | LinkedIn numeric IDs of the companies to research (e.g. \["104924588"]). | | `criteria_type` | string | **required** | `nbJobOffers`, `membersCount`, `technologiesBool`, `keywordSearchCompanyLinkedin`, `lookalikeScores`, `technologies`, `fundraising`, `mau`, `instagramFollowers`, `peopleGrowthLastYear` | — | Type of research to perform. | | `name` | string | **required** | — | — | Human-readable name for this research. Example: 'Hiring senior engineers'. | | `canonical_job_titles_excludes_ids` | array\ | optional | — | — | For membersCount: canonical job title IDs to exclude. | | `canonical_job_titles_includes_ids` | array\ | optional | — | — | For membersCount: canonical job title IDs to include. | | `countries` | array\ | optional | — | — | For nbJobOffers or membersCount: ISO country codes. Example: \['US', 'FR']. | | `country_excludes` | array\ | optional | — | — | For membersCount: ISO country codes to exclude. | | `description_excludes` | array\ | optional | — | — | For nbJobOffers: keywords that must not appear in the job description. | | `description_includes` | array\ | optional | — | — | For nbJobOffers: keywords that must appear in the job description. | | `employment_statuses_or` | array\ | optional | `full_time`, `part_time`, `temporary`, `internship`, `contract`, `freelance`, `co_founder`, `apprenticeship`, `seasonal`, `volunteer` | — | For nbJobOffers: employment types. Values: 'full\_time', 'part\_time', 'temporary', 'internship', 'contract', 'freelance', 'co\_founder', 'apprenticeship', 'seasonal', 'volunteer'. | | `job_seniority_or` | array\ | optional | `c_level`, `staff`, `senior`, `mid_level`, `junior` | — | For nbJobOffers: seniority levels. Values: 'c\_level', 'staff', 'senior', 'mid\_level', 'junior'. | | `job_technology_slug_or` | array\ | optional | — | — | For nbJobOffers: technology slugs to filter by (e.g. 'react', 'kubernetes'). | | `job_titles_excludes` | array\ | optional | — | — | For membersCount: job title keywords to exclude. | | `job_titles_includes` | array\ | optional | — | — | For membersCount: job title keywords to include. | | `keywords_excludes` | array\ | optional | — | — | For keywordSearchCompanyLinkedin: keywords that must not appear. | | `keywords_includes` | array\ | optional | — | — | For keywordSearchCompanyLinkedin: keywords that must appear in the company LinkedIn description. | | `linkedin_ids` | array\ | optional | — | — | For lookalikeScores: LinkedIn numeric IDs of reference companies to compare against (e.g. \["104924588"]). | | `posted_at_max_age_days` | number | optional | — | `365` | For nbJobOffers: maximum age of job postings in days. Default: 365. | | `queries` | array\ | optional | — | — | For lookalikeScores: text queries describing the ideal company profile. | | `technologies` | array\ | optional | — | — | For technologiesBool: technology slugs to check. Example: \['react', 'kubernetes']. | | `title_excludes` | array\ | optional | — | — | For nbJobOffers: job title keywords to exclude. | | `title_includes` | array\ | optional | — | — | For nbJobOffers: job title keywords to include. Example: \['engineer', 'developer']. | ## `search_canonical_job_titles` Search for canonical job titles by keyword. Returns matching job title IDs and English names. Use this to find valid canonical job title IDs for search\_people's canonical\_job\_titles\_includes\_ids / canonical\_job\_titles\_excludes\_ids parameters. **Call `skill_find_people` first** to learn the recommended workflow. | Parameter | Type | Required | Allowed values | Default | Description | | --------- | ------ | ------------ | -------------- | ------- | --------------------------------------------------------------------------------------- | | `query` | string | **required** | — | — | The job title keyword to search for (e.g. 'CTO', 'Head of Sales', 'Software Engineer'). | ## `search_companies_by_filters` Search for companies using advanced filters (keywords, industry, country, company size, founded year, employee count, etc.). Returns matching companies with their LinkedIn ID, name, and details. **Call `skill_find_companies` first** to learn how to choose between this, lookalikes, and job\_postings search. Default filters from account settings are automatically applied when you don't specify a filter explicitly. The response includes the true `total_count`, `has_more`, and `next_offset`. PAGINATION — DO NOT STOP AT THE FIRST PAGE when the user wants an exhaustive list: re-call with the SAME filters and `offset` set to the previous response's `next_offset` until `has_more` is false (bounded to 10000 results total). | Parameter | Type | Required | Allowed values | Default | Description | | -------------------- | -------------- | -------- | ------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `company_size` | array\ | optional | `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+` | — | Employee size ranges. Values: '1-10', '11-50', '51-200', '201-500', '501-1000', '1001-5000', '5001-10000', '10001+'. | | `countries` | array\ | optional | — | — | ISO 3166-1 alpha-2 country codes for company HQ location. Example: \['US', 'FR', 'DE']. | | `excluded_keywords` | array\ | optional | — | — | Keywords to exclude from search results. Example: \['consulting']. | | `hq_cities` | array\ | optional | — | — | HQ city names. Example: \['Paris', 'New York']. | | `hq_states` | array\ | optional | — | — | HQ state or region names. Example: \['California', 'Île-de-France']. | | `industries_exclude` | array\ | optional | — | — | LinkedIn industry names to exclude. Example: \['Staffing and Recruiting']. | | `industries_include` | array\ | optional | — | — | LinkedIn industry names to include. Example: \['Computer Software', 'Financial Services']. | | `keywords` | array\ | optional | — | — | Keywords to search for in the company profile (name, description, specialties). Example: \['AI', 'machine learning']. | | `keywords_logic` | string | optional | `OR`, `AND` | `OR` | How to combine keywords: 'OR' matches any keyword (default), 'AND' requires all keywords. | | `limit` | number | optional | ≤ 5000 | `100` | Maximum number of results to return per page (default 100, max 5000). Use a high limit (e.g. 5000) when the user wants exhaustive results. | | `max_employees` | number | optional | — | — | Maximum number of employees on LinkedIn. Example: 1000. | | `max_founded_year` | number | optional | — | — | Maximum year the company was founded. Example: 2023. | | `min_employees` | number | optional | — | — | Minimum number of employees on LinkedIn. Example: 50. | | `min_founded_year` | number | optional | — | — | Minimum year the company was founded. Example: 2010. | | `offset` | number | optional | — | `0` | Number of results to skip, for pagination (default 0). To sweep ALL matches: keep the same filters and re-call with offset set to the previous response's next\_offset until has\_more is false. Offset paging is bounded to 10000 results total. | ## `search_companies_by_job_postings` Search for companies based on their job postings and hiring activity. Filter by job titles, technologies, funding stage, location, and company size. Returns companies that are actively hiring for matching roles. Returned companies are revealed for the account; revealing only unblurs the company data and does NOT add them to Key Accounts. Costs 1 AI credit per newly-revealed company; companies the account already revealed are not re-charged. Use `limit` to bound how many companies are returned and revealed per page (default 500, max 500). The response includes a `pagination` block with `has_more` and `next_offset`. PAGINATION — DO NOT STOP AT THE FIRST PAGE when the user wants an exhaustive list: re-call with the SAME filters and `offset` set to the previous response's `pagination.next_offset` until `pagination.has_more` is false (each page reveals its companies and costs credits). **Call `skill_find_companies` first** to learn when to use job\_postings search vs. other tools. Default filters from account settings are automatically applied when you don't specify a filter explicitly. | Parameter | Type | Required | Allowed values | Default | Description | | -------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `company_countries` | array\ | optional | — | — | ISO 3166-1 alpha-2 country codes for company HQ location. Example: \['US', 'FR', 'DE']. | | `company_countries_exclude` | array\ | optional | — | — | ISO 3166-1 alpha-2 country codes to exclude for company HQ. | | `company_description_contains` | array\ | optional | — | — | Keywords that must ALL appear in the company description (AND logic, every keyword must match). For match-ANY semantics use company\_description\_pattern\_or instead. Example: \['fintech', 'payments']. | | `company_description_excludes` | array\ | optional | — | — | Keywords to exclude from company descriptions. Example: \['consulting']. | | `company_description_pattern_or` | array\ | optional | — | — | Keywords where ANY match is enough in the company description (OR logic, at least one keyword must match). For match-ALL semantics use company\_description\_contains instead. Example: \['ecommerce', 'online store', 'tienda online']. | | `company_tech_slugs_and` | array\ | optional | — | — | Technology slugs the company must ALL use, AND logic (every slug required). Use only when the full stack must be present. Example: \['react', 'typescript']. | | `company_tech_slugs_or` | array\ | optional | — | — | Technology slugs the company uses, OR logic (match if the company uses ANY of these). Prefer this for most tech searches. Example: \['prestashop', 'woocommerce', 'magento']. | | `company_type` | string | optional | `recruiting_agency`, `direct_employer`, `all` | `all` | Filter by company type: 'recruiting\_agency', 'direct\_employer', or 'all' (default). Use 'direct\_employer' to exclude recruiting agencies. | | `funding_stages` | array\ | optional | `angel`, `convertible_note`, `debt_financing`, `equity_crowdfunding`, `other`, `private_equity`, `seed`, `series_a`, `series_b`, `series_c`, `series_d`, `series_e`, `series_f`, `series_g`, `series_h`, `venture_round_not_specified`, `series_i`, `series_j`, `undisclosed`, `series_unknown`, `pre_seed`, `post_ipo_secondary`, `post_ipo_equity`, `post_ipo_debt`, `non_equity_assistance`, `late_vc`, `initial_coin_offering`, `growth_equity_vc`, `grant`, `early_vc`, `corporate_round`, `secondary_market`, `product_crowdfunding` | — | Funding stages to filter by. Example: \['seed', 'series\_a', 'series\_b']. Values: angel, convertible\_note, debt\_financing, equity\_crowdfunding, other, private\_equity, seed, series\_a, series\_b, series\_c, series\_d, series\_e, series\_f, series\_g, series\_h, venture\_round\_not\_specified, series\_i, series\_j, undisclosed, series\_unknown, pre\_seed, post\_ipo\_secondary, post\_ipo\_equity, post\_ipo\_debt, non\_equity\_assistance, late\_vc, initial\_coin\_offering, growth\_equity\_vc, grant, early\_vc, corporate\_round, secondary\_market, product\_crowdfunding. | | `industry_exclude_ids` | array\ | optional | — | — | Industry UUIDs to exclude. Use search\_industries to find valid IDs. | | `industry_ids` | array\ | optional | — | — | Industry UUIDs to filter by. Use search\_industries to find valid IDs. | | `job_countries` | array\ | optional | — | — | ISO 3166-1 alpha-2 country codes for job location (can differ from company HQ). Example: \['US', 'FR']. | | `job_description_contains` | array\ | optional | — | — | Keywords that must appear in the job description. Example: \['remote', 'senior']. | | `job_description_excludes` | array\ | optional | — | — | Keywords to exclude from job descriptions. Example: \['clearance required']. | | `job_seniority` | array\ | optional | — | — | Seniority levels. Example: \['senior', 'lead', 'manager']. | | `job_tech_slugs` | array\ | optional | — | — | Technology slugs mentioned in job postings (lowercase). Example: \['python', 'kubernetes', 'react']. | | `job_titles` | array\ | optional | — | — | Job titles to search for. Example: \['Data Engineer', 'Machine Learning Engineer']. | | `job_titles_exclude` | array\ | optional | — | — | Job titles to exclude from results. Example: \['Intern', 'Trainee']. | | `limit` | number | optional | ≤ 500 | `500` | Maximum number of companies to return and reveal per page (default 500, max 500). Each newly-revealed company costs 1 credit. | | `max_employees` | number | optional | — | — | Maximum number of employees. Example: 1000. | | `max_funding_usd` | number | optional | — | — | Maximum total funding in USD. Example: 50000000 for under \$50M. | | `max_revenue_usd` | number | optional | — | — | Maximum annual revenue in USD. | | `min_employees` | number | optional | — | — | Minimum number of employees. Example: 50. | | `min_funding_usd` | number | optional | — | — | Minimum total funding in USD. Example: 1000000 for \$1M+. | | `min_revenue_usd` | number | optional | — | — | Minimum annual revenue in USD. | | `offset` | number | optional | — | `0` | Number of results to skip, for pagination (default 0). To sweep ALL matches: keep the same filters and re-call with offset set to the previous response's pagination.next\_offset until pagination.has\_more is false. Should be a multiple of limit. Each page reveals its companies (costs credits). | | `posted_at_max_age_days` | number | optional | — | `90` | Only include job postings from the last N days (default 90). Example: 30 for last month only. | | `remote` | boolean | optional | — | — | Filter for remote positions only. | ## `search_companies_by_lookalikes` Find companies similar to given reference companies. Uses AI-powered similarity search. You must provide at least one company\_linkedin\_id. **Call `skill_find_companies` first** to learn when to use lookalikes vs. other search tools. Costs 1 credit per call. Default filters from the user / account settings (HQ countries, company sizes, employee-count range) are automatically applied when you don't specify the corresponding filter explicitly. Passing an explicit value (including an empty array) overrides the default. IMPORTANT: When multiple company\_linkedin\_ids are passed in the same call, they are merged into ONE combined similarity fingerprint (results are similar to ALL seeds at once, not similar to ANY of them). If the user names several distinct seed companies and wants companies similar to any of them, call this tool once per seed and union the results — do NOT batch them into one call. Only batch multiple IDs when the user explicitly asks for companies similar to the seeds as a group. When fanning out across multiple seeds, dedupe the union by linkedin\_id; an overlap across seeds is a strong-fit signal worth surfacing. | Parameter | Type | Required | Allowed values | Default | Description | | ---------------------- | -------------- | -------- | ------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `company_linkedin_ids` | array\ | optional | — | — | LinkedIn IDs of reference companies to find lookalikes for. Use search\_companies\_by\_name to find LinkedIn IDs first. Pass ONE seed per call when the user lists multiple distinct seeds; pass multiple only when the user explicitly wants companies similar to the seeds as a group (they will be merged into a combined fingerprint). | | `company_size` | array\ | optional | `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+` | — | Employee size ranges. Values: '1-10', '11-50', '51-200', '201-500', '501-1000', '1001-5000', '5001-10000', '10001+'. | | `countries` | array\ | optional | — | — | ISO 3166-1 alpha-2 country codes to filter by HQ location. Example: \['US', 'FR']. | | `limit` | number | optional | ≤ 500 | `100` | Maximum number of results (default 100, max 500). Higher limits consume the same 1 credit. | | `max_employees` | number | optional | — | — | Maximum number of employees on LinkedIn. | | `min_employees` | number | optional | — | — | Minimum number of employees on LinkedIn. | ## `search_companies_by_lookalikes_any` Find companies similar to ANY of several reference companies (OR semantics). Uses AI-powered similarity search. You must provide at least one company\_linkedin\_id. **Call `skill_find_companies` first** to learn when to use lookalikes vs. other search tools. Costs 1 credit per call. Unlike `search_companies_by_lookalikes` — which merges all seeds into ONE combined fingerprint (results similar to ALL seeds at once) — this tool runs a separate lookalike search per seed and unions the results. Use it when the user names several distinct seed companies and wants companies similar to ANY of them. Each result reports `score` (the highest score the company reached across the seeds it matched) and `match_count` (how many of the input seeds it qualified as a lookalike for). Results are ranked by `match_count` first, then by `score`: a company similar to several seeds is a stronger fit. Default filters from the user / account settings (HQ countries, company sizes, employee-count range) are automatically applied when you don't specify the corresponding filter explicitly. Passing an explicit value (including an empty array) overrides the default. | Parameter | Type | Required | Allowed values | Default | Description | | ---------------------- | -------------- | -------- | ------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `company_linkedin_ids` | array\ | optional | — | — | LinkedIn IDs of the reference companies to find lookalikes for (OR). Each is searched independently and the results are unioned. Use search\_companies\_by\_name to find LinkedIn IDs first. | | `company_size` | array\ | optional | `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+` | — | Employee size ranges. Values: '1-10', '11-50', '51-200', '201-500', '501-1000', '1001-5000', '5001-10000', '10001+'. | | `countries` | array\ | optional | — | — | ISO 3166-1 alpha-2 country codes to filter by HQ location. Example: \['US', 'FR']. | | `limit` | number | optional | ≤ 500 | `100` | Maximum number of results (default 100, max 500). Higher limits consume the same 1 credit. | | `max_employees` | number | optional | — | — | Maximum number of employees on LinkedIn. | | `min_employees` | number | optional | — | — | Minimum number of employees on LinkedIn. | ## `search_companies_by_name` Search for companies by name. Returns matching companies with their LinkedIn ID, name, domain, and other details. Use this to find a specific company's LinkedIn ID or to resolve company names for other tools. **Call `skill_find_companies` first** to learn the recommended workflows. | Parameter | Type | Required | Allowed values | Default | Description | | --------- | ------ | ------------ | -------------- | ------- | ----------------------------------------------- | | `query` | string | **required** | — | — | The company name (or part of it) to search for. | ## `search_industries` Search for industries by keyword. Returns matching industry IDs, names, and hierarchy paths. Use this to find valid industry IDs for search\_people and search\_companies\_by\_filters / search\_companies\_by\_job\_postings. **Call `skill_find_people` or `skill_find_companies` first** to learn the recommended workflows. | Parameter | Type | Required | Allowed values | Default | Description | | --------- | ------ | ------------ | -------------- | ------- | --------------------------------------------------------------------- | | `query` | string | **required** | — | — | The keyword to search for (e.g. 'fintech', 'software', 'healthcare'). | ## `search_people` Search for people — contacts, leads, prospects, or decision-makers — using advanced filters (job titles, seniority, location, company, industry, and more). Returns up to 25 profiles per page with LinkedIn IDs, job titles, companies, and locations. The response also includes `total_count` (total matches available across all pages) on the first page. **Call `skill_find_people` first** to learn how to use this tool effectively. **Recommended:** use the `prompt` parameter with a natural-language query (e.g. 'CTOs at fintech startups in France') — job titles, seniority, industries, countries, and other filters are automatically extracted from it. Alternatively, use the structured filter fields for precise control when you already have exact IDs. To find valid IDs for structured filters, use `search_canonical_job_titles` and `search_industries`. Pass `next_cursor` from a previous response to fetch the next page (re-call this same tool). Costs 1 credit per profile returned. PAGINATION DEFAULT — DO NOT STOP AT 25: Most people-search requests like 'find software engineers in healthcare startups in Paris' or 'find marketing leaders at fintech companies' are implicitly asking for a comprehensive list, NOT just 25 results. Stopping at the first page silently is a poor outcome. After the first page, if `has_more` is true, follow this decision rule: 1. If the user's request clearly implies wanting many/all/exhaustive results (broad discovery, building a list, prospecting, 'find me X', 'who are the X', 'extract contacts', persona-based searches): keep paginating by re-calling `search_people` with the returned `next_cursor` until `has_more` is false OR you have collected a reasonable working set (e.g. \~100-200 results), then ask the user if they want to continue. Mention the credit cost. 2. If the user explicitly requested a specific small number (e.g. 'find me 10 CTOs', 'give me a few examples'): respect that number and stop. 3. If intent is ambiguous regarding scale: after the first page, proactively ask the user how many results they want (e.g. 'I found a first batch of 25 out of \ total matches. Do you want me to load more? Each additional page of 25 costs 25 credits.'). Do not silently stop. ALWAYS surface to the user the `total_count` returned in the response, so they know how many matches exist before deciding to paginate. | Parameter | Type | Required | Allowed values | Default | Description | | ----------------------------------- | -------------- | -------- | ------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `canonical_job_titles_excludes_ids` | array\ | optional | — | — | Canonical LinkedIn job title UUIDs to exclude. | | `canonical_job_titles_includes_ids` | array\ | optional | — | — | Canonical LinkedIn job title UUIDs to include. | | `company_headcounts` | array\ | optional | `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`, `I` | — | Company headcount band codes: A=self-employed, B=1-10, C=11-50, D=51-200, E=201-500, F=501-1000, G=1001-5000, H=5001-10000, I=10001+. | | `company_hq_countries` | array\ | optional | — | — | ISO 3166-1 alpha-2 country codes of the company's headquarters (e.g. \['FR','US']). | | `company_linkedin_ids` | array\ | optional | — | — | LinkedIn company IDs to filter by. | | `countries` | array\ | optional | — | — | ISO 3166-1 alpha-2 country codes of the person's location (e.g. \['FR','US']). | | `first_name` | string | optional | — | — | Filter by person's first name. | | `industry_excludes_ids` | array\ | optional | — | — | Industry UUIDs to exclude from the search. | | `industry_includes_ids` | array\ | optional | — | — | Industry UUIDs to include in the search. | | `job_titles_excludes` | array\ | optional | — | — | Job titles to exclude. | | `job_titles_includes` | array\ | optional | — | — | Job titles to include (e.g. \['Head of Sales']). | | `last_name` | string | optional | — | — | Filter by person's last name. | | `next_cursor` | string | optional | — | — | Opaque pagination token returned by the previous response's next\_cursor. Pass it back unchanged to fetch the next page. Invalid or expired cursors return an error inviting a fresh search. | | `prompt` | string | optional | — | — | Natural-language search query. Mutually exclusive with structured filters. | | `recently_changed_jobs` | boolean | optional | — | — | Only include people who recently changed jobs. | ## `skill_find_companies` IMPORTANT: Call this BEFORE any company search or discovery task. Returns expert knowledge on which company search tools to use, how to combine them, and how to get the best results. No parameters needed. *No input parameters.* ## `skill_find_people` IMPORTANT: Call this BEFORE any task involving finding people, contacts, leads, or prospects — whether by search filters, name, LinkedIn URL, or email. Returns expert knowledge on which people-related tools to use, how to combine them, and how to interpret filters. No parameters needed. *No input parameters.* ## `skill_research_key_account` IMPORTANT: Call this BEFORE researching a specific target company in Key Accounts — their strategy, pains, fit, standing research answers, corporate structure, or recent news and buying signals. Returns expert knowledge on which research tools to use, the Key Accounts pre-requisite, and how to handle the asynchronous nature of research outputs. No parameters needed. *No input parameters.*