# 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](https://publicwww.com/docs/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](https://publicwww.com/prices.html) 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](https://publicwww.com/docs/search/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](https://publicwww.com/docs/api/requests/):

- `truncated` - the plan cut the page short;
- `index_complete: false` - part of the index did not answer, so `total` may be low;
- `total_exact: false` - the search hit its time limit: `total` counts 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 or `site:` finishes in time;
- `total_capped: true` - more than a million found; `total` stops 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. With `like:` results go by similarity instead;
- `query_note` - appears with `like:` (`total` counts 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, or `like:` has nothing to compare with), and when it was rewritten - other engines' syntax, a `site:` domain or letters in another alphabet: then `original_query` is the query as sent and `query` the one run. Characters that only separate words get no note: Blumengeschäft is searched as blumengesch ft - see [Languages](https://publicwww.com/docs/languages/);
- `sites` - only with `depth:`, where `total` counts pages: the distinct websites among them, a lower bound when `sites_exact` is 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](https://publicwww.com/docs/mcp/limits/).

## 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](https://publicwww.com/docs/mcp/limits/).

## 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](https://publicwww.com/docs/clusters/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](https://publicwww.com/docs/api/clusters/).

Source: https://publicwww.com/docs/mcp/tools/
