Trace

Full data for ONE section of a single company (name or domain). This is the FULL list behind a `company_profile` count; for a quick overview of all sections at once use `company_profile` instead. Sections: * `'tech'` — the complete detected technology stack, ordered by global adoption. Returns the full stack in one call (offset/limit do not apply); summarise large stacks by category rather than listing every item. The list is complete — do not caveat about undetected tech. * `'jobs'` — paginated job postings (up to 150 per call). Response has `total_jobs` and `has_more`; only page again with a higher `offset` when `has_more` is true, and only if the answer genuinely needs more rows — summarise large job sets (by department / seniority / title theme) instead of paging them all. * `'partners'` — paginated partner companies. Response has `total_partnerships` and `has_more`. Some companies have THOUSANDS of partners; never page through them all (each returned partner is a billed company record). Report `total_partnerships`, show the first page, and for the full set offer a saved list instead (`lists_edit` action='create' with a `partner_of` leaf) — the user can browse it in the app. To test ONE technology against a company use `company_uses_technology`; to test ONE partnership edge use `company_partnered_with` — both are cheaper than pulling a whole section and scanning it. Args: company: The company's name or domain (e.g. "Stripe" or "stripe.com"). section: 'tech', 'jobs', or 'partners'. offset: Pagination offset for 'jobs' / 'partners' (default 0). limit: Max rows for 'partners' (default 20, max 100). Ignored by 'tech' (full stack) and 'jobs' (fixed page of 150).

company_detail

Yes/no: are two companies partners? Confirms a single partnership edge ("is Stripe partnered with Shopify?") instead of paging the full partner list with `company_detail` (section='partners') and scanning it. The relationship is undirected — argument order doesn't matter. Each argument is a company NAME or DOMAIN and resolves on its own — no need to look up domains first. Returns `partnered` (boolean) plus `evidence` (first/last seen and observation count, or null when not partners), and echoes the resolved identity of each company. Args: company: One company's name or domain (e.g. "Stripe" or "stripe.com"). partner: The other company's name or domain (e.g. "Shopify").

company_partnered_with

Look up companies by name or domain — start here for any company question. `company_profile` is the SUMMARY: identity, firmographics, section COUNTS, and a small sample of tech / partners (jobs are count-only here). For the FULL list behind any count — the complete tech stack, the job listing, the partner list — call `company_detail` with the matching `section` ('tech' / 'partners' / 'jobs'). A profile may also include `related_companies` — corporate ownership context (parent / subsidiary / acquirer / acquisition / division); absent when no ownership relationships are known. Reach for a point tool instead of a full profile when the question is a single fact: "does X use tech Y?" → `company_uses_technology`; "who uses Y?" → `find_companies_using_technology`; "are X and Y partners?" → `company_partnered_with`. To discover companies matching partnership + other criteria, use `find_companies` with a `partner_of` leaf. Args: inputs: Company names or domains (max 5). A name resolves to its canonical company; ambiguous names return candidate matches.

company_profile

Yes/no: does ONE company use a specific technology or vendor? Use this to confirm a single fact ("does Shopify use Snowflake?") instead of pulling the company's whole stack with `company_detail` (section='tech') and scanning it yourself. The `technology` argument is fuzzy-matched the same way as `find_companies_using_technology`; the response echoes a `matched` block showing which technology/vendor it resolved to — check it before trusting the verdict. Returns `uses` (boolean) plus `evidence` (detection stats, or null when not used). When a name is both a technology and a vendor (e.g. "Salesforce") it returns `ambiguous: true` with both `candidates` — re-run with `kind`. If `technology` doesn't resolve to anything, returns error_code `not_found` — do not invent a yes/no. Args: company: The company's name or domain (e.g. "Shopify" or "shopify.com"). technology: Technology name, exact tech key, or vendor name (e.g. "Snowflake", "google-analytics", "Salesforce"). kind: "auto" (default) resolves either type and disambiguates a name that is both; "technology" or "vendor" forces that type.

company_uses_technology

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", "partners shared among X, Y, Z", "which of these domains use Z". Returns a match COUNT plus a small sample (the count is free signal; only the sample is billed), then offers to save the result as a live list. `definition` is a boolean tree of filter leaves — pass a bare tree or `{"query": <tree>}`. Call `lists_filter_fields` FIRST: it returns the available fields (technology / vendor / job_title / partner_of / firmographics / __domains), their operators and value shapes, AND an `authoring` guide for the tree grammar (GROUP/LEAF shape, AND-vs-OR value semantics, negation, the "one leaf per required technology" rule, and the mandatory positive filter). Author the tree from that guide rather than guessing the shape. Two recurring traps the guide covers: a leaf's value list is OR, so requiring several technologies TOGETHER needs a separate `in` leaf for each; and a pure-negation query ("neither X nor Y", "not using Z") has no positive anchor and is rejected — don't invent a number, tell the user it needs a positive criterion. Pick the leaf by what the request MEANS: "uses / customer of <vendor or tech>" is a technology/vendor leaf; "partner of <company>" is a `partner_of` leaf — a vendor's customers are not its partners, so never substitute one for the other. Company-valued leaves (`partner_of`, `__domains`) take domains — resolve a company name to its domain with `company_profile` first. For a SINGLE technology or vendor ("who uses Snowflake?") use `find_companies_using_technology` — it needs no tree. This tool is for combinations across two or more criteria.

find_companies

Find the companies that use ONE specific technology or vendor. Pass any technology or vendor name (it fuzzy-resolves); the `matched` block returns the stable `tech_key` / `vendor_slug` to reuse as a `find_companies` leaf. For a COMPOUND query (and/or/not across multiple criteria — "uses X and Y") use `find_companies` instead. To browse WHICH technologies exist (not their users) use `technology_catalog`. When a name is both a technology and a vendor (e.g. "Salesforce"), the tool returns `ambiguous: true` with both `candidates` instead of guessing — re-run with `kind="technology"` or `kind="vendor"` to choose. If it returns `error_code: not_found`, the entity isn't available — say so and stop; do NOT substitute a different leaf type. Popular technologies have tens of thousands of users; never page through them all (each returned company is a billed record). Report the free `total_companies` count with the first page, and for the full set offer a saved list instead (`lists_edit` action='create' with a technology/vendor leaf) — the user can browse it in the app. Args: query: Technology name, exact tech key, or vendor name. limit: Maximum companies (default 20, max 50). offset: Pagination offset (default 0). kind: "auto" (default) resolves either type and disambiguates a name that is both; "technology" or "vendor" forces that type.

find_companies_using_technology

Flag a company's Trace data as wrong and queue it for review. This is an additive write: the company is queued for data-quality audit, but no company data is changed by this tool. Args: domain: The company's domain (e.g. "stripe.com"). description: Optional user-authored context about what looks wrong.

flag_company_data

Generate a ranked list of target companies for a given domain. Two modes via ``target_kind``: * ``"customers"`` (default) — find companies that look like the *customers of* the requester. Use this for "who could I sell to?" The engine pulls customers from tracked-vendor evidence, the ``uploaded_customer_list`` if supplied, or a peer-vendor bootstrap as a last resort. Always produces a well-formed result for any valid domain. * ``"self"`` — find companies that look like the requester ITSELF (and any additional companies in ``uploaded_customer_list``, which in self-mode are treated as ADDITIONAL seed companies — not customers). This is PEER discovery: companies similar to the seed by industry, size, and footprint ("who else looks like Crossbeam?"). Competitors are one kind of peer that surfaces — not the whole result; expect look-alikes broadly (peers and adjacent players), not a curated competitor set. Don't describe the output to users as "competitors". The seed (requester + uploaded list) is excluded from output. When the requesting domain is unknown to us, returns ``error_code="requester_unknown_use_authenticated_api"`` (the MCP runtime can't auto-trace — read-only DB / no SQS perms). The agent should ask the user to look up the domain in the Trace UI or run a trace through the authenticated REST API, then retry. Returns up to ``max_count`` candidates, each scored 0-1 and tagged with a confidence band (HIGH / MEDIUM / EXPLORATORY). Optional ``min_band`` quality floor turns ``max_count`` into a soft cap: "give me up to N candidates AT OR ABOVE this band — don't pad with weaker matches." Output is a preview — nothing is persisted; every call writes a telemetry row to lookalike_generation_runs. Callers should check ``diagnostic.overall_coverage`` to decide how much to trust the result. Args: requesting_domain: Domain of the company generating the list (required). industries_include: Keep only candidates in these IndustryBucket values. industries_exclude: Drop candidates in these IndustryBucket values. employee_range_include: Keep candidates only in these employee range buckets (e.g. ["51-200", "201-500"]). countries_include: ISO 3166-1 alpha-2 codes to include. countries_exclude: ISO 3166-1 alpha-2 codes to exclude. exclude_domains: Explicit domain blacklist. uploaded_customer_list: In customers-mode, customer domains used as the seed when the requester isn't a tracked vendor. In self-mode, additional seed companies that (with ``requesting_domain``) define the "look like THESE" template. max_count: Maximum candidates returned. Default 100, max 500. target_kind: ``"customers"`` (default) or ``"self"``. min_band: Optional quality floor — ``"high"``, ``"medium"``, or ``"exploratory"``. When set, max_count is a soft cap.

target_generate

List the fields you can use in a list definition tree. Call this before authoring a definition with ``find_companies`` / ``lists_set_definition`` / ``lists_edit`` (action='create') so a request like "all companies using Salesforce" becomes a dynamic, self-updating rule rather than a frozen set of explicit domains. The response carries: * ``fields`` — the same registry the builder UI reads: each rule-leaf ``field`` (e.g. ``vendor``, ``technology``, ``partner_of``), its allowed operators, and its ``value`` shape. * ``registry_version`` — copy it into the envelope you author rather than guessing a value. * ``authoring`` — the tree grammar: GROUP/LEAF shape, snake_case operators, the OR-within-a-leaf rule (and how to require multiple values together), negation forms, the mandatory positive filter, and a worked example.

lists_filter_fields

Return the current materialization of a list, paginated. Args: list_id: The numeric list_id. limit: Max members per page (default 100, max 500). offset: Pagination offset (default 0). tier: Filter to one band: 'high', 'medium', or 'exploratory'. force_refresh: If true, synchronously recompute before returning.

lists_members