MCP tools

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.

​

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. requests[] fields:

​

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.

​

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.

​

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.

​

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.

​

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.

​

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.

​

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.

​

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.

​

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.

​

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.

​

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).

​

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.

​

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.

​

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.

​

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.

​

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.

​

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.

​

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.

​

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.

​

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).

​

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.

​

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.

​

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.

​

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.

​

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.

​

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_count> 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.

​

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.