add_profiles_to_list
ChatGPTAdd one or many profiles to a list. profileType must match the ids passed. Free — no credit charge. Sync to SearchAPI is asynchronous via Inngest. The tool resolves the list's sharing state internally — the caller does not pass isShared.
agent_signal_hits
ChatGPTFetch signal hits (matching events / intent surges) for a configured signal agent in a single category. Internally validates the agent, then queries the hits index scoped to that agent. Date-range filtering is not supported — use size to scope freshness. Free — no credit charge.
ai_search
ChatGPTNatural-language search across Firmable companies and people. Pass a free-text query like "companies in Melbourne" or "people at Atlassian in marketing" and Firmable parses it into filters server-side. Use this as the FIRST tool whenever the user asks to find / list / search / show records — before falling back to get_company, get_person, list_saved_searches, or list_lists. IMPORTANT: if the user mentions any country, region, city, or state, you MUST infer the country and pass it via the country parameter (e.g. "in San Francisco" → country: "US", "in Tokyo" → country: "JP", "in Auckland" → country: "NZ"). Default country is AU when no geographic hint is given. Free — no credit charge, no approval needed.
bulk_get_companies
ChatGPTFetch up to 100 company profiles in a single call. Accepts any mix of ids, domains, linkedinUrns. Results are returned in input order; missing records appear as null. CHARGES UP TO N api_enrichment CREDITS where N = items.length (profiles already charged previously are deduped and free).
bulk_get_people
ChatGPTFetch up to 100 person profiles in a single call. Accepts any mix of ids, linkedinUrns, and emails. Results are returned in input order; missing records appear as null. CHARGES UP TO N api_enrichment CREDITS where N = items.length (profiles already charged previously are deduped and free).
bulk_push_list_to_crm
ChatGPTPush the ENTIRE contents of a saved list to the workspace's connected CRM in one call (selection-mode list-all; the server fans out page-by-page via Inngest). The CRM is auto-detected — not an input. CHARGES UP TO N crm_push CREDITS where N is the list's companyCount or peopleCount depending on category. Fails with code="not_connected" if no CRM is connected, code="list_not_found" if the list id is unknown.
bulk_reveal_person_emails
ChatGPTReveal work and personal emails for up to 100 people in one call. Not credit-gated. Each result carries { id, emails: { work, personal } }; missing records appear as null.
bulk_reveal_person_phones
ChatGPTReveal mobile phone numbers for up to 100 people in one call. CHARGES N people_phone_viewed CREDITS where N = ids.length, atomic. Whole batch is rejected (code="no_credits") if the org does not have enough credits for every record — no partial charging.
copy_profiles_between_lists
ChatGPTCopy profiles into a destination list (source is unchanged — same effect as add_profiles_to_list with explicit source for traceability). Free — no credit charge. The tool resolves the destination list's sharing state internally.
create_list
ChatGPTCreate a new list. Lists are mixed-type — a single list can hold both companies and people; profileType is specified per add/remove call. Free — no credit charge.
filter_search
ChatGPTPrecise, filter-driven search across Firmable companies and people — the structured counterpart to ai_search. Use this when the user specifies explicit criteria (industry, location, company size, revenue, seniority, contact availability, saved lists, CRM owner, etc.) and you want exact control over the filters rather than letting the backend infer them from free text. Filters use the SAME identifiers the Firmable app uses. For any identifier whose values are option ids (industry, location, technographics, revenue, department, seniority, company_size bands, country, saved lists, CRM owner/agent, …), call get_filter_options FIRST to resolve human terms into ids, then pass them here. Free-text filters (keywords, position, skills, services, products, company/person name) accept a "contains:<term>" key for substring matching without a lookup. Free — no credit charge, no approval needed.
find_similar_companies
ChatGPTReturn lookalike companies for a given company id. Use for ABM (account-based marketing) expansion — feed a known target, get companies with similar size / industry / region.
find_similar_people
ChatGPTReturn persona matches for a given person id — people with similar role / seniority / department at other companies. Useful for building outbound lists when you have one known champion.
get_company
ChatGPTFetch a single company profile by id, domain, or linkedinUrn. CHARGES UP TO 1 api_enrichment CREDIT (free on repeat for the same profile).
get_filter_options
ChatGPTResolve human filter terms into the option ids that filter_search expects. Many Firmable filters use opaque ids (industry codes, location codes, revenue/seniority/department bands, saved list ids, CRM owner ids) that you cannot guess — call this first to look them up. Static dropdowns (country, revenue, seniority, company_type, company_size, …) return a fixed, built-in option list (searchTerm is ignored, and there is no live API lookup — e.g. country always returns the supported country codes); searchable filters (location, keywords, position, skills, products, services, company/person name, saved lists, CRM owner) accept a searchTerm; hierarchical filters (industry, technographics) accept a searchTerm or a levelOneId to drill into level-2 children. The returned records are keyed {optionId: label} — pass those keys straight into filter_search filters unchanged. For location filters (location, people_location, hq_location) the keys are already composite type:value:country strings (e.g. "lga:Sydney, NSW, AU:AU", "state:VIC:AU") — use them exactly as returned; do not reformat or strip them. Free — no credit charge.
get_list
ChatGPTFetch metadata + profile records inside a single list. Requires category ("company" or "people") — a mixed list must be queried twice. Free — no credit charge.
get_person
ChatGPTFetch a single person profile by id, linkedinUrn, or email. CHARGES UP TO 1 api_enrichment CREDIT (free on repeat for the same profile). Emails come back unmasked in emails.work.
get_signal_agent
ChatGPTReturn a single signal agent's full configuration: companySignals, peopleSignals, intentTopics, intentTargets, companySignalTargets, peopleSignalTargets, listIds, isEnabled. Use this to describe what an agent monitors before fetching its hits. Free — no credit charge.
get_workflow_guide
ChatGPTReturn the workflow guide for the Firmable agents MCP server. Call this first before any other tool to learn which tool to use, how to chain them (get_ → find_similar_ → bulk_ → reveal_), and what identifiers each accepts. Without this guide, tool calls often miss the intended chain or pass wrong identifier types. Optional: pass topic to fetch only one section.
list_lists
ChatGPTReturn all lists in the workspace, bucketed into shared and private. The bucket determines isShared (records.shared[id] => isShared:true, records.private[id] => isShared:false). Free — no credit charge. Call this first before any list mutation so you know each list's id and isShared.
list_saved_searches
ChatGPTReturn saved searches for the workspace, keyed by sid. Each record carries name, category ("company" or "people"), filters, operators, excluded values, last_modified_time, and isICPSearch. Use this to surface what the user has previously saved so the LLM can describe / re-run / build on those searches. Returns the 50 most recently modified saved searches (sorted by last_modified_time desc) — workspaces with more than 50 only see the most recent slice, same as the web app. Free — no credit charge.
list_signal_agents
ChatGPTReturn all user-configured signal agents in the workspace, keyed by id. Each agent monitors a chosen set of company/people signal types and intent topics over a chosen set of lists. Free — no credit charge. Call this first to discover an agentId before get_signal_agent or agent_signal_hits.
move_profiles_between_lists
ChatGPTMove profiles from one list to another. Atomic on the server — add to destination and remove from source happen together. Free — no credit charge. The tool resolves both lists' sharing state internally in a single lookup.
push_to_crm
ChatGPTPush 1–500 profiles to the workspace's connected CRM (HubSpot / Salesforce / Pipedrive / MS Dynamics 365 Sales / JobAdder — auto-detected). The CRM is not an input. CHARGES UP TO N crm_push CREDITS where N = profileIds.length (already-pushed profiles may be deduped downstream). Fails with code="not_connected" if no CRM is connected.
remove_profiles_from_list
ChatGPTRemove one or many profiles from a list. Free — no credit charge. Sync to SearchAPI is asynchronous via Inngest. The tool resolves the list's sharing state internally — the caller does not pass isShared.
rename_list
ChatGPTRename an existing list. Free — no credit charge. The tool resolves the list's sharing state internally — the caller does not pass isShared.
reveal_person_email
ChatGPTReveal the work and personal emails for a single person. Not credit-gated — emails are included in the profile payload. Returns { emails: { work: [...], personal: [...] } } plus minimal identifying fields.
reveal_person_phone
ChatGPTReveal mobile phone numbers for a single person. CHARGES 1 people_phone_viewed CREDIT per call (first view per profile actually bills; subsequent views of the same profile are deduped by Inngest idempotency). Fails with code="no_credits" if the org is out of credits.
