— MCP / TOOLS

Tool reference

Trawley v0.5 exposes seven MCP tools. One conversational build verb, three read verbs for discovery and health, three query verbs for natural-language search and drill-down.

Tool descriptions and parameter schemas are also self-describing over MCP's tools/list — your agent doesn't need to read this page to pick the right tool on the first turn.

trawley_build_scrapertrawley_list_scraperstrawley_get_scrapertrawley_check_jobtrawley_searchtrawley_hybrid_searchtrawley_get_result

— BUILD

Build verb

One conversational entry point for creating and editing scrapers.

trawley_build_scraper

Talk to Trawley's scraper builder to create or edit a scraper. The agent navigates the site, picks selectors, and commits.

When to use

Use for any "build me a scraper for X" or "add a field to this scraper" request. Returns the committed scraperId.

Inputs

Name	Type	Required	Description
message	string	yes	What you want Trawley to build, in plain English. Example: "extract listings from acmehomes.co.uk". The agent infers the target URL from this message.
scraperId	string	no	Omit for new scrapers. Pass an existing scraperId to continue editing — useful for adding a field, fixing a selector, or extending a partial build.

Returns

{
  "content": [{ "type": "text", "text": "<agent's reply>" }],
  "structuredContent": {
    "scraperId": "scr_xxx" | null,
    "idempotency_key": "mcp:commit:<keyId>:<requestId>",
    "message": "<agent's reply>"
  }
}

Notes

·Long-running: a single call can take 30s–5min depending on site complexity.
·Per-team concurrency capped at 3 in-flight builds. Excess returns AGENT_LOOP_CONCURRENCY.
·If a build commits but the HTTP connection drops before the reply arrives, call trawley_list_scrapers to find the committed id.

Error codes

AGENT_LOOP_CONCURRENCY AGENT_LOOP_FAILED URL_NOT_ALLOWED SCRAPER_TEAM_MISMATCH SCRAPER_STALE COMMIT_INSUFFICIENT_CONFIG COMMIT_FAILED ALREADY_COMMITTED API_KEY_REVOKED

— READ

Read verbs

Discovery and health. Cheap, side-effect free, ideal for orientation.

trawley_list_scrapers

List every scraper visible to the API key, with compact metadata and last-job summary.

When to use

The cheapest tool in the surface. Use it as a smoke test, or to disambiguate scraper names before deeper calls.

Inputs

No arguments.

Returns

{
  "scrapers": [
    {
      "id": "scr_xxx",
      "name": "...",
      "url": "...",
      "type": "LIST" | "SINGLE_ENTITY",
      "schedule": "0 6 * * *" | null,
      "updated_at": "2026-05-29T10:14:00Z",
      "last_job": {
        "status": "COMPLETED" | "FAILED" | "RUNNING",
        "finished_at": "...",
        "result_count": 47
      } | null
    }
  ]
}

Notes

·No arguments. Returns an empty array — not an error — for a team with zero scrapers.
·Field-level config is omitted; use trawley_get_scraper to drill in.

trawley_get_scraper

Full scraper configuration plus the 5 most recent jobs and a healthy/broken flag.

When to use

Use after trawley_list_scrapers when the agent needs to know fields, selectors, or schedule before editing.

Inputs

Name	Type	Required	Description
scraperId	string	yes	Scraper id from trawley_list_scrapers.

Returns

{
  "scraper": {
    "id": "scr_xxx",
    "name": "...",
    "url": "...",
    "type": "LIST" | "SINGLE_ENTITY",
    "schedule": "...",
    "fields": [{ "name": "price", "type": "NUMBER", "selector": "..." }],
    "updated_at": "..."
  },
  "recent_jobs": [{ "id": "...", "status": "...", "result_count": 0 }],
  "health": {
    "healthy": true,
    "reason": null | "stale" | "failing"
  }
}

Notes

·healthy: false / reason: "stale" means the last successful job is more than 2× the schedule period old.
·healthy: false / reason: "failing" means the last 3 jobs all failed.

Error codes

SCRAPER_NOT_FOUND SCRAPER_TEAM_MISMATCH

trawley_check_job

Status, result count, and error (if any) for a scrape job.

When to use

Use after a manual job trigger or to diagnose why trawley_search returned zero rows.

Inputs

Name	Type	Required	Description
scraperId	string	yes	Scraper the job belongs to.
jobId	string	no	If omitted, returns the most recent job for the scraper.

Returns

{
  "job": {
    "id": "...",
    "status": "PENDING" | "RUNNING" | "COMPLETED" | "FAILED",
    "started_at": "...",
    "finished_at": "...",
    "result_count": 47,
    "error": null | "..."
  }
}

Notes

·Jobs can take seconds or hours depending on site size and pagination depth.
·Use the dashboard to manually trigger a fresh job — there is no MCP run-job tool in v0.5.

Error codes

SCRAPER_NOT_FOUND SCRAPER_TEAM_MISMATCH JOB_NOT_FOUND

— QUERY

Query verbs

Search and drill down on indexed results.

trawley_search

Natural-language search over a scraper's indexed results. Returns structured rows capped to fit an LLM's context window.

When to use

The default query verb. Use it for everything from "3-bed houses with a garden" to "products under £50 with free shipping".

Inputs

Name	Type	Required	Description
scraperId	string	yes	Which scraper to query.
query	string	yes	Free-text query in any language. Trawley routes structured filters automatically (e.g. "under £500k" becomes a price range filter).
limit	number	no	Default 20, max 100. Larger values are clamped silently; the response sets meta.limit_clamped: true.

Returns

{
  "results": [
    {
      "id": "res_xxx",
      "fields": { "price": "£475,000", "bedrooms": 3, "..." : "..." }
    }
  ],
  "pagination": { "total": 47, "page": 1, "take": 20, "hasMore": true },
  "meta": {
    "capped": false,
    "limit_clamped": false,
    "_truncated": [],
    "queryParams": [...]
  }
}

Notes

·Per-field cap: 200 characters. Truncated field names are listed in meta._truncated.
·Total payload cap: 50 KB. If the JSON exceeds it, trailing rows are dropped and meta.capped: true is set.
·For the full uncapped row, call trawley_get_result with the id.

Error codes

SCRAPER_NOT_FOUND SCRAPER_TEAM_MISMATCH PLAN_LIMIT_EXCEEDED

trawley_hybrid_search

Hybrid lexical + semantic search. Use when a pure keyword match misses synonyms or related concepts the user cares about.

When to use

Reach for this when trawley_search returns thin or off-topic results — typically descriptions, free-text fields, or multilingual queries.

Inputs

Name	Type	Required	Description
scraperId	string	yes	Which scraper to query.
query	string	yes	Free-text query. Blends BM25 keyword scoring with embeddings-based semantic similarity.
limit	number	no	Default 20, max 100. Same clamping as trawley_search.

Returns

Same shape as trawley_search, with the same caps applied.

Notes

·Slightly more expensive than trawley_search — counts against the same per-month search-API quota.
·Best for queries like "cozy cabins near hiking trails" where the scraper indexes free-text descriptions.

Error codes

SCRAPER_NOT_FOUND SCRAPER_TEAM_MISMATCH PLAN_LIMIT_EXCEEDED

trawley_get_result

Full uncapped row for a single result. Drill-down companion to the search tools.

When to use

Use when a search row was truncated (check meta._truncated) and you need the full text — for example, the whole property description.

Inputs

Name	Type	Required	Description
scraperId	string	yes	Scraper the result belongs to.
resultId	string	yes	Id from a previous trawley_search or trawley_hybrid_search row.

Returns

{
  "result": {
    "id": "res_xxx",
    "scraperId": "scr_xxx",
    "jobId": "job_xxx",
    "createdAt": "...",
    "fields": { "<field>": "<full uncapped value>" }
  }
}

Notes

·No payload cap — return shape is bounded by a single row's natural size.
·Counts against the results-API monthly quota, not the search-API quota.

Error codes

SCRAPER_NOT_FOUND SCRAPER_TEAM_MISMATCH RESULT_NOT_FOUND PLAN_LIMIT_EXCEEDED

Deferred to v1

trawley_aggregate (sum, average, count over a scraper's results) was descoped from v0.5. If real usage shows agents reaching for a "pull 100 rows and average them" pattern, it lands in v1. Inspect-and-fix verbs (re_test_field, update_field) and a transparent build verb with progress streaming are also deferred until v0.5 surfaces the real failure modes.

Not connected yet?

The getting-started guide walks through generating an API key, pasting a config snippet, and running your first tool call.