MCP tool reference

This is the full reference for the tools the Trace MCP server exposes. Before reading it, see the MCP overview for the connection URL, OAuth sign-in, and metering.

A few things that apply across the board:

• Every plan. All tools are available on every plan — there is no per-tool plan gate. Plans differ only by the number of credits they grant per month; what you can do is limited by your credit balance, not your plan.
• Metering. Tools that return company records charge 1 credit per net-new company on the mcp channel (see Credits). Tools that return catalog entries, list metadata, or field registries don’t charge per record.
• Read vs. write. “Read-only” tools never change your data. Lists tools that create, edit, or delete are marked accordingly — your MCP client may prompt for consent before running a write or destructive tool.
• Errors. Tools return a structured {error, error_code} object instead of raising. Common codes: invalid_input, not_found, unauthorized, credit_exhausted, timeout.
• Names or domains. Every company argument accepts a company name or a bare domain (Stripe or stripe.com). A name resolves to its canonical company; an ambiguous name returns a candidates list (not billed) so you can retry with a domain or a candidate.

Companies

company_profile

Start here for any company question. Look up one or more companies by name or domain (up to 5) in a single call.

Argument	Type	Required	Notes
inputs	list of strings	yes	Up to 5 company names or domains.

Returns: an entry per input, keyed by the input. Each resolved entry has the company name, all known domains, firmographics (industry, employee range, country, founded year), section counts (tech_count, partnership_count, jobs_count), and a small sample of tech and partners (jobs are count-only here). A profile may also include related_companies — corporate ownership context (parent / subsidiary / acquirer / acquisition / division), omitted when none is known. For the full data behind a count, call company_detail with the matching section. Unknown inputs come back as per-input error objects; ambiguous names come back as a candidates list (not billed). Read-only. Metered per resolved company.

company_detail

The full data behind one company_profile section, for a single company.

Argument	Type	Required	Notes
company	string	yes	Company name or domain.
section	"tech" | "jobs" | "partners"	yes	Which section to fetch.
offset	integer	no	Pagination offset for jobs / partners, default 0.
limit	integer	no	Max rows for partners (default 20, max 100). Ignored by tech and jobs.

Sections:

• tech — the complete detected technology stack, ordered by global adoption, in one call (no pagination).
• jobs — paginated job postings, up to 150 per call. Only page further when has_more is true.
• partners — paginated partner companies with first/last seen dates.

Returns: the section’s rows plus the exact total (total_technologies / total_jobs / total_partnerships) and has_more where paginated. Read-only. Metered: tech and jobs charge the one company; partners charges per partner company returned.

find_companies

Discover companies matching a combination of criteria — the compound questions the single-purpose tools can’t answer: “uses both X and Y”, “X but not Y”, “customers of X also using Y”, “which of these domains use Z”.

Argument	Type	Required	Notes
definition	dict	yes	A boolean filter tree (or {"query": <tree>} envelope) over filter leaves — the same shape lists_filter_fields describes and the Lists tools use.
sample_size	integer	no	Sample rows to return, default 10, max 25.

A leaf’s value list is OR (technology in ["a","b"] matches a or b); to require multiple technologies together, give each its own leaf under an and group. Negate with the not_in operator, or a "not": true group nested under an and. Every definition needs at least one positive (bounding) leaf — a pure-negation tree (“companies using neither X nor Y”) is rejected, since it would match almost the whole corpus.

Returns: a match count (free signal) plus a small sample of companies (billed), and a suggested_list envelope you can pass straight to lists_edit (action create) to save the result as a live list. Read-only. Metered only on the sample returned. Call lists_filter_fields for the exact fields and operators; resolve company names to domains with company_profile first.

company_uses_technology

Yes/no: does one company use a specific technology or vendor? Cheaper than pulling the whole stack with company_detail and scanning it.

Argument	Type	Required	Notes
company	string	yes	Company name or domain.
technology	string	yes	Technology name, exact tech key, or vendor name — fuzzy-resolved.

Returns: uses (boolean), evidence (detection stats, or null when not used), and a matched block showing which technology or vendor the query resolved to — check it before trusting the verdict. An unresolvable technology returns error_code: not_found. Read-only. Metered (1 company).

Technologies and vendors

technology_catalog

Search the catalog of technologies and vendors Trace can detect — “what analytics tools exist?”. It does not tell you which companies use them; for that use find_companies_using_technology.

Argument	Type	Required	Notes
query	string	yes	e.g. CRM, analytics, Stripe
limit	integer	no	Default 20, max 50.
offset	integer	no	Default 0.

Returns: paginated catalog entries, each with tech_key, display_name, and vendor_name, plus total, count, and has_more. Read-only. Not metered per record (catalog search, not company records).

find_companies_using_technology

Find the companies that use one specific technology or vendor. Accepts a technology name, an exact tech key, or a vendor name. For compound queries (“uses X and Y”) use find_companies instead.

Argument	Type	Required	Notes
query	string	yes	Technology name, tech key, or vendor name.
limit	integer	no	Default 20, max 50.
offset	integer	no	Default 0.

Returns: a matched block resolving the query to a stable identifier (tech_key for a technology, vendor_slug for a vendor), plus total_companies and a page of companies (name, primary domain, last seen). Check matched.type matches what you asked for; a miss returns error_code: not_found. The matched identifier is the value to feed into a lists_set_definition / lists_edit rule leaf to build a self-updating list — don’t page through these results and dump domains. Read-only. Metered per company returned.

Partnerships

company_partnered_with

Yes/no: are two companies partners? The relationship is undirected — argument order doesn’t matter.

Argument	Type	Required	Notes
company	string	yes	One company’s name or domain.
partner	string	yes	The other company’s name or domain.

Returns: partnered (boolean), evidence (first/last seen and observation count, or null when not partners), and the resolved identity of each company. For a company’s full partner list, use company_detail with section="partners". Read-only. Metered (both companies).

Lookalikes

target_generate

Generate a ranked list of target companies for a domain. Output is a preview — nothing is persisted (each call writes a telemetry row only).

Argument	Type	Required	Notes
requesting_domain	string	yes	The company generating the list.
target_kind	"customers" | "self"	no	Default "customers".
industries_include	list of strings	no	Keep only these industry buckets.
industries_exclude	list of strings	no	Drop these industry buckets.
employee_range_include	list of strings	no	e.g. ["51-200", "201-500"].
countries_include	list of strings	no	ISO 3166-1 alpha-2 codes.
countries_exclude	list of strings	no	ISO 3166-1 alpha-2 codes.
exclude_domains	list of strings	no	Explicit domain blacklist.
uploaded_customer_list	list of strings	no	Seed customers (customers mode) or additional seed companies (self mode).
max_count	integer	no	Default 100, max 500. A soft cap when min_band is set.
min_band	"high" | "medium" | "exploratory"	no	Quality floor.

Two modes via target_kind:

• "customers" (default) — companies that look like the requester’s customers (“who could I sell to?”). Produces a well-formed result for any valid domain.
• "self" — companies that look like the requester itself (“who else looks like us?”). The seed is excluded from output. If the requesting domain is unknown to Trace, returns error_code: requester_unknown_use_authenticated_api — the MCP server can’t trace a new domain, so look it up in the Trace UI or run a trace via the authenticated REST API first, then retry.

Returns: up to max_count candidates, each scored 0–1 and tagged with a confidence band (HIGH / MEDIUM / EXPLORATORY), plus a diagnostic block (check overall_coverage to gauge how much to trust the result). Read-only from the MCP runtime’s perspective. Metered.

Data quality

flag_company_data

Flag a company’s Trace data as wrong and queue it for data-quality review. Authenticated org-scoped MCP callers can use this tool. It is an additive write — no company data is changed.

Argument	Type	Required	Notes
domain	string	yes	The company’s domain.
description	string	no	What looks wrong.

Lists

Lists are saved, named sets of companies in your org. A list can mix explicitly-named domains with dynamic rules (a boolean filter tree over fields like vendor, technology, and partner_of) that re-evaluate on every refresh, so “all companies using Salesforce” stays current. Access on each list is role-based: viewer, editor, or owner.

Tip

To build a list from criteria (e.g. “companies using Salesforce”, “customers of vendor X”), author a dynamic rule with lists_set_definition / lists_edit (action create) — call lists_filter_fields for the field shapes and find_companies_using_technology to resolve a name to its tech_key / vendor_slug. Only use lists_edit (action add_domains) for a few explicitly-named companies; dumping query results into it freezes membership at today’s snapshot.

Read tools

Tool	What it does	Key arguments	Read-only
lists_read	action="all" — every saved list the caller can see (owned, granted, or org-wide), each with is_owner and access_level; auto-creates the org’s default “Target Prospects” list on first call. action="get" — one list’s definition tree, permissions summary, and metadata (add include keys audit / materialization_history / excluded_domains for detail sections). action="find_by_domain" — which visible lists already contain a domain.	action (required); list_id (required for get); domain (required for find_by_domain); include (optional, get only)	Mostly — the first all call may seed the default list
lists_members	The current materialized members, paginated.	list_id (int, required); limit (default 100, max 500); offset; tier (high/medium/exploratory); force_refresh (bool)	Mostly — a stale cache or force_refresh triggers a recompute that writes member rows
lists_filter_fields	The field registry for authoring a definition tree (each field, its operators, value shape), plus registry_version and an authoring guide (tree grammar, AND-vs-OR, negation, worked example).	none	yes

Write tools (non-destructive)

lists_edit groups the non-destructive edits under one action:

Action	What it does	Key arguments
create	Create a list. Takes optional description and a definition envelope for criteria-based lists.	name (required); description; definition (dict)
update	Patch a list’s name / description only (not the definition).	list_id (required); name; description
add_domains	Add explicitly-named domains to a list’s static include set. Idempotent; un-blacklists any of them that were excluded.	list_id, domains (both required)
unblock	Un-blacklist a domain (lift the block). Does not re-add it to the include set.	list_id, domain (both required)
materialize	Synchronously recompute a list’s members, bypassing the cache.	list_id (required)

lists_set_definition stays its own tool: it replaces a list’s entire definition tree (wholesale, not a merge) with a definition envelope {schema_version, registry_version, query}. To make a small change, fetch the current tree (lists_read action get), edit it, and pass the whole tree back.

All of these require editor-or-higher access on the list (except create).

Write tools (destructive)

lists_admin groups the destructive and ownership operations; your MCP client will typically ask for consent before running it.

Action	What it does	Key arguments	Access
delete	Delete a list and cascade-remove its rules, permissions, and members.	list_id (required)	Owner or org-admin
transfer	Transfer ownership to another user.	list_id, new_owner_user_id (both required)	Owner only
remove_domain	Remove a domain from a list and blacklist it so a later recompute can’t resurrect it.	list_id, domain (both required)	Editor-or-higher
grant_permission	Grant editor or viewer access. Pass the person’s name or email as grantee (resolved to a member of your org), or org_wide=True for everyone.	list_id, role (both required); grantee or org_wide	Editor-or-higher
revoke_permission	Revoke a grant.	list_id, permission_id (both required)	Editor-or-higher

All Lists tools are available on every plan. They do not meter per company record.

See also

• MCP overview — connection, OAuth, and metering.
• Credits — how per-record charges and the 30-day re-access window work.
• Authentication — Trace accounts and credentials.