> ## 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.

# MCP search reference

> Search and recover Landbase prospecting results through MCP tools.

Use MCP `search` to find companies or people, preview the resulting dataset, and
continue work that runs asynchronously. Start with [the supported-tools
guide](https://www.landbase.com/docs/guides/mcp/mcp-supported-tools.md) for the complete schema.

## `search`

Submit a natural-language request to build a company or people dataset.

Important inputs:

| Input | Description |
| - | - |
| `query` | Natural-language description of the audience or analysis. |
| `mode` | `default` for everyday audience builds; `research` for Advanced Dataset Creator-style custom logic, aggregations, and exact output columns. |
| `session_id` | Continue an existing search conversation and refine its result. |
| `wait_seconds` | Wait up to 40 seconds for a result before returning a running handle. |
| `account_id` | The selected Landbase account. Preserve it on every follow-up call. |

Example:

```json theme={null}
{
  "account_id": "447",
  "query": "Find 20 B2B SaaS companies in Texas with 50–200 employees",
  "mode": "default",
  "wait_seconds": 40
}
```

The completed response usually includes an answer, a `session_id`, and a
`dataset_id`:

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

## For AI agents

* Call `list_accounts` when the account is ambiguous and preserve the selected `account_id`.
* Call `get_credit_balance` when the request may use paid research or another credit-consuming mode.
* Use returned dataset fields instead of guessing field names.
* Preserve `search_handle` and `agent_run_id`; recover existing work before retrying.
* Preview results before paid follow-up work.

When the account is ambiguous, call `list_accounts` first and ask the user to
select an account. Do not infer an account from a dataset ID, session ID, or
run ID.

## Default search

Use `mode: "default"` for ordinary natural-language audience requests. This is
the fastest path for finding companies or people with common criteria such as
industry, title, geography, employee count, or other supported filters.

### Safe search prompt

```text theme={null}
Find 20 B2B SaaS companies in Texas with 50–200 employees. Preview the results and do not enrich or spend credits.
```

```json theme={null}
{
  "account_id": "5093",
  "query": "B2B SaaS companies in Texas",
  "mode": "default",
  "wait_seconds": 40
}
```

The assistant should call `list_accounts` if needed, then `search`, and inspect
the result with `get_search_result` when a handle is returned. Search and
preview are read-only; do not automatically chain them into enrichment,
qualification, research, publishing, or downloads.

## Refine a search with sessions

Reuse the returned `session_id` when a follow-up should continue the same search
conversation. Keep the same `account_id` and provide a new query:

```json theme={null}
{
  "account_id": "5093",
  "session_id": "4f2d...",
  "query": "Only show companies with at least 50 employees",
  "mode": "default",
  "wait_seconds": 40
}
```

Do not start an unrelated search when a session is available for the refinement
the user requested.

## Advanced Dataset Creator

Use `mode: "research"` when the request needs custom logic that is hard to
express as fixed filters, including:

* Custom SQL-style conditions or exact filtering.
* Aggregations, rankings, counts, or breakdowns.
* Ratios and comparisons between custom groups.
* Historical or time-based signals.
* Explicit output columns such as counts, ratios, booleans, and labels.

Research search uses a two-step approval flow:

1. Send the request with `mode: "research"` and preserve the returned `session_id`.
2. Review the proposed query, expected result, and credit quote.
3. After the user approves, call `search` again with `query: "confirm"`, the same `session_id`, `mode: "research"`, and `account_id`.

Do not pass `confirm: true`; MCP `search` does not accept that argument.

### Advanced Dataset Creator examples

Find companies using a custom ratio and request specific output columns:

```json theme={null}
{
  "account_id": "447",
  "session_id": "sales-ratio",
  "mode": "research",
  "query": "Find companies where the AE-to-SDR ratio is between 1.5 and 3.0. Return company name, website, AE count, SDR count, and ratio.",
  "wait_seconds": 40
}
```

After reviewing the proposal and receiving approval:

```json theme={null}
{
  "account_id": "447",
  "session_id": "sales-ratio",
  "mode": "research",
  "query": "confirm",
  "wait_seconds": 40
}
```

Ask for an aggregation or ranking:

```json theme={null}
{
  "account_id": "447",
  "session_id": "state-counts",
  "mode": "research",
  "query": "How many companies are in each US state, sorted by count? Return the top 10.",
  "wait_seconds": 40
}
```

Research mode may return a SQL proposal and credit quote without a dataset on
the first turn. Do not treat that response as completed work until the user
approves and the confirmation call returns a completed result.

## Search results and recovery

Search responses can include a dataset identifier, a search handle, or an
`agent_run_id`. Keep every identifier with the selected account. Use
`get_search_result` for a search handle. Use `get_agent_run` for one agent-run
status read, `wait_for_agent_run` for bounded polling, `list_agent_runs` to find
runs for a session, and `get_latest_agent_run` when the trigger response was
lost.

If the response is still running, call `get_search_result` with the exact opaque
handle, the same `account_id`, and a new `wait_seconds` value. Do not submit the
same query again while it is running.

`wait_seconds` is bounded. A wait expiration does not cancel remote work. See
[Continue a search or workflow](https://www.landbase.com/docs/guides/mcp/continue-async-work.md) before starting
another request.

If the trigger response was lost, use `list_agent_runs` or
`get_latest_agent_run` with the original `session_id` and agent context to
recover it.

Once a search completes, use the returned `dataset_id` for dataset inspection
and later workflows. Do not assume the input or previous dataset is the output
of a new search.

## Related pages

* [Build your first prospect list](https://www.landbase.com/docs/guides/mcp/first-prospect-list.md)
* [MCP limits and credits](https://www.landbase.com/docs/guides/mcp/limits-and-credits.md)
* [MCP troubleshooting](https://www.landbase.com/docs/guides/mcp/troubleshooting.md)


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