Tool reference overview

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`	Discover URLs for a query	Waits for results
`titan_fetch`	Read content from known URLs	Waits for results
`titan_crawl`	Map or crawl a site	Returns a `run_id` to poll
`titan_list_templates`	Browse curated templates	Immediate
`titan_run_template`	Run a curated template	Waits for results
`titan_get_run`	Poll a run and read its results	Immediate

Which tool when

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 for the full lifecycle.

Shared parameters

Three parameters appear across the execution tools:

boolean

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.

integer

default:"30"

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.

string

Deduplicates repeated calls. The same key replays the original run instead of starting a new billable one, for 24 hours. See Idempotency and retries.

Errors

Failures return an MCP error result with a structured body:

{
  "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.

Next steps

titan_search

Search operators, providers, and result shape.

titan_fetch

Content formats, truncation, and failure handling.

titan_crawl

Map versus crawl mode, and the limits that bound both.

titan_get_run

Polling, pagination, and reading step-level results.

Get started

Tool reference

How it works

Integration examples

Which tool when

The shared response envelope

Statuses

Shared parameters

Errors

Next steps

titan_search

titan_fetch

titan_crawl

titan_get_run

​Which tool when

​The shared response envelope

​Statuses

​Shared parameters

​Errors

​Next steps

titan_search

titan_fetch

titan_crawl

titan_get_run

Which tool when

The shared response envelope

Statuses

Shared parameters

Errors

Next steps