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, plan requirement, and metering.

A few things that apply across the board:

• Plan gating. The whole server is Starter+. Tools marked Pro below return an upgrade_required error on a Starter (or lower) plan. Everything else works on Starter+.
• 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, upgrade_required, credit_exhausted, timeout.
• Domains. Pass a bare domain like stripe.com. The server normalizes www. prefixes and full URLs where it can.

Companies

batch_lookup_companies — Pro

Look up one or more companies by domain (up to 5) in a single call. Use it for all company lookups, single or multiple.

Argument	Type	Required	Notes
domains	list of strings	yes	Up to 5 domains. For one company, pass a one-element list.

Returns: a profile per input domain, keyed by the domain. Each profile has the company name, all known domains, technology stack, partnerships (up to 50), and active job postings (up to 50). Invalid or unknown domains come back as per-domain error objects. Read-only. Metered per company returned.

get_tech_stack

Get the complete technology stack for one company. Use this when someone asks what technologies, tools, or software a company uses.

Argument	Type	Required	Notes
domain	string	yes	e.g. stripe.com

Returns: company name, domain, total_technologies (the exact count), and the full detected stack ordered by global adoption (most widely used first). Read-only. Metered (1 company). Available on Starter+.

list_company_jobs — Pro

List a company’s active job postings, the hiring signal.

Argument	Type	Required	Notes
domain	string	yes	e.g. godaddy.com
offset	integer	no	Pagination offset, default 0.

Returns: company name, domain, total_jobs (true count), has_more, and up to 50 jobs per call. Only page further when has_more is true. Read-only. Metered (the company).

Technologies and vendors

search_technologies

Search the technology catalog by technology name or vendor name. To find companies that use something, use find_companies_using instead.

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). Available on Starter+.

find_companies_using

Find companies that use a specific technology or vendor. Accepts a technology name, an exact tech key, or a vendor name.

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 set_list_definition / upsert_list rule leaf to build a self-updating list — don’t page through these results and dump domains. Read-only. Metered per company returned. Available on Starter+.

Partnerships

find_partnerships — Pro

Find companies partnered with a given company.

Argument	Type	Required	Notes
domain	string	yes	e.g. crossbeam.com
limit	integer	no	Default 50, max 100.
offset	integer	no	Default 0.

Returns: the company, total_partnerships, has_more, and a page of partner companies (name, primary domain, first/last seen). A company with no partner record returns an empty list (zero billed). Read-only. Metered per partner company returned.

Lookalikes

generate_target_list — Pro

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.

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 set_list_definition / upsert_list — call get_filter_fields for the field shapes and find_companies_using to resolve a name to its tech_key / vendor_slug. Only use add_domains_to_list 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
list_target_lists	Every saved list the caller can see (owned, granted, or org-wide). Auto-creates the org’s default “Target Prospects” list on first call.	none	Mostly — first call may seed the default list
get_list	A list’s definition, permissions summary, and metadata.	list_id (int, required); include (list of audit / materialization_history / excluded_domains / definition / permissions)	yes
get_list_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_containing_domain	Which visible lists already contain a domain.	domain (string, required)	yes
get_filter_fields	The field registry for authoring a definition tree (each field, its operators, value shape) plus registry_version.	none	yes

Write tools (non-destructive)

Tool	What it does	Key arguments
upsert_list	Create or update a list. create requires name, takes optional description and a definition envelope. update patches name/description only (not the definition).	action (create/update, required); name; description; definition (dict); list_id (required for update)
set_list_definition	Replace a list’s entire definition tree (wholesale, not a merge).	list_id (int, required); definition (dict envelope {schema_version, registry_version, query}, required)
force_materialize_list	Synchronously recompute a list’s members, bypassing the cache.	list_id (int, required)
add_domains_to_list	Add explicitly-named domains to a list’s static include set. Idempotent; un-blacklists any of them that were excluded.	list_id (int, required); domains (list of strings, required)
remove_excluded_domain	Un-blacklist a domain (lift the block). Does not re-add it to the include set.	list_id (int, required); domain (string, required)

All five require editor-or-higher access on the list.

Write tools (destructive)

Your MCP client will typically ask for consent before running these.

Tool	What it does	Key arguments	Access
delete_list	Delete a list and cascade-remove its rules, permissions, and members.	list_id (int, required)	Owner or org-admin
manage_list_permissions	Grant or revoke a permission. grant needs role (editor/viewer) plus user_id or org_wide=True; revoke needs permission_id.	action (grant/revoke, required); list_id (required); role; user_id; org_wide (bool); permission_id	Editor-or-higher
transfer_list_ownership	Transfer ownership to another user.	list_id (int, required); new_owner_user_id (user ID, required)	Owner only
remove_domain_from_list	Remove a domain from a list and blacklist it so a later recompute can’t resurrect it.	list_id (int, required); domain (string, required)	Editor-or-higher

All Lists tools are available on Starter+ (no per-tool Pro gate). They do not meter per company record.

See also

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