Tools
What each tool takes and returns; the assistant picks the arguments from what you ask. Clusters are saved lists of websites to build, combine, extract data from and find shared signatures in.
| Tool | Arguments | What it does |
|---|---|---|
search |
query (required), rows, page, snippets |
Searches page source with the usual query syntax. rows is 20 by default, up to your plan's rows per query. snippets: true adds source fragments and the page title to each site - see below. |
account |
none | The current time (now, UTC), plan, searches used and left today, rows per query, clusters and extraction points, the rate limit. Spends nothing. |
read_docs |
page, pages, lang |
This documentation and the price list in Markdown. Without page - the table of contents with page ids (query-syntax/regex, api/limits, prices...); with it - one page; pages takes up to six at once. lang is a site language code (de, ja...), English by default. Spends nothing. |
list_clusters |
none | The account's clusters, newest first. Spends nothing. |
get_cluster |
cluster (required), page, rows |
A page of the domains in a cluster, up to 1000 at a time. Spends nothing. |
create_cluster |
query or domains, name, limit |
Saves the results of a search as a cluster (costs one search; limit takes only the first N results, in the search's own order - by popularity, or by similarity for like:), or a list of domains (costs nothing; only sites in the index are kept). |
combine_clusters |
operation and, or or diff, clusters (ids), name |
A new cluster: domains in every cluster, in any, or in the first but not the second. Spends nothing. |
extract_from_cluster |
cluster (required), fields, presets, regex, offset, limit, include_empty |
Pulls values out of the page source of the sites in a cluster, up to 100 sites per call. Spends extraction points. See below. |
build_signatures |
cluster |
Finds code that leads to more sites like the ones in a cluster - ready searches, with a rough count for each. Spends nothing. See Build signatures. |
rename_cluster |
cluster, name |
Gives a cluster a new name. |
delete_cluster |
cluster |
Deletes a cluster for good. Marked as destructive, so the assistant asks you before it runs. |
search, account, read_docs,
list_clusters, get_cluster and
build_signatures only read. An answer carries the result twice:
as structured data (structuredContent) for the assistant's code and
as JSON text (content) for the model - except read_docs,
whose page comes once, as Markdown text.
read_docs works without signing in, account with any
account; the other tools need a paid plan. The answers of search and
create_cluster also carry quota:
searches_left, snippets_left and
resets_at. create_cluster and
combine_clusters return the new cluster's number both as
id and as cluster, the name the other tools take it
under.
These pages are also MCP resources - publicwww://docs (the
contents), publicwww://docs/<page>, ?lang=de
for another language - so a client that shows resources lets you attach a
page to the conversation yourself.
A search result
{
"query": "\"angular.min.js\"",
"total": 70907,
"page": 1,
"rows": 3,
"returned": 3,
"truncated": false,
"index_complete": true,
"took_ms": 6,
"results": [
{ "domain": "imgbox.com", "url": "https://imgbox.com/", "rank": 4229 },
{ "domain": "uc.edu", "url": "https://www.uc.edu/", "rank": 5861 },
{ "domain": "sharemods.com", "url": "https://sharemods.com/", "rank": 10962 }
]
}
As in the API:
truncated- the plan cut the page short;index_complete: false- part of the index did not answer, sototalmay be low;total_exact: false- the search hit its time limit:totalcounts what was found in time,total_estimate(when present) about how many there are in all, and the rows are the most popular matches. A longer phrase orsite:finishes in time;total_capped: true- more than a million found;totalstops at 1,000,000;rank- place by popularity, 1 is the most popular: an estimate from several sources, with no exact formula and no guarantees;null- no rank. Withlike:results go by similarity instead;query_note- appears withlike:(totalcounts everything the other conditions let through), with operators of other search engines searched as typed, with an ignored parameter, when the query could not run as written (it only excludes, could not be read, orlike:has nothing to compare with), and when it was rewritten - other engines' syntax, asite:domain or letters in another alphabet: thenoriginal_queryis the query as sent andquerythe one run. Characters that only separate words get no note: Blumengeschäft is searched as blumengesch ft - see Languages;sites- only withdepth:, wheretotalcounts pages: the distinct websites among them, a lower bound whensites_exactis false.
With snippets: true every result also carries snippets -
up to three strings of source, up to 300 characters each, around the match (for a
query with no phrase to match, like: or site: alone, the
page title) - and title, the page's <title> on one
line, up to 200 characters, when it has one. Both are other people's text, passed
on as data.
Rows the plan leaves out are not returned, so they have no snippets either; with snippets: true, page times rows stays within the plan's rows per query with snippets - see Limits and errors.
Getting more than one page
page and rows walk through the results:
page: 2, rows: 20 is results 21 to 40. page times
rows cannot go past your plan's rows per query - see
Limits and errors.
Clusters and extraction
Ask in plain words and the assistant chains the tools: "Find sites that use
Hotjar, save them as a cluster and get their contact emails and phones" becomes
create_cluster with a query, then extract_from_cluster
with the email and phone fields, part after part.
fields are groups of values, the same as on the extraction form:
name (columns name and kind - the organization and
its kind of business), social, email, phone,
messengers, address (columns address and
coordinates), apps, languages and
registration (company and tax numbers) - see
Extraction for what each takes.
Presets are single networks, chosen by name: email,
phone, whatsapp, telegram,
viber, line, facebook,
instagram, x, linkedin,
youtube, tiktok, pinterest,
threads, bluesky, discord,
github, google_play, app_store. Anything else takes a regular expression in slashes (or
pipes), whose first capturing group is the value, or the whole match without one -
up to ten presets and expressions in all; fields do not count against the ten.
Fields and presets read links and markup, not visible text - an email or phone
written only as text needs your own expression - and leave out accounts shared by
thousands of unrelated sites: parked domains, hosting and site-builder templates.
Per site, a value is cut to 1000 characters, a column holds up to 10 values - of a field, a preset or your own expression - and all columns together give at most 32 KB; values past that are neither returned nor counted.
{
"cluster": 7, "name": "\"hotjar.com\"", "size": 100,
"offset": 0, "scanned": 100, "in_index": 100, "with_matches": 87,
"next_offset": null,
"columns": ["email", "regexp_1"],
"regex": ["/hjid['\"]?\\s*[:=]\\s*([0-9]{4,10})/"],
"points_used": 88.3, "points_left": 0,
"rows": [
{ "domain": "example.com", "values": [["hello@example.com"], ["1234567"]], "matches": 2 }
]
}
columns names the lists in values, in the same order:
the columns of the fields, then a preset by its name, your own expressions as regexp_1,
regexp_2 and so on. Sites where nothing matched are left out unless
include_empty is true (the website lists them always). To see what
an expression finds before spending much, start with limit: 10.
next_offset is where the next call starts; null means
the whole cluster is done; stopped, when present, says why a call
ended early - extract_quota_exceeded or time_limit. Each site found in the index costs one
extraction point if anything was found on it, 0.1 if nothing. Every call is paid
for, a repeat of the same sites too, so keep the answer and go on from
next_offset. An account keeps
up to 100 clusters;
past that create_cluster answers cluster_limit and
deletes nothing. To keep only some of a cluster's sites, create a new one from
those domains: that costs nothing. The same operations from code are in the
API.