tap_run
Run a pre-built tap to extract structured site data. Returns columns, rows, count, timing, and cache_hit; read-intent calls are cached for 5 minutes, use fresh:true to bypass.
Instructions
Run a pre-built tap. Preferred over tap.* tools — deterministic, zero AI at runtime. Returns {columns, rows, count, timing, cache_hit}. Read-intent taps are memoized for 5 minutes per process; identical calls return cached data with cache_hit:true. Pass {fresh:true} to bypass cache. Write-intent taps are never cached. If rows contain login/error page content or are empty on a site that requires login → call tap.runtime(runtime:'chrome') first, then retry. If rows is empty on a public site, use tap.doctor(site, name) for structured diagnosis. On transient failure (timeout, connection), RETRY tap.run — do not fall back to manual tap.* operations.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"site": "<site>",
"name": "<name>"
},
"name": "tap_run"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Tap arguments | |
| name | Yes | Tap name | |
| site | Yes | Site name | |
| fresh | No | Bypass the 5-minute per-process result cache. Use when you need current data despite a recent identical call. | |
| envelope | No | Response shape. 'bare' (default) returns {rows, columns, count, elapsed_ms}; 'annotation' wraps the result in a W3C Web Annotation with target + body:tap:RunResult + prov:wasDerivedFrom — useful for provenance chains and signing. Does NOT affect sub-tap composition or pipe bindings (those read the internal flat shape). | bare |