> ## Documentation Index
> Fetch the complete documentation index at: https://webscraping.titannet.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Tool reference overview
> The six Titan MCP tools, when an agent should reach for each, and the response envelope they all share.
The Titan MCP server exposes six tools. The surface is intentionally small—agents choose correctly when the choice is narrow.
| Tool | Purpose | Default behavior |
| --------------------------------------------------------- | ------------------------------- | -------------------------- |
| [`titan_search`](/docs/mcp/tools/titan-search) | Discover URLs for a query | Waits for results |
| [`titan_fetch`](/docs/mcp/tools/titan-fetch) | Read content from known URLs | Waits for results |
| [`titan_crawl`](/docs/mcp/tools/titan-crawl) | Map or crawl a site | Returns a `run_id` to poll |
| [`titan_list_templates`](/docs/mcp/tools/titan-list-templates) | Browse curated templates | Immediate |
| [`titan_run_template`](/docs/mcp/tools/titan-run-template) | Run a curated template | Waits for results |
| [`titan_get_run`](/docs/mcp/tools/titan-get-run) | Poll a run and read its results | Immediate |
## Which tool when
```mermaid theme={null}
flowchart TD
Start{Do you have the URLs?} -->|No| Search[titan_search]
Start -->|Yes| Fetch[titan_fetch]
Search --> Pick[Pick the promising results]
Pick --> Fetch
Start -->|Need the whole site| Crawl[titan_crawl]
Fetch --> Done[Content in markdown]
Crawl --> Done
```
Rules of thumb an agent should follow:
* **Search before fetch.** If you do not have URLs, discover them first rather than guessing.
* **Fetch beats crawl.** Reading five known URLs is faster and cheaper than crawling a site to find them.
* **Crawl only for site-level work.** Reach for it when you genuinely need a site's inventory, not when you need a few pages.
* **Keep limits small.** Request the results you will actually read.
* **Poll after a timeout.** If a tool returns `queued` or `running`, call `titan_get_run` rather than re-issuing the work.
These rules are also embedded in the tool descriptions the server advertises, so most agents follow them without prompting.
## The shared response envelope
Every tool returns the same wrapper fields alongside its own payload:
| Field | Type | Meaning |
| ------------ | ------ | ---------------------------------------------------------------------- |
| `run_id` | string | Titan `execution_id` for this run. Present whenever a run was created. |
| `status` | string | `completed`, `partial`, `running`, `queued`, `failed`, or `cancelled` |
| `usage` | object | Credit estimate, credits consumed, record counts, and billing status |
| `warnings` | array | Machine-readable warnings. Always present, often empty. |
| `request_id` | string | Correlation ID for this MCP call, prefixed `req_` |
`titan_list_templates` is the exception: it starts no run, so it returns only `templates` and `request_id`.
### Statuses
| Status | Meaning | What to do |
| ----------- | ------------------------------- | ------------------------------------------------- |
| `completed` | Run finished, results delivered | Use the results |
| `partial` | Run finished with some failures | Use what came back; check `warnings` |
| `running` | Work in progress | Poll `titan_get_run` |
| `queued` | Accepted, not started | Poll `titan_get_run` |
| `failed` | Run failed | Check `warnings`; retry if the error is retryable |
| `cancelled` | Run was stopped | Start a new run if still needed |
See [Runs and results](/docs/mcp/runs-and-results) for the full lifecycle.
## Shared parameters
Three parameters appear across the execution tools:
Whether to wait for the run inside the tool call. Defaults to `true` for search, fetch, and template runs; `false` for crawl. Set `false` to get a `run_id` immediately.
How long to wait when `wait_for_completion` is true. Capped at 30 seconds. Exceeding it is not an error—the run continues and you receive a `run_id`.
Deduplicates repeated calls. The same key replays the original run instead of starting a new billable one, for 24 hours. See [Idempotency and retries](/docs/mcp/idempotency-and-retries).
## Errors
Failures return an MCP error result with a structured body:
```json theme={null}
{
"code": "limit_exceeded",
"message": "urls exceeds max of 100",
"retryable": false,
"request_id": "req_8f3a1c9e2b7d4056"
}
```
Validation, authorization, and credit failures happen **before** any run is created, so they never consume credits or leave an execution behind. See [Errors and warnings](/docs/mcp/errors-and-warnings).
## Next steps
Search operators, providers, and result shape.
Content formats, truncation, and failure handling.
Map versus crawl mode, and the limits that bound both.
Polling, pagination, and reading step-level results.