Firmable

Precise, 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.

filter_search

Return 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_companies

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

find_similar_people

Fetch a single company profile by id, domain, or linkedinUrn. Uses up to 1 credit (free on repeat for the same profile).

get_company

Resolve 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, tech_intelligence) accept a searchTerm; hierarchical filters (industry) accept a searchTerm or a levelOneId to drill into level-2 children. An industry search returns the closest matches, each with its top-level group (l1_id, l1_text); when the word the user gave names a whole sector ("healthcare", "finance", "IT"), call again with the levelOneId of that group and use all its 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:AU") — use them exactly as returned; do not reformat or strip them. tech_intelligence (technology a company uses, e.g. AWS) may not be available; when it fails, tell the user searching by technology is not available and stop — never substitute ai_search or other filters. Free — no credit charge.

get_filter_options

Fetch metadata + profile records inside a single list. Requires category ("company" or "people") — a mixed list must be queried twice. Free — no credit charge.

get_list

Fetch 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_person

Return 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_signal_agent

Return 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. Pass topic "all" for the full guide, or one section.

get_workflow_guide

Return one page of lists in the workspace, bucketed into shared and private. Use search to find a list by name; page with from/size when total > returned. Free — no credit charge. Call this first to get a list's id before changing it.

list_lists

Return 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_saved_searches

Return one page of user-configured signal agents in the workspace, enabled first then newest, each with its id. Use search to find an agent by name; page with from/size when total > returned. 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.

list_signal_agents

Move profiles from one list to another. Atomic — add to destination and remove from source happen together. Free — no credit charge.

move_profiles_between_lists

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

push_to_crm

Remove one or many profiles from a list. Free — no credit charge. Changes may take a moment to appear in search.

remove_profiles_from_list

Rename an existing list. Free — no credit charge.

rename_list

Reveal 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_email

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

reveal_person_phone