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

# Supported tools

> Use Landbase MCP to build, inspect, enrich, and download B2B prospecting datasets.

# Landbase MCP tools

Landbase MCP gives an assistant a complete workflow for B2B prospecting:

1. Choose the Landbase account.
2. Search for companies or people, or inspect an existing dataset.
3. Preview and optionally transform the dataset.
4. Match, enrich, qualify, or research rows.
5. Poll the asynchronous run and use its output dataset.
6. Publish and download the final file when needed.

The server exposes account, search, dataset, workflow, and record-matching tools. It also exposes two guided prompts and the
`landbase://capabilities` resource for clients that support those MCP features.

## How to choose a tool

| Goal | Start with | Then use |
| - | - | - |
| Build a new prospect list | `search` | `get_search_result`, `get_dataset`, `preview_dataset` |
| Find one company | `match_company` | — |
| Find one person | `match_person` | — |
| Match many rows | `match_dataset` | `get_workflow_run` |
| Add attributes | `enrich_dataset` | `get_workflow_run` |
| Ask yes/no questions per row | `qualify_dataset` | `get_workflow_run` |
| Research one question per row | `research_dataset` | `get_workflow_run` |
| Find contact details | `enrich_contacts` | `get_workflow_run` |
| Limit or select rows | `transform_dataset` | `get_workflow_run` |
| Download a dataset | `publish_dataset` if required | `get_download_url` |
| Upload a small CSV/JSONL file | `upload_dataset` | `get_dataset`, `preview_dataset` |
| Inspect authoritative fields | `get_dataset_fields` | — |
| Trace dataset provenance | `get_dataset_lineage` | — |

Use the typed workflow tools when one matches the task. Use `run_workflow` when
you need one of the less common workflow types or need to pass workflow-specific
parameters not covered by a typed tool.

## Account context

### `list_accounts`

Returns the signed-in user, the Landbase accounts they belong to, and the
current default account when one exists.

Call this first when the user might belong to multiple accounts:

```json theme={null}
{}
```

Example result:

```json theme={null}
{
  "user": {"email": "ada@example.com", "name": "Ada Lovelace"},
  "accounts": [
    {"id": "447", "name": "GTM", "role": "Owner", "wallet_status": "active"}
  ],
  "default_account_id": "447"
}
```

If more than one account is returned, ask the user which account to use.
Once selected, pass its string `account_id` on **every account-scoped call**,
including reads, writes, polling, recovery, confirmation calls, and downloads.
The server does not retain the selection between calls. A dataset ID, run ID,
or search handle does not replace account context.

The request examples below use `"account_id": "447"`; replace it with the
chosen account ID. `list_accounts` itself has no `account_id` argument. Response
examples may omit account context, but follow-up calls must still include it.
Never guess or silently choose an account.

### `get_credit_balance`

Returns the current credit balance for the selected account:

```json theme={null}
{"account_id": "447"}
```

Keep the selected `account_id` on subsequent calls even when the result does
not repeat it.

## Building prospect lists

### `search`

Builds a company or people dataset from a natural-language request.

Important inputs:

* `query` — what to find, in plain language.
* `mode` — `default` builds a list; `research` handles SQL-style questions and
  aggregations.
* `session_id` — reuse the session ID from an earlier search to refine that
  search instead of starting an unrelated conversation.
* `wait_seconds` — wait up to 40 seconds for a result before returning a
  running handle.
* `account_id` — selected Landbase account; keep it on follow-up calls.

Example:

```json theme={null}
{
  "query": "VPs of Sales at B2B SaaS companies in Texas with 50-200 employees",
  "mode": "default",
  "wait_seconds": 40,
  "account_id": "447"
}
```

A completed result includes an answer and usually a `dataset_id`:

```json theme={null}
{
  "status": "completed",
  "session_id": "4f2d...",
  "dataset_id": "ds-abc123",
  "answer": "Found companies matching the request."
}
```

Searches can outlive an MCP client's tool-call timeout. In that case the first
response is a running handle:

```json theme={null}
{
  "status": "running",
  "handle": "srch_<opaque-handle>",
  "session_id": "4f2d..."
}
```

Do not submit the same query again while it is running. To refine a completed
search, call `search` with its `session_id`, the selected `account_id`, and a
new query.

Research mode can finish its first turn with a SQL proposal and credit quote
but no dataset. After user approval, call `search` with `query: "confirm"`,
`mode: "research"`, and the original `session_id` and `account_id`. Do not pass
`confirm: true` to `search`; it has no such argument. See
[Research search approval](https://www.landbase.com/docs/guides/mcp/limits-and-credits.md#research-search-approval).

### `get_search_result`

Polls a running search using the opaque `handle` returned by `search`.
`wait_seconds` may be 0-40. Call it again while the result has
`status: "running"`, passing the same `account_id` on every poll.

```json theme={null}
{
  "handle": "srch_<opaque-handle>",
  "wait_seconds": 40,
  "account_id": "447"
}
```

The handle is safe to pass to a later MCP connection; do not decode or modify
it. If the search completes with a workflow ID, poll that workflow separately
with `get_workflow_run` and the same `account_id`.

## Agent-run status and recovery

Search results can include an `agent_run_id`. Keep it alongside the search
handle and session ID. These tools inspect existing runs; they do not start a
new search.

### `get_agent_run`

Read one status snapshot by exact run ID:

```json theme={null}
{"run_id": "agent-run-123", "account_id": "447"}
```

### `wait_for_agent_run`

Wait up to 40 seconds for an exact run:

```json theme={null}
{"run_id": "agent-run-123", "wait_seconds": 40, "account_id": "447"}
```

An `outcome` of `wait_expired` means the local wait ended while the operation
may still be running. Call `wait_for_agent_run` again with the same run ID and
`account_id`. Terminal outcomes are `completed`, `failed`, and `cancelled`.
If the result includes a `workflow_run_id`, inspect that workflow with
`get_workflow_run` and the same `account_id`.

### `list_agent_runs`

Recover the runs associated with the original session when a trigger response
was lost:

```json theme={null}
{
  "session_id": "00000000-0000-4000-8000-000000000001",
  "agent": "fast_dataset_creator",
  "account_id": "447"
}
```

Use the real session ID from the original operation. The `agent` can be
`fast_dataset_creator`, `advanced_dataset_creator`, or `tam_map_creator`; select
the agent that started the run, rather than assuming every session is a default
search. Default search uses `fast_dataset_creator`; research search uses
`advanced_dataset_creator`.

### `get_latest_agent_run`

Read the latest run in an agent session. It accepts the same `session_id`,
`agent`, and `account_id` arguments as `list_agent_runs`:

```json theme={null}
{
  "session_id": "00000000-0000-4000-8000-000000000001",
  "agent": "fast_dataset_creator",
  "account_id": "447"
}
```

Prefer an exact run ID once you have recovered it so a later run cannot be
mistaken for the operation you are waiting on.

## Dataset inspection and files

### `list_datasets`

Lists datasets newest first. Use `limit` (1-100) and `offset` for pagination:

```json theme={null}
{"limit": 20, "offset": 0, "account_id": "447"}
```

### `get_dataset`

Returns dataset metadata, row count, and column names:

```json theme={null}
{"dataset_id": "ds-abc123", "account_id": "447"}
```

Use this before a workflow when you need to know the number of rows or available
columns. If the row count is zero, there are no rows to preview or enrich. Set `include_runs: true` when you also need processing run summaries.

### `get_dataset_fields`

Returns the authoritative field names without downloading the dataset. Use this
when you only need schema information:

```json theme={null}
{"dataset_id": "ds-abc123", "account_id": "447"}
```

### `preview_dataset`

Returns up to 100 rows. The optional SQL must be a read-only DuckDB `SELECT`
against a table named `input_dataset`:

```json theme={null}
{
  "dataset_id": "ds-abc123",
  "sql": "SELECT company_name, website FROM input_dataset WHERE employee_count > 100",
  "limit": 20,
  "account_id": "447"
}
```

If `sql` is omitted, the tool uses `SELECT * FROM input_dataset`. Long cell
values are trimmed for safe tool responses. An empty `rows` result means the
dataset is empty or the query matched nothing.

### `upload_dataset`

Uploads bounded CSV or JSONL text supplied by the MCP client. It accepts up to
5 MiB and does not read a client-local filesystem path. For larger files, use
the Landbase UI or CLI. After upload, call `get_dataset` to inspect processing
status and fields:

```json theme={null}
{
  "filename": "prospects.csv",
  "content": "company_name,website\nAcme,https://acme.example\n",
  "account_id": "447"
}
```

### `get_dataset_lineage`

Returns the datasets and processing history that produced a dataset. Use this
when explaining where an output came from or before deleting derived data:

```json theme={null}
{"dataset_id": "ds-abc123", "account_id": "447"}
```

### `delete_dataset`

Permanently deletes a dataset. The first call only returns a confirmation
request; repeat with `confirm: true` after the user explicitly agrees:

```json theme={null}
{"dataset_id": "ds-abc123", "confirm": true, "account_id": "447"}
```

### `publish_dataset`

Creates one downloadable file from a dataset. Supported formats are `csv`,
`jsonl.gz`, and `parquet`:

```json theme={null}
{
  "dataset_id": "ds-abc123",
  "format": "csv",
  "account_id": "447"
}
```

The tool starts an asynchronous workflow and returns a `workflow_run_id`. Poll
it with `get_workflow_run`, keeping the same `account_id`; after it succeeds,
download the output dataset with that account ID.
Publishing is also required when a dataset is partitioned and cannot be
downloaded directly.

### `get_download_url`

Returns a temporary download link. Downloading costs credits, so call it once
without confirmation first:

```json theme={null}
{"dataset_id": "ds-abc123", "account_id": "447"}
```

The first result has `status: "needs_confirmation"`, `row_count`, and a
next-step instruction. After the user agrees, repeat with `confirm: true`:

```json theme={null}
{"dataset_id": "ds-abc123", "confirm": true, "account_id": "447"}
```

The confirmed result has `status: "ready"`, `download_url`, and an expiry of
about 30 minutes. Give the URL to the user promptly. If the tool says the
dataset must be published, call `publish_dataset`, poll its workflow, and use
that workflow's `output_dataset_id`.

## Matching individual records

### `match_company`

Looks up one company using a website, company name, or LinkedIn URL. A website
or LinkedIn URL is more precise than a name alone:

```json theme={null}
{"company_website": "https://example.com", "account_id": "447"}
```

Optional inputs include `company_name`, `linkedin_url`, and `hq_country`. At
least one of `company_website`, `company_name`, or `linkedin_url` is required.
For many rows, use `match_dataset` instead.

### `match_person`

Looks up one person using a LinkedIn URL, email, or a full name with company
context:

```json theme={null}
{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "company_name": "Analytical Engines",
  "account_id": "447"
}
```

A LinkedIn URL or email is the strongest identifier. A full name requires both
`first_name` and `last_name` plus `company_name` or `company_website`. Treat a
`plausible` match as unverified and inspect the returned record before reporting
it as confirmed.

## Dataset workflows

Workflow calls return a bounded status snapshot. A workflow may still be in
progress when the tool returns. Poll with:

```json theme={null}
{
  "run_id": "workflow-run-123",
  "wait_seconds": 40,
  "account_id": "447"
}
```

Use `output_dataset_id` after `SUCCEEDED`; it is the workflow's output dataset,
not the input dataset. Terminal statuses are `SUCCEEDED`, `FAILED`, and
`CANCELLED`. Do not retry a failed workflow without changing the cause. Use
`cancel_workflow_run` only when the user asks to stop work.

### `match_dataset`

Matches many company or person rows to Landbase records.

```json theme={null}
{
  "dataset_id": "ds-abc123",
  "enable_name_to_website": false,
  "account_id": "447"
}
```

### `enrich_dataset`

Adds selected company and/or person attributes. This spends credits:

```json theme={null}
{
  "dataset_id": "ds-abc123",
  "company_enrich_fields": [
    "employee_count",
    "industry"
  ],
  "person_enrich_fields": [
    "job_title",
    "email"
  ],
  "account_id": "447"
}
```

Call first without `confirm`. If the result is `needs_confirmation`, show the
estimate and repeat the same call, including the selected `account_id`, with
`confirm: true` only after the user agrees.

### `qualify_dataset`

Runs one or more AI yes/no qualification questions for each row:

```json theme={null}
{
  "dataset_id": "ds-abc123",
  "qualification_prompts": [
    "Is this company a B2B SaaS business?"
  ],
  "context_cols": [
    "company_name",
    "website"
  ],
  "entity_type": "company",
  "enable_web_search": false,
  "account_id": "447"
}
```

This spends credits and requires the same quote-then-confirm flow. `entity_type`
is `company` or `person`.

### `research_dataset`

Runs one AI research task per row. The typed tool accepts one task at a time:

```json theme={null}
{
  "dataset_id": "ds-abc123",
  "research_task_name": "pricing",
  "prompt": "Find the public pricing model and summarize it in one sentence.",
  "context_cols": [
    "website"
  ],
  "enable_web_search": true,
  "account_id": "447"
}
```

This spends credits and requires confirmation. Keep the prompt focused and use
only the columns needed for the task.

### `enrich_contacts`

Finds contact email addresses and/or phone numbers:

```json theme={null}
{
  "dataset_id": "ds-abc123",
  "enrich_email_address": true,
  "enrich_phone_number": false,
  "account_id": "447"
}
```

This spends credits and requires confirmation. Request only the contact fields
needed for the user's goal.

### `transform_dataset`

Creates a new dataset from a read-only SQL query. It is useful for limiting rows
before a paid workflow:

```json theme={null}
{
  "dataset_id": "ds-abc123",
  "sql": "SELECT * FROM input_dataset LIMIT 100",
  "account_id": "447"
}
```

Use the returned workflow's `output_dataset_id` for the next step.

### `run_workflow`

The generic workflow tool supports `onboard`, `match`, `enrich_only`, `qualify`,
`research`, `dataset_transform`, `similar_company_expansion`, and
`contact_enrich`. Its `params` object follows the workflow-specific shapes in
the tool description. Prefer the typed tools above when available.

For example, the generic form of a match call is:

```json theme={null}
{
  "workflow": "match",
  "dataset_id": "ds-abc123",
  "params": {
    "enable_name_to_website": false
  },
  "account_id": "447"
}
```

### `get_workflow_run`

Polls a `workflow_run_id` from `run_workflow`, a typed workflow tool, or a
search/publish result. It waits up to 40 seconds and returns progress such as
`percentage`, `rows_processed`, and `current_stage` when available.

```json theme={null}
{"run_id": "workflow-run-123", "wait_seconds": 40, "account_id": "447"}
```

### `cancel_workflow_run`

Cancels a running workflow. Only call it after the user explicitly asks to stop
that workflow:

```json theme={null}
{"run_id": "workflow-run-123", "account_id": "447"}
```

Cancellation does not roll back rows already written or credits already spent.
Inspect the run and its lineage before deciding whether any output is usable.

## Guided prompts and capabilities resource

Clients that support MCP prompts can use `build_prospect_list` or
`enrich_dataset` to start a guided workflow. Prompts are suggestions for the
model; they do not execute tools themselves.

Clients that support MCP resources can read `landbase://capabilities` for a
short version of the tool catalog, async rules, and confirmation requirements.

## Common errors and recovery

* **Multiple accounts:** call `list_accounts`, ask the user to choose, and pass
  `account_id`.
* **`needs_confirmation`:** show the estimate or row count and ask for explicit
  agreement; keep the same `account_id` on the confirmed call and do not set
  `confirm` automatically.
* **Running search/workflow:** poll the returned handle or run ID; do not start
  a duplicate operation.
* **`PUBLISH_REQUIRED`:** publish the dataset, poll that workflow, and download
  the output dataset.
* **Insufficient credits:** tell the user and do not retry.
* **Rate-limited status read:** wait for the indicated delay, then retry the
  same read. If it fails again, report the error.
* **Timed-out call that starts work:** recover the existing operation before
  retrying. A lost response does not mean no work started. See
  [Continue a search or workflow](https://www.landbase.com/docs/guides/mcp/continue-async-work.md).

For copy/paste task prompts, see the [MCP prompt cookbook](https://www.landbase.com/docs/guides/mcp/prompt-cookbook.md). For connection and recovery symptoms, see [Troubleshoot MCP](https://www.landbase.com/docs/guides/mcp/troubleshooting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.