Canonical Company Search

Find companies similar to a given company by domain. Args: company_domain: Domain of the seed company (e.g. "stripe.com"). Required for a new search; omit only when resuming a previous search via `cursor` (the seed is pinned server-side from the original call). top_k: Number of similar companies to return (1-1000, default 25). Prefer 25+ so the user sees the full similar set; only go lower when they explicitly want just the closest one or two. Each returned strong match costs 1 credit. intent: Optional ranking profile that reorders the similar set AFTER similarity filtering — same taxonomy and selection rule as `search_companies` (pick the slug matching the user's use case; omit / pass null for relevance-only ordering). Intent only changes the ORDER of the matched set; it never changes which companies are in it, the candidate pool, or the credits charged. Use it for requests like "companies similar to Stripe that are hiring/growing fast" or "...ranked for who's buying now". Allowed slugs: - "sales_prospecting": general outbound ICP list. - "sales_timing": accounts with a near-term buying window. - "sales_expansion": existing customers ripe for upsell. - "competitive_tracking": monitor NAMED competitors' direction. - "emerging_competitor_scan": discover rising new entrants. - "talent_source": companies to poach candidates from. - "recruiter_employer_vet": vet a company for a candidate. - "jobseeker_stability": job security over upside. - "jobseeker_growth": career-growth / high-momentum companies. See `search_companies` for the full per-slug guidance. include_partials: When True, also returns LLM-evaluated "partial" matches (close but not strong). Off by default because partials aren't billed; opt in only when the user wants exploratory context beyond strong matches. Default False. exclude_company_domains: Optional list of company domains to exclude from the similar-companies results. Useful when the seed has obvious near-clones you want to skip (e.g. "similar to Stripe, not Square or Adyen"). Unresolvable domains appear in `warnings`. cursor: Opaque pagination token from a previous response's `next_cursor`. Pass it back (with `company_domain` omitted) to fetch the next page of the SAME similar-companies search — the original seed company is pinned from the first call. The response includes `next_cursor` when more results remain; pass it back as `cursor` to page through the rest without re-querying from scratch. When presenting results to the user, render each company's `domain` as a clickable link to the company's website (e.g. as a Markdown link to https://<domain>). Note: each candidate is independently LLM-verified, so the exact set (and therefore the result count and credits charged) can vary slightly between otherwise-identical calls — borderline matches may pass on one run and not the next. This is expected and is not affected by `intent`.

find_similar_companies

Return the authenticated org's credit balance, plan, and search rate limits. Use this to check remaining credits before issuing a search, or to pace requests against the org's per-minute and per-day limits. This call is completely free — it charges no credits and does not count against the search rate budget. Returns: - `credits`: bucket breakdown (`total`, `subscription`, `extra`) and `subscription_resets_at` (ISO datetime string or null) — when the subscription bucket will next be refilled. - `plan`: the org's current plan name (e.g. "free", "starter", "pro"). - `rate_limits`: `per_minute` and `per_day` search operation limits for the current plan.

get_account_status

Return the full detail payload for one canonical company by domain. Use this AFTER a search to drill into a specific company. Returns: - `company`: full canonical fields (name, domain, description, hq, employees, funding, dimensions). Includes `defunct` (bool) — when true the company has shut down, so don't route users to it. Always present when the domain resolves to a known company. Internal `id` fields are intentionally not included. - `people`: key people (cofounders + C-suite/execs — not only founders) with role, headline, LinkedIn URL, and `prior_companies` (each with category tags like 'faang', 'unicorn', 'top_startup', 'big_tech', 'mbb', and a `domain` handle you can pass back into this tool to walk the company graph). May be empty. - `leadership_data`: `"available"` (people populated), `"not_available"` (company is in our DB but not in the leadership subset — most companies fall here), or `"error"` (transient lookup failure). - `relationships` (present only when the company has corporate- relationship edges; `source` reports their provenance, e.g. 'analyst_curated'): `parents` (direct owners, each with a `relation` like 'wholly_owned_subsidiary'), `ultimate_parent` and `lineage` (ownership chain ordered root→immediate parent; null/empty when the company is top-level or ownership is ambiguous, e.g. a joint venture with multiple owners), and `children` (ALL related companies, grouped by category — subsidiary, product_of, joint_venture, merger, other — ordered largest-first; lists are complete, never truncated). Every related company carries a `domain` — pass it back into this tool to walk the corporate graph (each hop costs 1 credit). Costs 1 credit per call, charged only when the domain resolves to a real company (a not-found domain is free). Response includes `credits_used` and `credits_remaining`. Rate-limited to prevent enumeration. When showing this to the user, render the `domain` as a clickable link to the company's website (e.g. as a Markdown link to https://<domain>). Args: company_domain: Domain of the company (e.g. "stripe.com") — the same handle returned in search results.

get_company_details

Look up companies by name to disambiguate before another tool. Use this when a user names a company you'll feed into `find_similar_companies` (as a seed) or `search_companies` (as an `exclude_company_domains` entry) and the name might be ambiguous. Returns, per input name: - `candidates`: ranked (best-guess-first) list, each with `name`, `domain`, `headquarters`, `description`, `is_primary`, and `payload_richness`. - `confidence`: `"high"` (one entity) | `"medium"` (a dominant entity among rivals) | `"low"` (comparable rivals — a real toss-up). - `primary_candidate_domain`: the recommended domain, or `null` when asking. - `auto_resolve_recommended`: bool. Input shaping — RAISES HIT RATE, no extra cost (1 credit per call whatever you pass): when a name carries a legal/registry suffix (Ltd, LLC, GmbH, "Co., Ltd", s.r.o., Pvt. Ltd.), a **leading article** ("The Home Depot", "The Kroger Co"), or a location qualifier ("Raima Barcelona"), ALSO include the bare trade name as a separate entry — e.g. `["CEQUENS HOLDING LIMITED", "Cequens"]`, `["The Home Depot", "Home Depot"]`, `["The Kroger Co", "Kroger"]`. The corpus stores some companies under the article and some without it, so sending both forms is what makes the hit reliable. If a domain is embedded in the name, pass it as its own entry (`"Undo (undo.io)"` → add `"undo.io"`). For a non-Latin name, add a transliteration or English trade name if known. Send the extra forms alongside the original, never instead of it. Disambiguation policy — FOLLOW THIS: - If `auto_resolve_recommended` is true, proceed silently with `primary_candidate_domain` (the one candidate marked `is_primary`). Do NOT ask the user — the match is unambiguous (one entity, or a clear dominant one). - If `auto_resolve_recommended` is false, `primary_candidate_domain` is `null` and NO candidate is `is_primary` — none is authoritative. Present `candidates` to the user as a list and WAIT for them to pick before calling the next tool. Do not auto-select even if one looks right — disambiguation is the point. Costs 1 credit per call, charged only when at least one candidate is returned (a no-match lookup is free) — regardless of how many names or candidates. Response includes `credits_used` and `credits_remaining`. Rate-limited. Args: names: One or more free-text company names to look up. k: How many candidates to return per name (1-25, default 5). disambiguation_mode: Override the recommendation for non-interactive callers. "auto_when_confident" (default) follows the policy above; "always_auto" never asks (use the primary); "always_ask" always asks.

lookup_companies

Search Canonical's verified company graph for the long tail — the companies others miss. This is precise, LLM-verified company discovery, not a web search that returns ranked links. `description` is the only fuzzy / semantic field: it expresses a free-text concept (e.g. "enterprise SaaS for supply-chain visibility"), which is passed to an LLM verifier that checks each candidate against the intent and returns a verdict. Everything else is an exact, hard filter — the pipeline enforces it before the verifier sees a result. IMPORTANT — unsupported constraints: there is intentionally NO field for constraints we cannot enforce (founder demographics, profitability, YC / accelerator batch, individual revenue figures). If the user asks for one, tell them it isn't a supported filter rather than pretending it was applied — or fold the idea into `description` for loose semantic verification. For example "YC S22 company" → description="Y Combinator Summer 2022 batch startup", which the verifier will check loosely. IMPORTANT — exclusions belong in `exclude_description`, never in `description`. When the user says a company should NOT be something ("no drinks-only co-packers", "exclude logistics and distributors", "not consulting"), put that concept in `exclude_description`. A negation written into `description` is read as POSITIVE signal — it pulls in the very companies you meant to exclude and sharply lowers precision. IMPORTANT — `description` is matched against a company factsheet, and the verifier scores only three things: what the company OFFERS, WHO it serves, and HOW it makes money. Route every other constraint to its own field, or it silently retrieves the wrong companies: - Size ("large", "major", "enterprise-scale") → `employee_count_min` / `employee_count_max`. There is no size axis in the verdict, so a size word left in `description` filters nothing at all. - Location → `countries` / `states` / `cities`. Don't also name the country in `description`. - Why you want the list ("sources of talent", "benchmarks for X", "acquisition targets") → `intent`. Never restate it in `description`. - A factsheet describes what a company SELLS. So any phrase naming what a company BUYS, USES, EMPLOYS or IS SUBJECT TO retrieves the companies that SELL that thing, not the ones you meant. Describe the target by what IT does, and put the thing-it-uses in `exclude_description`. (Ask for employers that offer a benefit and you get the benefit's vendors; ask for companies to recruit from and you get recruiters.) Args: description: Free-text semantic concept describing what the company does. This is the ONLY fuzzy field — the LLM verifier reads it and checks each candidate for match/partial/irrelevant. Examples: "B2B SaaS for HR teams", "consumer fintech targeting millennials", "climate tech in renewable energy storage". Omit (or pass null) for purely filter-driven searches (e.g. "all Series B companies in India with 50-100 employees"). Describe ONLY what the company SHOULD be. Do NOT embed exclusions or negations here (no "exclude X", "not Y", "without Z", "excluding …") — those belong in `exclude_description`; left here they are treated as positive signal and hurt results. cities: Restrict to companies headquartered in these cities. Exact match (case-insensitive). Example: ["San Francisco", "New York"]. For a metro/region, list all constituent cities and include common name variants (e.g. Gurgaon/Gurugram, Bengaluru/Bangalore). states: Restrict to these states/provinces. Example: ["California", "New York"]. Use full name, not abbreviation. countries: Restrict to these countries. Expand geographic regions to their constituent countries before passing — e.g. "Southeast Asia" → ["Indonesia", "Vietnam", "Thailand", "Philippines", "Malaysia", "Singapore"]; "Nordics" → ["Sweden", "Norway", "Denmark", "Finland", "Iceland"]. Single country: ["India"]. Only set this when the user EXPLICITLY names a geography. Do NOT infer a country from the user's own locale, timezone, or language — an unrequested location filter silently drops the large majority of matches (companies are worldwide). When in doubt, leave it unset. employee_count_min: Smallest company headcount to include (inclusive). E.g. employee_count_min=5 with employee_count_max=25 means "5-25 employees"; min alone (e.g. 500) means "500+". For "well-funded startup" signals, use funding_min_usd instead. employee_count_max: Largest company headcount to include (inclusive). Omit for an open-ended upper bound. founding_year_min: Lowest founding year to include (inclusive 4-digit year). E.g. 2015 means "founded in 2015 or later". Combine with founding_year_max to express a range. founding_year_max: Highest founding year to include (inclusive). E.g. 2020 means "founded in 2020 or earlier". For an exact year, set founding_year_min == founding_year_max. founding_year_exclude_min: Lowest year of a contiguous range to EXCLUDE (inclusive). Both exclude_min and exclude_max must be set together; for a single-year exclusion ("not founded in 2020"), set both to the same year. founding_year_exclude_max: Highest year of the contiguous range to EXCLUDE (inclusive). Note on NULLs: companies with unknown founding year are DROPPED when including (min/max), but KEPT when excluding — matching the intuitive reading of "not founded in 2020" (unknowns might be). funding_series: One or more funding-round labels to include. Values: "pre_seed", "seed", "series_a", "series_b", "series_c", "series_d", "series_e", "series_f", "series_g_plus", "growth", "late", "bridge", "venture", "angel", "other". funding_min_usd: Minimum LATEST-ROUND funding amount (USD). Heuristics: "well-funded startup" ≈ 50_000_000; "unicorn-range" use funding_post_money_min_usd instead. funding_max_usd: Maximum LATEST-ROUND funding amount (USD). Pair with funding_min_usd for a two-sided range (e.g. "raised between $10M and $20M"); omit for an open-ended upper bound. funding_post_money_min_usd: Minimum post-money valuation (USD). Heuristic: "unicorn" ≈ 1_000_000_000. funding_post_money_max_usd: Maximum post-money valuation (USD). Pair with funding_post_money_min_usd for a two-sided valuation range; omit for an open-ended upper bound. funded_after: Only include companies that raised a round after this ISO date (YYYY-MM-DD). Example: "2022-01-01". funding_investor: Filter to companies backed by these investors. Pass the investor firm name; the server expands it to canonical variants and fund-family splits automatically. Example: "Sequoia" resolves to "Sequoia Capital", "Peak XV Partners", "Sequoia Capital India". You may pass multiple investors for an OR match. has_repeat_founder: True → require at least one founder who has previously founded or co-founded another company. has_technical_cofounder: True → require at least one technical co-founder (CTO/engineering background). founder_prior_categories: Restrict to companies whose founders previously worked at companies in these categories. Values: "faang", "big_tech", "unicorn", "top_startup", "mbb". founder_prior_companies: Restrict to companies whose founders previously worked at any of these free-text company names (resolved to canonical entities). exclude_company_domains: Domains to exclude from results. Use `lookup_companies` first to resolve names to domains when needed. Unresolvable domains appear in the response `warnings`. exclude_description: ALL semantic exclusions go here — every concept the company must NOT match. Any candidate the LLM judges as matching this description is filtered out. Use this whenever the user says "exclude / not / without / no / except …", and pack multiple exclusions into one string, e.g. exclude_description="logistics providers, distributors, drinks-only manufacturers". Combined with `description` for fine-grained positive+negative semantic shaping. Do NOT phrase these as negatives inside `description`. intent: Optional ranking profile applied AFTER relevance filtering. Pick the slug that best matches the user's stated or implied use case from the surrounding conversation. Omit / pass null for relevance-only ordering. Allowed slugs and when to pick each: - "sales_prospecting": general outbound — user is building a top-of-funnel list of potential customers without a specific buying-window constraint. Optimizes for companies that are actively growing, hiring, and have brand reach (broad ICP fit). - "sales_timing": "who is buying NOW?" — user wants accounts with a near-term buying window. Optimizes for recent hiring acceleration paired with healthy growth (active investment / budget release). - "sales_expansion": user already has the customer relation- ship and wants accounts ripe for upsell, cross-sell, or deepening. Optimizes for stable, steadily-growing companies with strong retention. - "competitive_tracking": user has NAMED competitors and wants to monitor their direction. Optimizes for hiring- direction shifts, momentum, brand reach, and geo footprint. - "emerging_competitor_scan": user wants to DISCOVER new entrants / rising challengers they don't yet know about. Optimizes for fast-growing, aggressively hiring companies with rising visibility. - "talent_source": recruiter / hiring manager looking for companies to poach candidates from. Optimizes for hiring in the target function, alumni footprint, team pedigree, retention. - "recruiter_employer_vet": user is evaluating whether to send a candidate to a particular company ("is this a good place for my candidate?"). Optimizes for employer retention, stability, talent demand, and brand reach. - "jobseeker_stability": job seeker prioritizing job SECURITY over upside ("is this company safe?"). Optimizes for low churn, positive net flow, retention, moderate momentum. - "jobseeker_growth": job seeker prioritizing career GROWTH ("where can my career accelerate?"). Optimizes for high-momentum companies hiring into growth functions, strong talent magnetism, recent hiring velocity. top_k: Number of results to return (1-1000, default 25). Do NOT under-request: Canonical's value is breadth across the long tail, so a small top_k hides the very companies the user came for. Default to at least 25 for discovery / prospecting / competitive scans, and prefer 25-50 when the user wants a thorough list. Only drop below 10 when the user explicitly asks for a single best match or a quick peek. Each returned strong match costs 1 credit, so do not pad beyond what the user needs either. include_partials: When True, also returns LLM-evaluated "partial" matches (close but not strong). Off by default because partials aren't billed; opt in only when the user wants exploratory context beyond strong matches. Default False. cursor: Opaque pagination token from a previous response's `next_cursor`. Pass it back to fetch the next page of the SAME search — when set, all other arguments except `top_k` are ignored server-side (the original description/filters are pinned from the first call). Omit for a new search. The response includes `next_cursor` when more results remain; pass it back as `cursor` to page through the rest without re-querying from scratch. When presenting results to the user, render each company's `domain` as a clickable link to the company's website (e.g. as a Markdown link to https://<domain>). Note: hard filters (location, funding, employee size, founder background, etc.) are applied exactly; `description` is the only fuzzy field, matched by an LLM verifier. Because each candidate is independently verified, the exact result set (and therefore the count and credits charged) can vary slightly between otherwise-identical calls — borderline matches may pass on one run and not the next. This is expected.

search_companies