Get Account Information
Check your API key and account status.
Returns validation status, credits remaining, and
plan info if available. Free (no credits used).
Further account details are available at https://sumble.com/account
Args:
reason: Why you are calling this tool.
Get My Company Profile
Get your company's profile and target account intelligence profile.
Returns the intelligence profile for your company, designed to
help you understand how to position and break into accounts.
Use this data to craft targeted outreach and prioritize efforts.
The response includes:
- company_summary: Who your company is, what you sell, what
problems you solve, your sales plays, and reference customers
you can cite.
- technologies: Your competitive landscape. Includes your own
technology, modern and legacy competitors, and complementary
tools in your ecosystem. Each technology has a tier (key or
other) indicating its importance.
- tech_concepts: Abstract technology themes relevant to your
company (e.g., SIEM, ETL, CI/CD).
- job_functions: The personas and roles your company targets,
split by importance (key vs other).
- projects: The types of initiatives and projects happening at
target accounts that are relevant to your offering, split by
importance (key vs other).
This is a free call, and the response is stable for the session —
you can rely on it as context for follow-up outreach and account
questions without re-fetching.
Args:
reason: Why you are calling this tool.
List Contact Lists
List the user's contact lists (people lists).
Returns metadata for each list: id, name, people_count,
and url. Always surface the url to the user so they can
view the list in Sumble.
Use get_contact_list after this to retrieve the people in a
specific list.
Costs 1 credit per returned list.
Args:
reason: Why you are calling this tool.
Get Contact List
Get one contact list and its people.
Fetch a list by id after calling list_contact_lists.
Returns list metadata (including url) and simplified
person data: id, name, job_title, job_function,
linkedin_url, organization info, and contact_info
(emails/phone) if the contact was enriched. Each
person entry includes a `url` linking to their
Sumble profile for more details. Always show these
URLs and the list url to the user.
Costs 1 credit per returned person.
Args:
list_id: The contact list ID (from list_contact_lists).
reason: Why you are calling this tool.
Create Contact List
Create a new contact list (people list).
Returns the new list's id, name, and url. Always
surface the url to the user so they can view the
list in Sumble. Use add_contacts_to_list to populate
it afterward.
WORKFLOW — when a user wants to build a people list:
1. Call find_people or find_related_people_to_person
to get Sumble person IDs.
2. Call create_contact_list to make the list.
3. Call add_contacts_to_list with the person IDs.
If you already have Sumble person IDs (from a prior
API call), skip step 1 and use those IDs directly.
Always ask the user for the list name. If you have a
good guess, you can suggest it in the prompt.
Args:
reason: Why you are calling this tool.
name: Name for the new list.
Add Contacts To List
Add people to an existing contact list.
Accepts Sumble person IDs. Returns how many were added,
how many were already on the list, and the list url.
Duplicates are silently skipped. Always surface the url
to the user so they can view the list in Sumble.
WORKFLOW — when a user provides names or LinkedIn URLs:
1. Call find_people to resolve them to Sumble person
IDs.
2. Call add_contacts_to_list with the matched IDs
(use the "id" field from each result).
If you already have Sumble person IDs (from a prior
API call), pass them directly as people_ids.
Args:
reason: Why you are calling this tool.
list_id: The contact list ID (from
list_contact_lists or create_contact_list).
people_ids: Sumble person IDs to add.
List Organization Lists
List the user's organization lists, i.e. their accounts.
Returns concise metadata for each list: id, name, type,
organizations_count, read_only, deletable, and deleted. Use
`GetOrganizationList` after this to retrieve one list's organizations.
Each list has a type: "group" or "user". A "group" list is
the user's territory — synced from their employer's CRM or
territory management system. Questions about "my territory"
or "my accounts" map to the group list; ad-hoc lists the
user has built themselves are "user" lists.
Costs 1 credit per returned list.
Args:
reason: Why you are calling this tool.
include_deleted: If True, also return soft-deleted lists (each is
flagged with `deleted: true`). Defaults to False.
Get Organization List
Get one organization list (i.e. one of the user's account lists)
and its organizations, by list_id. Includes id, name, slug, sumble_url
(the org's Sumble profile page), and url (the org's own website) for each
organization.
Typically used after calling `ListOrganizationLists`. It is not filterable.
Share the url with the user.
Costs 1 credit per returned item.
Note that `GetOrganizationList` is not a general purpose organizations
search, it is only for retrieving a user's account list.
Use `FindMatchAndEnrichOrganizations` to more generally search
organizations by query. Note that `FindMatchAndEnrichOrganizations`
offers `organizations_list` as a filter option, which is a good way to
find companies meeting various criteria within a user's accounts.
Args:
list_id: The organization list ID (from `ListOrganizationLists`).
reason: Why you are calling this tool.
include_deleted: If True, the list is returned even when it has been
soft-deleted. Defaults to False.
Create Organization List
Create a new organization list.
Returns the new list's id and name. Use
add_organizations_to_list to populate it afterward.
Share the list url with the user so they can view it in the dashboard.
WORKFLOW — when a user provides company names/URLs:
1. Call FindMatchAndEnrichOrganizations to resolve them
to Sumble IDs.
2. Call create_organization_list to make the list.
3. Call add_organizations_to_list with the matched IDs.
If you already have Sumble org IDs (from a SQL query,
FindMatchAndEnrichOrganizations, or another API call), skip step 1
and use those IDs directly.
Always ask the user for the list name to use. If you
have a good guess for the name, you can suggest it in the prompt,
Args:
reason: Why you are calling this tool.
name: Name for the new list.
Add Organizations To List
Add organizations to an existing list.
Accepts Sumble organization IDs and/or slugs. Returns
which were added and which failed.
WORKFLOW — when a user provides company names/URLs:
1. Call FindMatchAndEnrichOrganizations to resolve them
to Sumble IDs.
2. Call add_organizations_to_list with the matched IDs
(use the "id" field from each match result).
If you already have Sumble org IDs (from a SQL query,
FindMatchAndEnrichOrganizations, or another API call), skip step 1
and pass them directly as organization_ids.
Args:
reason: Why you are calling this tool.
list_id: The organization list ID (from
list_organization_lists or
create_organization_list).
organization_ids: Sumble organization IDs to add.
organization_slugs: Sumble organization slugs to
add (resolved server-side).
Set Organization List Deleted
Soft-delete or restore an organization list.
Deletion is reversible: pass `deleted=False` to restore a list. Deleting or
restoring a list does not delete or restore individual organizations in the
list. To find a deleted list to restore, call `ListOrganizationLists` with
`include_deleted=True`.
Only user-created lists can be deleted. "Group" lists (synced territories)
are read-only and cannot be deleted or restored.
Args:
reason: Why you are calling this tool.
list_id: The organization list ID (from `ListOrganizationLists`).
deleted: True to soft-delete the list, False to restore it.
Defaults to True.
Set Organization List Signals
Include or exclude an organization list's accounts from signals.
Pass `include_in_signals=False` to exclude this list's accounts from your
signals, or `True` to include them again. Lists are included by default.
This mirrors the per-list signals toggle in the dashboard.
Args:
reason: Why you are calling this tool.
list_id: The organization list ID (from `ListOrganizationLists`).
include_in_signals: True to include the list's accounts in signals,
False to exclude them.
Find Match And Enrich Jobs
The primary jobs tool: look up jobs by
id or search the jobs corpus, and return exactly the attributes you ask
for, with optional related people.
INPUT — provide EXACTLY ONE of:
- `jobs` (list mode): up to 1000 entries, each {"job_id": <int>}. One
result row per entry, in input order; entries that don't match a
Sumble job come back with just their input echoed and cost nothing.
- Filter mode: any of `organization_ids`, `organization_list_id`,
and/or `query` (at least one required). With no organization scope
the whole jobs corpus is searched. `limit`/`offset` apply to filter
mode only.
ORGANIZATION SCOPING (filter mode) — there is no name/domain org param.
To scope to specific companies, first resolve names or domains to ids
with FindMatchAndEnrichOrganizations (whose free attributes include
`id`) and pass `organization_ids`. The query language's
`organization EQ '<name>'` node is a fuzzy single-org match and can
pick the wrong company — prefer explicit ids. For saved lists prefer
the `organization_list_id` param over the query language's
`organizations_list` field.
SELECT — `attributes`. Every row always includes job_id and a
sumble_url deep link for free, plus the free attributes
(title). Paid attributes (1 credit each per returned
job): description, location, posted_date, organization, technologies, teams, job_functions, job_levels, projects.
`description` is the full posting text; selecting it allows at most
200 jobs per request in list mode.
RELATED PEOPLE — pass `related_people` as {"attributes": [...],
"limit": N} to also get the people likely involved in each job's
hiring: scored hiring managers and team members at the posting
organization, inferred from team, job function, location and
technology similarity, not actual reporting lines. Available in BOTH
modes, for at most 25 jobs per request (list entries or `limit`).
Per-job limit is 1-25 (default 5); 1 credit per related person
returned. Related people support the person attributes (name is free;
linkedin_url, job_title, job_function, job_level, location, country,
current_employer, technologies) except email/phone.
COST — total = returned jobs x (1 + paid attributes) + related people
returned. The API checks affordability up front and returns an error
before doing any work the user can't pay for.
Always share sumble_url links with the user. Filter mode also returns
a `source_data_url` linking to the matching jobs on Sumble (present
when no org scope or exactly one org is given) — share it with the
user too.
QUERY SYNTAX (use `query` param):
Operators: EQ, NEQ, IN, NOT IN.
Combine with AND, OR. Group with parentheses.
Values are single-quoted. IN/NOT IN use
comma-separated values in parens.
Available fields:
ORGANIZATION / SCOPE FIELDS — filter which orgs
to search jobs within:
- organizations_list — EQ/IN. Restrict to a
user's saved org list by numeric list ID.
Use ListOrganizationLists to get IDs first.
Use 'default' for the user's default list.
Example: organizations_list EQ '42'
- organization — EQ only. Fuzzy org name/URL.
- industry — EQ/IN/NOT IN.
- employee_count — EQ/IN. Range format:
'100-1000', '1000-' (1000+), '-500'.
- hq_location — EQ/IN/NEQ. Format:
'US', 'US:Texas', 'US:Texas:Austin'.
Region codes: EMEA, APAC, NAMER, LATAM.
- tag — EQ/IN (e.g. 'digital_native').
- funding_last_round_type — EQ/IN/NEQ/NOT IN.
Values: 'pre_seed', 'seed', 'series_a' through
'series_h', 'series_h_plus', 'debt', 'grant',
'convertible_note', 'private_equity'.
'series_h_plus' is a virtual value that matches
Series I and beyond (series_i..series_z under the
hood). Raw 'series_i'..'series_z' are NOT accepted
as filter values — use 'series_h_plus' instead.
- funding_last_round_year — EQ. Range format like
employee_count: '2022-2025', '2023-', '-2020'.
- funding_last_round_raised — EQ. USD amount raised
in the most recent round. Range format:
'1000000-50000000', '100000000-', '-5000000'.
- funding_total_raised — EQ. Range format in USD:
'1000000-50000000', '100000000-', '-5000000'.
- funding_valuation — EQ. Post-money valuation in
USD. Range format:
'10000000-1000000000', '1000000000-', '-50000000'.
JOB FIELDS — filter which jobs to return:
- technology — EQ/IN/NOT IN. Use slugs from
SearchTechnologies.
- technology_category — EQ/IN/NOT IN (e.g.
'gen-ai', 'mlops', 'cybersecurity').
- project — EQ/IN. Filter by project slug.
Example: project IN ('cloud-migration',
'gen-ai-initiative')
- job_function — EQ/IN/NOT IN (e.g.
'Machine Learning', 'Data Scientist',
'Engineer', 'Product Manager').
- job_level — EQ/IN/NOT IN (e.g.
'Senior', 'Manager', 'VP', 'Director').
- country — EQ/IN/NOT IN. Format:
'US', 'US:California',
'US:California:San Francisco'.
Use full state names, not abbreviations.
'UK' is auto-converted to 'GB'.
- hiring_period — EQ ONLY (not IN/NOT IN).
Values: '2wk', '1mo', '3mo', '6mo',
'1yr', '18mo', '2yr'.
- NOTE: job_title and job_description are NOT
available as filters. Use job_function and
job_level.
COMBINING FILTERS:
Use AND to combine org fields with job fields.
Do NOT use OR across org and job fields.
Examples:
- Jobs in a user's org list with specific tech:
organizations_list EQ '42'
AND technology IN ('snowflake', 'databricks')
- Jobs in default list, ML roles, recent:
organizations_list EQ 'default'
AND job_function EQ 'Machine Learning'
AND hiring_period EQ '3mo'
- Jobs at large US companies using PyTorch:
technology EQ 'pytorch'
AND hq_location EQ 'US'
AND employee_count EQ '1000-'
- Jobs matching a project and function:
project EQ 'cloud-migration'
AND job_function IN ('Cloud Engineer',
'DevOps Engineer')
- Basic tech + location:
technology IN ('pytorch', 'tensorflow')
AND country EQ 'US'
- Function + level:
job_function IN ('Machine Learning',
'AI Engineer') AND job_level EQ 'Senior'
Args:
reason: Why you are calling this tool.
jobs: List mode entries, each {"job_id": <int>}. Mutually
exclusive with the filter-mode params.
organization_ids: Filter mode: Sumble organization ids to
search within (at most 1000).
organization_list_id: Filter mode: id of one of the user's
saved organization lists.
query: Filter mode: advanced query string. See QUERY SYNTAX.
attributes: Job attributes to return (the free ones are
always included).
related_people: Optional related-people selection.
limit: Max results, filter mode only (1-200, default 10).
offset: Skip N results, filter mode only (default 0).
Lookup Job Titles
Look up likely job function and level for job titles.
Use this when you need deterministic job function and job level
identifiers for follow-up API calls. Returns one result per input
title, preserving input order. Either `job_function` or `job_level`
may be null when no confident match is available.
Costs 1 credit per 100 matched titles.
Args:
titles: Job titles to classify (e.g. "Senior Software Engineer",
"Director of Sales").
reason: Why you are calling this tool.
Find Match And Enrich Organizations
Find, match, and enrich organizations in one call.
This is the primary organizations tool. It resolves
organizations and returns the exact baseline attributes
and per-entity metrics you ask for.
Provide EXACTLY ONE of:
- organizations: a list of companies to resolve (match)
by id, slug, name, url, and/or location, OR
- query: an advanced-query string that selects
organizations (search / filter mode).
If results include URLs or links, always share them
with the user.
WHAT YOU GET BACK
Each result row echoes its input and includes:
- attributes: the baseline company fields you requested
(null if the org could not be matched), and
- entities: one result block per entity selection, with
the requested metrics (and deep-link URLs).
INPUT — organizations (match mode)
A list of up to 1000 dicts. Each dict needs at least one
of:
- id: Sumble organization id (int) — bypasses matching
- slug: Sumble slug (str) — bypasses matching
- name: company name (str)
- url: website or domain (str)
- location: country name or code (str, optional;
improves matching accuracy)
Example: [{"name": "Sumble", "url": "sumble.com"},
{"id": 1726684}]
INPUT — query (search / filter mode)
An advanced-query string (syntax below). Use limit/offset
to page and order_by_column/order_by_direction to sort.
order_by is ONLY valid in this mode.
Special sorts:
- "people_concentration": all-time fraction of the org's
tracked people in one job function. REQUIRES
order_by_job_function (a job function name, e.g.
"Data Engineer"; 400 if unknown).
- "people_count_growth_1y": current YoY % growth of the
org's people in one job function (latest month vs. one
year earlier); orgs without growth data sort last in
both directions. REQUIRES order_by_job_function.
- "job_post_concentration": all-time fraction of the
org's job posts matching a second advanced query.
REQUIRES order_by_advanced_query (advanced-query syntax
below, restricted to technology, technology_category,
job_function, project, job_level, country; no excludes).
The sort query only orders results — it does NOT filter
them; orgs with no matching jobs sort as 0.
The webapp cannot reproduce these orderings, so the
response has no source_data_url for these sorts.
SELECT — attributes
A list of baseline fields to return. The free fields
(id, name, slug, url, sumble_url) are ALWAYS returned automatically —
you only need to list the paid attributes you want here.
Each of these costs 1 credit per matched org:
employee_count, industry, jobs_count, teams_count, headquarters_country, sumble_score, parent_id, subsidiary_ids, tags, funding_total_raised, funding_valuation, funding_last_round_raised, funding_last_round_type, funding_last_round_date.
`sumble_score` is Sumble's proprietary account-fit score
for the CURRENT user's company / ICP (see caveat below).
SELECT — entities
A list of per-entity metric selections. Each entity is a
dict:
- type (required): one of technology, job_function,
project, technology_category, advanced_query
- term (required): the slug / name / category slug /
advanced-query string for that type
- metrics (required): a list of metric names valid for
the type, or the string "all"
- granularity: REQUIRED for technology_category (and only
valid there). "aggregate" rolls the category up into
one set of counts; "exploded" returns per-component-
technology counts (and multiplies cost by the number
of component technologies).
- since: optional YYYY-MM-DD; scopes job_post_count,
job_post_used_count, team_count, and people_count to
activity on/after this date. Does not affect *_growth_1y.
Valid metrics by type:
- technology: job_post_count, job_post_used_count,
people_count, team_count, job_post_count_growth_1y
- job_function: job_post_count, team_count, people_count,
people_count_growth_1y, job_post_count_growth_1y,
people_concentration (fraction 0-1 of the org's tracked
people in the job function; `since` scopes both the
matching and total people counts)
- project: job_post_count, team_count
- advanced_query: job_post_count, team_count, people_count,
job_post_concentration (fraction 0-1 of the org's job
posts matching the query; `since` scopes both the
matching and total job counts)
- technology_category: job_post_count, people_count,
team_count, job_post_count_growth_1y (growth available
only with granularity "exploded")
Entity examples:
- {"type": "technology", "term": "kubernetes",
"metrics": "all"}
- {"type": "technology_category", "term": "gen-ai",
"metrics": ["job_post_count"], "granularity": "aggregate"}
- {"type": "job_function", "term": "Data Engineer",
"metrics": ["people_count"], "since": "2024-01-01"}
TECHNOLOGY CATEGORY SLUGS (commonly used):
crm, business-intelligence, cloud-data-warehouse,
data-catalog, gen-ai, mlops, ml-training,
cybersecurity, cloud-security, ci-cd, ipaas,
event-streaming, data-pipeline-orchestration, etl,
logging-observability-monitoring,
data-quality-and-observability,
customer-data-platform,
feature-flagging-and-a-b-testing,
vector-database, oss-data-science,
commercial-data-science,
infrastructure-as-code-tools, design,
javascript, siem, edr, headless-cms,
ccaas, endpoint-management, ecommerce-platform,
vibe-coding,
marketing-automation-platforms, frontier-ai-models,
processing-units-and-chips,
cloud-and-container-orchestration-platforms,
identity-and-access-management
ADVANCED QUERY SYNTAX (used for the `query` param and for
`advanced_query` entity terms):
Operators: EQ, NEQ, IN, NOT IN.
Combine with AND, OR. Group with parentheses.
Values are single-quoted. IN/NOT IN use
comma-separated values in parens.
LIMITATION: negation (NEQ / NOT IN) is only
supported on industry, hq_location and
organizations_list (as listed per field below).
Negating any other field (e.g. technology)
fails the whole query with 400 Invalid query.
Available fields:
- technology — EQ/IN only (no NOT IN). Use slugs
from SearchTechnologies.
- technology_category — EQ/IN only (no NOT IN).
Slugs from the list above.
- organization — EQ only. Fuzzy name/URL match.
- organizations_list — EQ/IN/NOT IN. Values are
numeric organization-list IDs as single-quoted strings
(e.g. '12345'). Use this field to search orgs within a
user's accounts, which can be retrieved via ListOrganizationLists.
Use 'default' for the user's default list.
Important: organizations_list must be a top-level clause,
not nested within another clause/parentheses.
- industry — EQ/IN/NOT IN.
- employee_count — EQ/IN. Range format:
'100-1000', '1000-' (1000+), '-500' (up to 500).
- hq_location — EQ/IN/NEQ. Format:
'US', 'US:Texas', 'US:Texas:Austin'.
Use full state names, not abbreviations.
'UK' is auto-converted to 'GB'.
Region codes: EMEA, APAC, NAMER, LATAM,
Americas, Europe, MiddleEast, Africa.
- tag — EQ/IN. Valid slugs: 'is_ai_native', 'b2b', 'b2c', 'digital_native', 'freelancing', 'org_type_government', 'org_type_hospital', 'it_services', 'org_type_k12_school', 'org_type_nonprofit', 'is_private_equity_firm', 'is_private_equity_owned', 'professional_services', 'is_public_company', 'org_type_recruitment_agency', 'is_soe', 'org_type_university', 'is_venture_backed'.
Tags are curated, exact-match labels. When
the user's intent maps to one of these tags
(e.g. "digital native companies" →
'digital_native'), use the tag field rather
than industry, SIC code, or free-text terms.
- sic_code — EQ (e.g. '7371').
- naics_code — EQ (e.g. '541511').
- funding_last_round_type — EQ/IN only (no
NEQ/NOT IN).
Values: 'pre_seed', 'seed', 'series_a' through
'series_h', 'series_h_plus', 'debt', 'grant',
'convertible_note', 'private_equity'.
'series_h_plus' is a virtual value that matches
Series I and beyond (series_i..series_z under the
hood). Raw 'series_i'..'series_z' are NOT accepted
as filter values — use 'series_h_plus' instead.
- funding_last_round_year — EQ. Range format like
employee_count: '2022-2025', '2023-', '-2020'.
- funding_last_round_raised — EQ. USD amount raised
in the most recent round. Range format:
'1000000-50000000', '100000000-', '-5000000'.
- funding_total_raised — EQ. Range format in USD:
'1000000-50000000', '100000000-', '-5000000'.
- funding_valuation — EQ. Post-money valuation in
USD. Range format:
'10000000-1000000000', '1000000000-', '-50000000'.
- primary_<category> — EQ/IN only (no NOT IN).
Filter by an org's primary (dominant) technology
within a specific category. Field name is "primary_" + the
category slug with hyphens replaced by underscores.
Examples:
cloud-vendor -> primary_cloud_vendor
cloud-data-warehouse -> primary_cloud_data_warehouse
Values are technology slugs.
Use '__none__' to find orgs with NO primary tech
in a category.
Only use when the user expresses dominance
intent ("primary", "main", "standardized on").
Must be combined with a matching technology_category clause,
or a technology clause whose technology belongs to that
same category.
IMPORTANT: Do NOT combine org filters with job
filters (job_function, job_level, country) using OR.
Query examples:
- technology IN ('snowflake', 'databricks')
AND employee_count EQ '1000-'
- hq_location IN ('US:California', 'US:New York')
- hq_location EQ 'EMEA'
- technology EQ 'kubernetes'
AND hq_location EQ 'US' AND
employee_count EQ '1000-5000'
- industry NOT IN ('Recruiting and Staffing')
- organizations_list IN ('12345', '67890')
- technology_category EQ 'cloud-data-warehouse'
AND primary_cloud_data_warehouse EQ 'snowflake'
Note: this tool is not the same as `ListOrganizationLists`
and `GetOrganizationList`. Those tools are specifically for
retrieving a user's accounts, and are good in combination
with this tool (search within accounts via the
`organizations_list` filter field).
COST
Total = matched_count × per-org cost. Per-org cost =
1 (base) + 1 per paid attribute + (metric count ×
explosion) per entity. `metrics: "all"` counts as every
metric for that type; an exploded technology_category fans
out by its component-tech count. This can get expensive —
confirm with the user before large org lists or many
attributes/entities.
ACCOUNT SCORE CAVEAT
`sumble_score` (and ordering by account_score) is a
proprietary score reflecting fit to the CURRENT user's
company, products, and ICP.
Args:
reason: Why you are calling this tool.
organizations: List of org dicts to resolve (match
mode). Mutually exclusive with `query`. Max 1000.
query: Advanced-query string selecting orgs (filter
mode). Mutually exclusive with `organizations`.
attributes: Baseline fields to return (see
SELECT — attributes).
entities: Per-entity metric selections (see
SELECT — entities).
limit: Max results, 1-200 (filter mode only; default 10).
offset: Results to skip, 0-10000 (filter mode only;
default 0).
order_by_column: Column to sort by (filter mode only).
order_by_direction: 'ASC' or 'DESC' (filter mode only).
order_by_job_function: Job function name whose people
metrics drive the sort. Required with (and only
valid with) order_by_column "people_concentration"
or "people_count_growth_1y".
order_by_advanced_query: Advanced query whose matching
job posts form the sort numerator. Required with
(and only valid with) order_by_column
"job_post_concentration".
Get Intelligence Brief
Get a sales intelligence brief for a target account.
The brief is LLM-generated: it is a natural-language sales narrative
synthesized by Google Gemini from Sumble's structured data (technology,
people, team, and signal records). Treat it as an AI-written summary —
it may phrase, infer, or emphasize beyond the underlying records.
Use this when the user asks for account research, sales prep,
prospecting angles, who to contact, relevant technology signals,
team fit, or recent changes at a company. The brief is written for
the user's own company/domain, so it explains why this target
account may matter to the user's GTM motion.
The response includes a Markdown body and a Sumble URL. The body
combines sections such as: What's the Angle, Who To Contact First,
The Intel, Which Teams Are The Best Fit, and Recent Changes. If the
response includes `sumble_url`, share it with the user.
This tool requires a Sumble organization ID. If the user gives a
company name, domain, or slug, first use
FindMatchAndEnrichOrganizations to resolve it to an organization ID.
While a brief is being generated, the MCP tool result will
have `status` set to "pending", `upstream_status_code: 202`,
and a `retry_after_seconds` integer (typically 20 seconds). In that
case, you should retry after the specified time to get the completed
brief.
If it's possible for you to do the retry on the user's behalf,
that would be a better experience than asking the user to do it manually.
If so, update the user that the brief is being generated, that you
are waiting on results, and what they should expect.
No credits are consumed for pending responses, you can safely retry
until you get a completed brief.
Costs 50 credits when a completed brief is returned.
Args:
reason: Why you are calling this tool.
organization_id: The ID of the organization to get an intelligence brief for.
Get Organization Signals
Get recent sales signals (notable changes) for a target account.
Organization signals are timely, sales-relevant events Sumble has detected
at an organization — for example new hires using a tracked technology,
leadership/champion moves, hiring trends for a job function, or
technology adoption trends. Use this when the user asks what's
recently changed at a company, for prospecting triggers, "why reach
out now" angles, or recent activity worth a sales touch.
This tool requires a Sumble organization ID. If the user gives a
company name, domain, or slug, first use `FindMatchAndEnrichOrganizations`
to resolve it to an organization ID.
Each signal includes a human-readable title/subtitle, an optional
sales angle, the signal date, a deep-link `sumble_url`, and
structured fields where applicable (organization, job post, person,
location, job function, and priority).
Use `sumble_url` as the primary link to the signal for users to click on
for more details. The Sumble page includes the full signal explanation,
and will include links to the underlying data (e.g. job post, person profile).
Where relevant, the response includes a `person_id`, which refers to
the individual associated with the signal (e.g. a promotion or champion move).
You can use `person_id` with MCP tools such as `FindMatchAndEnrichPeople`
for further research on that individual.
Where relevant, the response includes a `job_post_id`, which refers to
the job post associated with the signal (e.g. technology and project mentions).
You can use `job_post_id` with MCP tools such as `FindMatchAndEnrichJobs`
for further research on that job post.
Optionally, filter signals by technology, by passing technology slugs in
`technology_slugs`. Use `SearchTechnologies` for technology discovery
or `LookupTechnologies` to resolve names, slugs, or aliases to canonical
slugs. Empty or blank values are ignored.
COST
Costs 1 credit per signal returned.
Args:
reason: Why you are calling this tool.
organization_id: The ID of the organization to get signals for.
technology_slugs: Optional technology slugs to filter signals by.
Find Match And Enrich People
The primary people tool: resolve people
and return exactly the attributes you ask for, with optional related
people and contact reveals.
INPUT — provide EXACTLY ONE of:
- `people` (match mode): up to 1000 entries, each identified by any of
`person_id`, `linkedin_url`, and/or `email` (precedence: person_id >
linkedin_url > email). One result row per entry, in input order;
entries that don't match come back with just their input echoed and
cost nothing.
- Filter mode: `organization_ids` and/or `organization_list_id`
(REQUIRED — people queries are organization-scoped; resolve names or
domains to ids with FindMatchAndEnrichOrganizations first, whose free
attributes include `id`) plus an optional `query` (see QUERY SYNTAX).
`limit`/`offset` apply to filter mode only.
SELECT — `attributes`. Every row always includes person_id, name, and a
sumble_url deep link for free. Paid attributes (1 credit each per
returned person): linkedin_url, job_title, job_function, job_level,
location, country, current_employer (the employer org with its Sumble
organization_id, start date, and link), technologies (from the
person's profile skills, normalized to Sumble's technology catalog,
as name+slug objects), person_score (see below).
PERSON SCORE — `person_score` (1 credit) rates each person 0-100
against the user's ideal customer profile (ICP), with skill,
job-function, and seniority contributions plus the matched
technologies/job functions behind them. Filter mode only, and requires
exactly ONE organization in scope and an ICP configured for the user's
account — requests that don't meet this fail with a 400 explaining why.
When selected, results come back ordered by the score, best leads
first. Use it to rank the people at a target account.
CONTACT REVEALS — `email` (10 credits) and `phone` (80 credits) are also
selectable attributes, charged once per person on the first successful
reveal; repeat reveals and not-found lookups are free. Match mode only,
at most 25 people per request.
EMAIL IDENTIFIERS — an entry identified only by email is resolved via
reverse enrichment: +20 credits when it resolves to a returned person,
free otherwise. At most 25 people per request when used.
RELATED PEOPLE — pass `related_people` as {"direction": ["managers"
and/or "direct_reports"], "attributes": [...]} to also get people up or
down the org hierarchy for each matched person. Match mode only, at most
25 people per request, 1 credit per related person returned.
Relationships are INFERRED from org structure and seniority signals, not
actual reporting lines. Related people support the same attributes
except email/phone and person_score.
COST — total = matched_count x (1 + paid attributes) + related people
+ contact reveals + email resolutions. The API checks affordability up
front and returns an error before doing any work the user can't pay for.
Always share sumble_url links with the user.
JOB FUNCTIONS (top-level categories with children):
- Executive, Board of Directors
- Engineering & R&D: Data Analyst, Statistician,
Data Scientist, Machine Learning (incl. MLOps
Engineer), AI Engineer, Researcher, Engineer
(Software Engineer, Security Engineer, DevOps
Engineer, Data Engineer, Site Reliability Engineer,
Cloud Engineer, etc.), Applied Scientist, Scientist
- Product & Design: Product Manager, Designer (UX,
Visual, Brand, etc.)
- Strategy & Operations: Analyst, Strategy, Operations
(Program Manager, Procurement & Supply Chain)
- Information Technology: IT Support, IT Security,
Business Systems, etc.
- Healthcare Services: Physician, Nurse, Pharmacist
- Sales: Account Executive, SDR
- Marketing: Product Marketing, Growth, Content,
Digital Marketing
- Customer Support, Customer Success, Solutions
- Revenue Operations (GTM Engineer)
- Business Development
- General & Administrative: Finance (Accountant,
Financial Analyst), Legal & Compliance, Human
Resources, Administrator
- Consultant, Government, Education, Journalist
JOB LEVELS (highest to lowest rank):
Board Member, CXO, EVP, CVP, SVP, RVP, AVP, VP,
Executive Director, Senior Director, Director,
General Manager, Head, Associate Director,
Senior Manager, Manager, Principal, Lead, Senior,
Individual Contributor
QUERY SYNTAX (use `query` param):
Operators: EQ, NEQ, IN, NOT IN.
Combine with AND, OR. Group with parentheses.
Values are single-quoted. IN/NOT IN use
comma-separated values in parens.
Available fields:
- job_function — EQ/IN/NOT IN. Use values from
the JOB FUNCTIONS list above.
- job_level — EQ/IN/NOT IN. Use values from
the JOB LEVELS list above.
- country — EQ/IN/NOT IN. Format:
'US', 'US:California',
'US:California:San Francisco'.
Use full state names, not abbreviations.
'UK' is auto-converted to 'GB'.
- technology — EQ/IN/NOT IN. Use slugs from
SearchTechnologies.
- since — EQ ONLY. ISO date format:
'2023-01-01'. Returns people with data
since that date.
- hiring_period — EQ ONLY. Predefined buckets:
'2wk', '1mo', '3mo', '6mo', '1yr', '18mo', '2yr'.
Alternative to `since` for relative ranges.
- person_name — EQ.
- NOTE: job_title and job_description are NOT
available as filters. Use job_function and
job_level.
Examples:
- ML engineers in the US:
job_function IN ('Machine Learning',
'AI Engineer') AND job_level IN ('Senior',
'Lead') AND country EQ 'US'
- Data scientists in California:
job_function EQ 'Data Scientist'
AND country EQ 'US:California'
- Senior PyTorch users:
technology EQ 'pytorch'
AND job_level EQ 'Senior'
- Recent engineering hires:
job_function EQ 'Engineer'
AND since EQ '2026-01-01'
- VPs in the UK:
job_level EQ 'VP'
AND country EQ 'UK'
Args:
reason: Why you are calling this tool.
people: Match mode entries. Mutually exclusive with the
filter-mode params.
organization_ids: Filter mode: Sumble organization ids to
search within (at most 1000 combined with the list).
organization_list_id: Filter mode: id of one of the user's
saved organization lists.
query: Filter mode: advanced query string. See QUERY SYNTAX.
attributes: Person attributes to return (the free ones are
always included).
related_people: Optional related-people selection.
limit: Max results, filter mode only (1-200, default 10).
offset: Skip N results, filter mode only (default 0).
Lookup Projects
Look up project IDs, slugs, and names from project names or slugs.
Use this when you need deterministic project identifiers for
follow-up API calls. Returns one result per input, preserving
input order. Unmatched inputs return `project: null`.
Costs 1 credit per 100 matched projects.
Args:
projects: Project names or slugs to resolve
(e.g. "cloud migration", "generative_ai").
reason: Why you are calling this tool.
Search Signals
Search Sumble Signals by account, person, technology, job function, or list.
Signals are timely, sales-relevant events Sumble has detected across
accounts - for example champion movements, recent hires and promotions,
technology and product mentions, projects and initiatives, and technology
or job-function trends. Use this when the user asks for a filtered signal
feed across many accounts, recent account changes, or prospecting
triggers matching technologies, job functions, people, or account lists.
Each signal includes a `signal_id`, a human-readable title/subtitle, an
optional sales angle, the signal date, a deep-link `sumble_url`, and
structured fields where applicable (organization, job post, person,
matched technologies, location, job function, and priority). Always share
useful `sumble_url` links with the user.
Where relevant, the response includes a `person_id`, which refers to the
individual associated with the signal (for example a promotion, recent
hire, or champion move). Use `FindMatchAndEnrichPeople` for further
research on that individual.
Where relevant, the response includes a `job_post_id`, which refers to the
job post associated with the signal. Use `FindMatchAndEnrichJobs` for
further research on that job post.
Job-post signals (technology and product mentions, projects, and first
mentions) also include `suggested_contacts`: the top few people to consider
reaching out to at the account, ranked by a relevance `score` from 1 to 10
(highest first), each with a `person_id`, name, title, and LinkedIn URL,
plus a `sumble_url` to see all matches. Use `FindMatchAndEnrichPeople` to
research a suggested contact further.
Filters are combined with AND. Values inside each filter array are combined
with OR (like IN).
COST
Costs 1 credit per signal returned. Searches with no returned signals do
not consume credits.
Args:
reason: Why you are calling this tool.
filter: Filter criteria for the signals search. Filters are combined
with AND; values inside each filter array are combined with OR.
Supported filters: organization_ids, person_ids, signal_ids,
technology_slugs, job_functions, priorities, and account_list_ids.
Search Priority Signals
Search the user's priority signals by source signal and entity IDs.
Priority signals summarize and contextualize the most
important signals in the user's account feed. Use this when the user
asks for priority signals, or to enrich other search results,
especially when focused on an organization, person, or job post.
Each result includes a web app URL, item headline/content, date, source
`signal_ids`, and searchable `organization_ids`, `person_ids`, and `job_post_ids`.
Returns the most recent 20 priority signals based on the specified filters,
or omit filters to simply return the latest.
Filters are combined with AND. Values inside each filter array are combined
with OR (like IN).
COST
Costs 1 credit per priority signal returned. Searches with no returned
priority signals do not consume credits.
Args:
reason: Why you are calling this tool.
filter: Filter criteria for the priority signals search. Supported
filters: organization_ids, person_ids, signal_ids, and job_post_ids.
Report Data Quality Issue
Report a data quality issue (e.g. wrong/missing/stale Sumble data).
Sends the report to the Sumble data team for triage. They may
follow up at the account's email address. Free (no credits used).
Args:
reason: Why you are calling this tool.
message: Description of the data quality issue. Be specific
about what is wrong and what you expected instead.
url: The Sumble URL the issue relates to, if any.
page_title: The title of the Sumble page the issue relates
to, if any.
Submit Support Request
Submit a general support request to the Sumble team.
Use this for account, billing, or product questions that
aren't a data quality issue -- use report_data_quality_issue
for those instead. Free (no credits used).
Args:
reason: Why you are calling this tool.
message: Description of the support request.
url: The Sumble URL the request relates to, if any.
Search Technologies
Search for technologies by name.
Returns technology slug, name, and mention count.
Use this first to find valid technology slugs for use in
FindMatchAndEnrichOrganizations, FindMatchAndEnrichJobs, and
FindMatchAndEnrichPeople.
The returned slugs can also be used in advanced
queries with `technology IN ('slug1', 'slug2')`.
Costs 1 credit per search.
Args:
query: Search term (e.g. "react", "kubernetes",
"snowflake", "pytorch")
reason: Why you are calling this tool.
Lookup Technologies
Look up technology IDs, slugs, and names from names, slugs, or aliases.
Use this when you need deterministic technology identifiers for
follow-up API calls. Returns one result per input, preserving
input order. Each matched technology also includes the tech
categories it belongs to. Unmatched inputs return `technology: null`.
Costs 1 credit per 100 matched technologies.
Args:
technologies: Technology names, slugs, or aliases to resolve
(e.g. "GCP BigQuery", "windows azure", "react").
reason: Why you are calling this tool.
Lookup Technology Categories
Look up technology categories and the technologies they contain.
Given category slugs or names, returns each category's slug, name, and
short name, plus the id, slug, and name of every technology in it.
Technologies mentioned most often in job postings appear first. Use this
to enumerate the technologies that make up a category.
Returns one result per input, preserving input order. Unmatched inputs return
`category: null`.
Costs 1 credit per 100 matched categories.
Args:
technology_categories: Technology category slugs or names to resolve
(e.g. "cloud-vendor", "Cloud Data Warehouse", "OLAP").
reason: Why you are calling this tool.
Run Sql Query
Execute a read-only SQL query against the Sumble DuckDB analytics
database.
Use this tool only when the structured search tools cannot express
the user's question — for example, custom aggregations, joins
across tables, or columns not exposed by those tools. For routine
entity lookups (companies, people, jobs, technologies), use the
structured tools listed below; they handle those cases directly.
Structured tools that cover most questions:
- FindMatchAndEnrichOrganizations: search/filter or resolve
companies (by name, industry, technology, location, size, etc.)
and enrich them with technology, job-function, project, and
people metrics.
- FindMatchAndEnrichJobs: look up jobs by id or search job postings
by org, technology, job function, location, etc.
- FindMatchAndEnrichPeople: resolve people by id/LinkedIn/email or
search people by org, job function, seniority, location, etc.
- SearchTechnologies: look up technologies by name/keyword.
Sumble users are typically sales professionals, not SQL-literate.
Do not surface the raw SQL — restate the answer in plain language
along with the filters your query applied, so the user can confirm
it matches what they asked.
Args:
sql: The read-only SQL query to execute.
reason: A short explanation of what you are trying to find.
TIPS:
- Call ListTables first to discover tables, columns, and their
descriptions.
- JSON cols use DuckDB syntax: json_keys(), ->> operator.
- Read-only, 30s timeout, max 1,000 rows. Use LIMIT.
- Costs 1 credit per 100 bytes of response data.
List Tables
List all available tables and their columns in the DuckDB.
Returns table names with column names and types for each table.
Use this to understand the schema before writing queries.
Free (no credits used).
Args:
reason: Why you are calling this tool.
Get Started