> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentlinkops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discovery tools

> Inputs, access and errors for 7 registered discovery tools.

Generated 2026-09-13T03:11:22.248Z from `src/tool-registry.js` by `scripts/export-mint-tool-docs.mjs`. 7 of 62 registered tools. Authenticated cloud tools have REST endpoints under `/v1/`. The anonymous `verify_link_free` tool uses `POST /free/check` and `/free/mcp`.

## verify\_discovery\_candidate

Request an asynchronous check of one saved discovery candidate. Returns a verification record and queued job with immutable lineage. Requires an idempotency key; consumes check allowance when executed. Does not establish a verified result synchronously.

* **State**: Registered and locally tested.
* **Access**: write · scope: `discovery:read, watches:write` · defined at `src/tool-registry.js:43`

| Input            | Type   | Required | Notes                                                                                               |
| ---------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `runId`          | string | yes      | Identifier of the run returned by its create or list operation.                                     |
| `candidateId`    | string | yes      | Identifier of the candidate returned by its create or list operation.                               |
| `localReference` | string | no       | Customer-owned reference to associate this record with a local ledger entry.                        |
| `idempotencyKey` | string | yes      | Caller-generated key reused only for retries of the same operation and arguments in this workspace. |

**Side effects**: write; dispatchOutbox(jobId)

**Error codes**: `CANDIDATE_VERIFICATION_NOT_FOUND` · `CHECK_COOLDOWN` · `DISCOVERY_CANDIDATE_NOT_FOUND` · `IDEMPOTENCY_CONFLICT` · `INVALID_CANDIDATE_VERIFICATION_INPUT` · `WATCH_BUSY`

## request\_domain\_overview

Request a separately metered supplier summary for a domain or subdomain. Admission is disabled in this build. Summaries carry their data mode and provider provenance; they are not link checks or totals derived from selected candidates.

* **State**: Admission-gated: refuses live with `true`
* **Access**: write · scope: `discovery:write` · defined at `src/tool-registry.js:47`

| Input                      | Type    | Required | Notes                                                                                                  |
| -------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `projectId`                | string  | yes      | Identifier of the project returned by its create or list operation.                                    |
| `target`                   | string  | yes      | Exact URL or domain to query, interpreted according to targetKind.                                     |
| `includeSubdomains`        | boolean | yes      | Include subdomains of the selected domain in this query.                                               |
| `includeIndirectLinks`     | boolean | yes      | Include indirect supplier-reported links where supported.                                              |
| `excludeInternalBacklinks` | boolean | yes      | Exclude supplier rows linking within the queried site.                                                 |
| `backlinksStatus`          | string  | yes      | Supplier-reported backlink status filter; this is not Linktrail verification.; one of: live, lost, all |
| `idempotencyKey`           | string  | yes      | Caller-generated key reused only for retries of the same operation and arguments in this workspace.    |

**Side effects**: write

**Error codes**: `INVALID_OVERVIEW_INPUT` · `OVERVIEW_RUN_NOT_FOUND` · `PROVIDER_DISABLED` · `PROVIDER_NOT_CONFIGURED`

## get\_domain\_overview

Read a stored domain overview, dated provider provenance and separate overview usage. Missing counts remain null; reads never purchase another request.

* **State**: Registered and locally tested.
* **Access**: read · scope: `discovery:read` · defined at `src/tool-registry.js:48`

| Input   | Type   | Required | Notes                                                           |
| ------- | ------ | -------- | --------------------------------------------------------------- |
| `runId` | string | yes      | Identifier of the run returned by its create or list operation. |

**Error codes**: `INVALID_OVERVIEW_INPUT` · `OVERVIEW_RUN_NOT_FOUND` · `PROVIDER_DISABLED` · `PROVIDER_NOT_CONFIGURED`

## discover\_backlinks

Request bounded backlink candidates. Discovery admission is disabled in this build; stored synthetic acceptance uses a separate discovery meter. Reuse the idempotency key. Candidates are not verified links and are not enrolled in monitoring.

* **State**: Admission-gated: refuses live with `true`
* **Access**: write · scope: `discovery:write` · defined at `src/tool-registry.js:73`

| Input                      | Type    | Required | Notes                                                                                                  |
| -------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `projectId`                | string  | yes      | Identifier of the project returned by its create or list operation.                                    |
| `targetKind`               | string  | yes      | Whether target identifies an exact URL or a domain.; one of: domain, exact\_url                        |
| `target`                   | string  | yes      | Exact URL or domain to query, interpreted according to targetKind.                                     |
| `includeSubdomains`        | boolean | yes      | Include subdomains of the selected domain in this query.                                               |
| `backlinksStatus`          | string  | yes      | Supplier-reported backlink status filter; this is not Linktrail verification.; one of: live, lost, all |
| `excludeInternalBacklinks` | boolean | yes      | Exclude supplier rows linking within the queried site.                                                 |
| `pageLimit`                | integer | yes      | Maximum supplier rows requested per page, within the total row limit.                                  |
| `rowLimit`                 | integer | yes      | Maximum total supplier rows admitted for this discovery run.                                           |
| `idempotencyKey`           | string  | yes      | Caller-generated key reused only for retries of the same operation and arguments in this workspace.    |

**Side effects**: write

**Error codes**: `DISCOVERY_RUN_NOT_FOUND` · `INVALID_CURSOR` · `PROVIDER_DISABLED` · `PROVIDER_NOT_CONFIGURED`

## list\_discovery\_runs

Browse stored discovery runs newest first with optional project filtering and bounded cursor pagination. No provider calls, spending or enrollment.

* **State**: Registered and locally tested.
* **Access**: read · scope: `discovery:read` · defined at `src/tool-registry.js:74`

| Input       | Type    | Required | Notes                                                                       |
| ----------- | ------- | -------- | --------------------------------------------------------------------------- |
| `projectId` | string  | no       | Identifier of the project returned by its create or list operation.         |
| `cursor`    | string  | no       | Opaque continuation returned by this same listing; omit for the first page. |
| `limit`     | integer | no       | Maximum rows in this page or bounded report; subject to the schema maximum. |

**Error codes**: `DISCOVERY_RUN_NOT_FOUND` · `INVALID_CURSOR` · `PROVIDER_DISABLED` · `PROVIDER_NOT_CONFIGURED`

## get\_discovery\_run

Read stored discovery status, query coverage and separate discovery usage. This read never purchases a provider page.

* **State**: Registered and locally tested.
* **Access**: read · scope: `discovery:read` · defined at `src/tool-registry.js:75`

| Input   | Type   | Required | Notes                                                           |
| ------- | ------ | -------- | --------------------------------------------------------------- |
| `runId` | string | yes      | Identifier of the run returned by its create or list operation. |

**Error codes**: `DISCOVERY_RUN_NOT_FOUND` · `INVALID_CURSOR` · `PROVIDER_DISABLED` · `PROVIDER_NOT_CONFIGURED`

## list\_discovery\_candidates

Read up to 100 stored discovery candidates with dated provider provenance and separate verification status. Cursor pages freeze a stored result snapshot; restart without a cursor for newer results. Reads never purchase provider pages.

* **State**: Registered and locally tested.
* **Access**: read · scope: `discovery:read` · defined at `src/tool-registry.js:76`

| Input    | Type    | Required | Notes                                                                       |
| -------- | ------- | -------- | --------------------------------------------------------------------------- |
| `runId`  | string  | yes      | Identifier of the run returned by its create or list operation.             |
| `cursor` | string  | no       | Opaque continuation returned by this same listing; omit for the first page. |
| `limit`  | integer | no       | Maximum rows in this page or bounded report; subject to the schema maximum. |

**Error codes**: `DISCOVERY_RUN_NOT_FOUND` · `INVALID_CURSOR` · `PROVIDER_DISABLED` · `PROVIDER_NOT_CONFIGURED`