Datris

Start one server-side job that enables a catalog's taps in their enable order (see catalog_enable_order): level by level, each tap is tested if it has no passing test, enabled, given one real run, and the job waits until that run's data has landed before moving on. A tap whose source did not land data is skipped with the reason; every tap's outcome is reported. Call this ONLY when the user has asked to enable the catalog's taps. It returns at once with the job id and the plan; follow progress with catalog_enable_order (its `job` block), pausing with `wait_seconds` between polls, until `job.act…

Back up a catalog: returns one zip archive of every tap and pipeline in it (definitions, each tap's script and incremental state, referenced validation schemas). Read-only. Secret values are never included; the manifest lists the secret names the catalog needs. Returns `manifest` (catalog, taps, pipelines, requiredSecrets, warnings) first, then `archiveBase64` and `sizeBytes`. Answer questions about the archive from `manifest`; pass `archiveBase64` unchanged to restore_catalog. Uncataloged cannot be exported.

Find datasets by meaning: ranks the pipelines your key can read against a natural-language query over their names, descriptions, tags, catalogs, destination field names, and source hosts. Each hit returns where the data lives, how fresh it is, provenance handles (latest run id, config version, script sha), lineage, and a `howToQuery` hint naming the existing query/search tool with pre-filled arguments. Discovery only — nothing is executed for you: make the query call yourself, then pass its provenance handles to ai_answer as `sources` so the answer carries them.

Read this Datris instance's agent policy: for each action (e.g. tap:delete, pipeline:update:dest-types) whether an agent may do it on its own (auto), must wait for a person to approve it (approve), or is refused (deny). Call this before a delete, schema migration, or other consequential change to know whether it will run immediately or queue for approval, and tell the user accordingly. Returns {enabled, policy:{actions, overrides, limits}, actions:[all policy-able action keys], pendingCount}. When enabled is false, every action is auto.

Poll one queued approval by the `approvalId` a mutating tool returned with status pending_approval. Returns its current state: pending (still waiting for a person), executed (approved and performed — `resultStatus` / `resultBody` carry the outcome of the original call), failed (approved but the replay failed), rejected, or expired. Poll with `wait_seconds` between calls, backing off to 30-60s; a decision can take minutes or hours, so after a few polls tell the user you will check back and stop polling unless they ask you to wait.

Propose real column types for a pipeline whose destination columns are all stored as text (the default for agent-created pipelines). Stateless: samples up to 1000 rows that already landed in the destination, infers types deterministically, and returns per-column evidence — a few sample values, plus (for columns kept as string by a dirty value) the offending value and the type it blocked. Only for postgres, snowflake, and databricks destinations; `eligible: false` with a `reason` of destination-not-supported, already-typed, or no-landed-rows (run the pipeline once first) otherwise. Nothing is s…

Read one recovery-agent incident by id — its trigger, classification, proposal, step-by-step narrative, approvals it is waiting on, outcome, and its evidence (before/after profile, diff, blast radius, thresholds, verdict). A pipeline incident's repair is regenerating the stored AI script; the evidence names the script versions before and after (scriptVersions), and revertToScriptVersions is what a failed verification restores. The one-line evidence summary of this evidence (numbers and column names, never values) is also what the incident webhook sends (evidenceSummary). When the operator asks…

Read the deterministic evidence the platform computed for one recovery-agent incident: the baseline profile of the last successful run before it broke, the profile of the real run after the fix, the diff between them (columns added or removed, type changes, record-count delta, null-rate deltas, distribution shift), the blast radius (downstream pipelines, datasets and catalog tables, and which agent identities queried them when reads are audited), the thresholds in force, each threshold check, and the verdict (pending | pass | fail | needs-human). Computed by platform code, never by a model; va…

Get job status for an upload_data submission. Pass `pipeline_token` (returned from upload_data) for the recommended path. Pass `pipeline_name` instead for a paginated summary of recent jobs for that pipeline. When queried by `pipeline_token`, the response is `{rollup: {allDone, status, jobs: [...]}, events: [...]}` — poll every few seconds until `rollup.allDone` is true, then read `rollup.status` (`success` | `warning` | `error`) for the outcome. Per-job detail is in `rollup.jobs[]` with `pipelineToken`, `pipeline`, `filename`, `status`, `startedAt`, `lastEventAt`, `elapsed`, and `lastError` (…

Traverse the lineage graph from one node: everything upstream (what feeds it) and/or downstream (what depends on it) of a source, tap, pipeline, dataset, or catalog, with the edges between them, freshness for the pipeline involved, and optionally the most recent recorded runs (what each run read and wrote, per destination). Datasets a pipeline used to land into under an earlier configuration are marked `historical`. Use it for impact analysis before changing or deleting something — 'what is downstream of this tap?' — or to see which datasets a pipeline actually wrote. Node names: a tap or pipe…

Get a specific pipeline configuration by name. Returns the full JSON config including source, dataQuality, transformation, preprocessor, and destination sections.

Read the rows a Live Read (`scratch`) pipeline produced. Only Live Read pipelines (destination scratch) have a result — anything else is a 404 (an error body of `Not Found` / `status: 404` — rather than the endpoint's own `Only Live Read (scratch) pipelines have a result` message, or `Only scratch pipelines have a result` on older servers — for a pipeline you know is Live Read means the server predates Live Read results: report the version mismatch and stop, do not retry). The first rows are already on the `get_pipeline_status` rollup as `resultPreview`, so call this ONLY when the rollup's `re…

Read pipeline ingestion status. Use this after `run_tap` to watch a tap-submitted load progress. Pass `publisher_token` to see every job the tap run submitted (the recommended option — works for both structured and document taps). Pass `pipeline_token` for a single ingestion job. Exactly one of the two must be supplied. Response shape: `{rollup: {allDone, status, jobs: [...]}, events: [...]}`. Poll every few seconds until `rollup.allDone` is true, then read `rollup.status` (`success` | `warning` | `error`) for the outcome. Per-job detail is in `rollup.jobs[]` — each entry has `pipelineToken`, …

View one historical snapshot of a pipeline's definition: the full config as it was at that version. Read-only; does not change the live pipeline. Get version numbers from `list_pipeline_versions`.

Return the FIELD NAMES (keys only — never values) of an existing platform secret. Use this after list_platform_secrets to verify a candidate secret has the keys a destination config requires (e.g. an S3 credentialsSecret must contain accessKey, secretKey, region). Secret values are intentionally NOT returned. If the named secret is tap-tagged, this tool refuses — use get_tap_secret_fields for those.

Resolve a stamped `_datris_run_id` value back to its origin: the pipeline run, the tap run that fed it, the script commit, the pipeline config version, and the declared source. Use it when rows or search results carry `_datris_*` provenance fields (pipelines with provenance stamping enabled). Returns one document walking the whole chain.

View one version of a pipeline's AI data-quality rule or AI transformation script: the list fields plus the full `script` text, `fingerprint`, `generatedAt` and `contractVersion`. Read-only; does not change what the pipeline runs. Get version numbers from `list_script_versions`.

Get a tap's static definition: configuration, schedule, target pipeline, and the generated Python script content. This is config-only — it returns the SAME data on every call and tells you NOTHING about run state. Do NOT call this to check whether a run is finished or to poll for completion — repeatedly calling get_tap after run_tap is a bug, the response will never change to reflect ingestion progress. For run status: call `get_pipeline_status(publisher_token=...)` (token comes from the run_tap response or from a get_tap_logs entry). For run history: call `get_tap_logs`.

For a document tap: return the ledger of discovered documents (URI, filename, status, hashes, first/last seen timestamps). The ledger is what tells the platform which documents have already been processed so re-runs skip unchanged files. Pass 'clear_uri' to delete one entry (forces that document to be re-processed on the next run) or 'clear_all=true' to wipe the entire ledger (forces a full re-scan).

Get the run history for a tap. Returns the last 50 run log entries sorted by most recent first, including status, record count, duration, errors, logs, and `publisherToken` for each run that submitted records to a pipeline. Works for both manual runs (triggered by `run_tap`) and scheduled runs (triggered by the platform's cron scheduler) — they share the same log. Use this to verify whether a scheduled run fired, whether any recent run's script succeeded, and to recover the `publisherToken` for any run if you didn't keep the original `run_tap` response in context. To verify the actual destinat…

Return the FIELD NAMES (keys only — never values) of an existing tap secret. Use this after list_tap_secrets to verify a candidate secret has the keys your tap script will need (e.g. API_KEY, USER_AGENT). Secret values are intentionally NOT returned and are never visible to the agent.

Get a tap's incremental-sync state — the bookmark/cursor its script saved after the last successful run (injected into the next run as the DATRIS_TAP_STATE env var). Returns `{tap, state, updatedAt, updatedBy}`; `state` is null when the tap has never committed state (non-incremental tap, or no successful run yet). Use this to see where an incremental tap will resume from, or to debug why a scheduled tap is re-fetching or skipping a window.

View one historical snapshot of a tap's definition: the full config and the pinned Python script as they were at that version. Read-only; does not change the live tap. Get version numbers from `list_tap_versions`.

Get the Datris server version and the tap budgets in force on this install: `pipelineMaxPayloadMB` (MB, 0 = unlimited), `tapScriptTimeoutSeconds` and `tapRunTimeoutSeconds`, each with a `...Source` field (`env`, `deprecated-alias`, `derived` or `default`). Cheap to call: call it before sizing a large source and compare the estimates with these values, not with the documented defaults (the budget fields are absent on a server older than this feature; then the documented defaults apply). It also returns `environmentLabel` when the operator set `DATRIS_ENV` on the server (absent otherwise).

Kill a running pipeline job by its pipeline token. The job thread will be interrupted and the job marked as cancelled.

List all collections in the Chroma vector database. Use this to discover available collections before running search_chroma.

List the platform's recovery-agent incidents, newest first. An incident is opened by the platform itself when a scheduled tap finally fails, a pipeline job errors, a tap goes stale, a pipeline's volume swings, or a source changed its columns after a successful run (schema drift); the recovery agent diagnoses it and — within the agent policy's recovery mode — repairs and verifies it (for taps, re-running or fixing the tap; for pipelines, regenerating the stored AI script; the evidence names the script versions before and after). Each entry carries kind, resource, state (open | diagnosing | prop…

List all collections in the Milvus vector database. Use this to discover available collections before running search_milvus.

List MongoDB collections. If database is specified, lists collections in that database. If omitted, lists all collections across all databases in 'db.collection' format.

List all MongoDB databases available in the Datris platform. Use this as the first step when exploring what data has been ingested into MongoDB destinations.

List the actions this agent queued for human approval under the agent policy, newest first. Each entry has id, action, resource, state (pending | approved | rejected | expired | executed | failed), createdAt, expiresAt and — once decided — decidedBy and the result. Use `state` to filter (default: all).

List all pgvector tables (tables with an embedding column) in PostgreSQL. Use this to discover available collections before running search_pgvector.

List the change HISTORY of a pipeline's definition, newest first. Each entry has `version`, `createdAt`, `createdBy`, and `changeNote`. The platform snapshots a pipeline's full config every time it is created or updated. Read-only. IMPORTANT: an EMPTY result does NOT mean the pipeline has no version — it means it has not been edited since versioning was enabled. The CURRENT version number is the `version` field on the pipeline itself (from `list_pipelines` or `get_pipeline`), at least 1 for every pipeline. Use this tool for 'what changed and when'; use `list_pipelines`/`get_pipeline` for 'what…

List all registered pipeline configurations. Each pipeline defines a complete data processing flow: source format and schema, AI-powered data quality and transformations, and destination (database, message queue, or vector store). CALL THIS FIRST on any data-related user request — before suggesting external sources, before asking scope questions. The user almost always cares more about what's already in their Datris environment than about a generic options menu.

List the names of PLATFORM secrets (all secrets NOT tagged _type=tap — the Platform tab in the UI's Secrets section). These are human-owned credentials for destinations and infrastructure (e.g. S3 destination credentials, Postgres connection, MongoDB connection, embedding/vector-store endpoints). The agent can READ these (to look up their names and field shape via get_platform_secret_fields and reference them in pipeline configs) but cannot create, update, or delete them — those operations are the user's responsibility via the Secrets tab. Use this whenever a pipeline's destination needs a cre…

List all columns and their data types for a specific PostgreSQL table. Use this to understand table structure before writing a query_postgres SQL query.

List all PostgreSQL databases available in the Datris platform. Use this as the first step when exploring what data has been ingested into PostgreSQL destinations.

List all schemas in a PostgreSQL database. Schemas organize tables within a database (e.g., 'public', 'analytics'). Use after list_postgres_databases to drill into a specific database.

List all tables in a PostgreSQL schema. Set vector_only=true to show only pgvector embedding tables, or false (default) to show regular data tables. Use after list_postgres_schemas.

List all collections in the Qdrant vector database. Use this to discover available collections before running search_qdrant.

List the version HISTORY of the script the pipeline runs for its AI data-quality rule or AI transformation (`kind`), newest first. Each entry has `version`, `createdAt`, `createdBy`, `changeNote`, `origin` (save, regenerate, run, restore-version, restore, repository), `model`, `commitSha` (repository-backed scripts), `fingerprintMatchesCurrent` (written for the pipeline's current instruction and source schema) and `isLive` (the script runs now use). Every change to the script is kept; the pipeline's definition version does not change when its script does. Read-only. See also `get_script_versio…

List the names of tap secrets that already exist (secrets tagged _type=tap — both agent-created and human-owned ones surfaced via the UI's Tap Secrets section). ALWAYS call this before create_tap_secret: if a suitable secret already exists, prefer reusing it by passing its name as secret_name to create_tap. Only ask the user to provide credentials when no existing secret covers the need.

List the change HISTORY of a tap's definition, newest first. Each entry has `version`, `createdAt`, `createdBy`, and `changeNote`. The platform snapshots a tap's config + script every time it is created or updated. Read-only. IMPORTANT: an EMPTY result does NOT mean the tap has no version — it means the tap has not been edited since versioning was enabled, so no change snapshots exist yet. The tap's CURRENT version number is the `version` field on the tap itself (from `list_taps` or `get_tap`), which is at least 1 for every tap. Use this tool for 'what changed and when'; use `list_taps`/`get_t…

List all taps with their status, target pipeline, schedule, and last run info. CALL THIS FIRST (alongside list_pipelines) on any data-related user request — the user's existing taps often reveal what's already being pulled and where, which short-circuits the entire 'should I suggest an external API?' conversation.

List all classes in the Weaviate vector database. Use this to discover available classes before running search_weaviate.

Send data and use AI to generate a comprehensive data profile: summary statistics per column, data quality issues detected, and suggested validation rules. Use the suggested aiRule when building a pipeline's dataQuality section. The server may withhold row values from the model (DATRIS_AI_SAMPLE_VALUES=false): the profile is then built from column statistics or structure only, sampleValues are empty, and the result carries valuesWithheld: true. If the AI model declines the request (a provider safety decline), the result carries aiDeclined: true and holds the server's column statistics only, wi…

Run a read-only query against the Databricks workspace a pipeline loads into. Pass the pipeline name; the server resolves the workspace, credentials, SQL warehouse, and catalog from the pipeline's config — same connection the loader uses, credentials never leave the server. Only works for pipelines whose destination is Databricks (database with useDatabricks=true). Allowed statements: SELECT (WITH/CTE), SHOW, and DESCRIBE — LIMIT is auto-appended to SELECTs. Omit `sql` to preview the pipeline's destination table (the 'did my load land?' check). Metadata discovery uses the same tool — there are…

Query a MongoDB collection with optional filter and projection. Use list_mongodb_databases and list_mongodb_collections first to discover available data. Returns matching documents as JSON.

Ask a question in natural language about data in a PostgreSQL table. The AI generates a SQL query from the question and table schema, executes it, and returns the results. Use this instead of writing SQL manually.

Read rows from a pipeline's objectStore destination (Parquet files, ORC files, or an Iceberg table in MinIO or AWS S3). Pass the pipeline name; the server resolves the bucket, prefix, format, and credentials from the pipeline config — same code path the writer uses, so MinIO and S3 destinations both work. Returns up to `limit` rows as JSON objects keyed by column name, plus the resolved s3a:// path and format for transparency. For an Iceberg table the response also carries snapshotId (a decimal string, not a number) and snapshotTimestamp (ISO-8601) of the snapshot read; both are null for other…

Execute a read-only SQL SELECT query against PostgreSQL. Use the metadata discovery tools (list_postgres_databases, list_postgres_schemas, list_postgres_tables, list_postgres_columns) first to explore available data before constructing queries. Only SELECT is allowed; LIMIT is auto-appended if missing. Queries are cancelled if they run too long, so avoid full-table scans. For approximate row counts — "how many rows / records does table X have", overviews, or summarizing several tables — do NOT run exact `SELECT COUNT(*)` (it scans the whole table and can take many seconds on a large one). Inst…

Run a read-only query against the Snowflake account a pipeline loads into. Pass the pipeline name; the server resolves the account, credentials, warehouse, and role from the pipeline's config — same connection the loader uses, credentials never leave the server. Only works for pipelines whose destination is Snowflake (database with useSnowflake=true). Allowed statements: SELECT (WITH/CTE), SHOW, and DESCRIBE — LIMIT is auto-appended to SELECTs. Omit `sql` to preview the pipeline's destination table (the 'did my load land?' check). Metadata discovery uses the same tool — there are no separate l…

Rename a catalog: every tap and pipeline labelled with `catalog` is relabelled to `new_name` in one server-side operation, and the empty-catalog placeholder moves with it. Call this ONLY when the user has explicitly asked to rename that catalog — never to emulate a rename by calling set_catalog on each item. `new_name` must not already exist: a rename never merges catalogs and is refused if the target exists. To combine two catalogs, move their items with set_catalog. Uncataloged cannot be renamed, and `new_name` must use letters, digits, '_' and '-' only. Items that could not be moved come ba…

Restore a catalog archive produced by export_catalog as catalog `catalog` (the same or a new name). Call this ONLY when the user has explicitly asked to restore and named the archive to use. A restore never merges: it is refused (with the clashing names) when the catalog already exists or any archived tap or pipeline name exists anywhere on this install. mode=overwrite replaces only items already in `catalog` and needs `confirm` equal to the catalog name. It never writes secrets: missing ones come back under `missingSecrets` for the user to create. Restored taps are left disabled; tell the use…

Roll a pipeline back (or forward) to a prior definition version. APPEND-ONLY and SIDE-EFFECTING: reads snapshot `version` and writes it as a NEW latest version, preserving full history. 'Rolling forward' is the same call with a higher version number. Only call this when the operator has explicitly asked to restore/roll back this specific pipeline to a specific version. Report the new version and stop.

Make an earlier version of a pipeline's AI data-quality rule or AI transformation script the one the pipeline runs. APPEND-ONLY and SIDE-EFFECTING: the restore writes the chosen text back as a NEW latest version (no model call); the pipeline's definition version does not change. If that text is already the live script, nothing is written and the response carries `noop: true`. Refused when the pipeline's instruction or source schema no longer matches the version (HTTP 422 with the reason; nothing is changed), and refused with HTTP 409 when a repository-backed script file was edited since its re…

Roll a tap back (or forward) to a prior definition version. This is APPEND-ONLY and SIDE-EFFECTING: it reads snapshot `version` and writes it as a NEW latest version (config + that version's script), preserving the full history — nothing is overwritten or lost. 'Rolling forward' is the same call with a higher version number. Only call this when the operator has explicitly asked to restore/roll back this specific tap to a specific version. It does NOT run the tap — after restoring, report the new version and stop; do not chain into `run_tap` unless separately and explicitly asked.

Run the platform's operational self-check and return a report: Vault token expiry, AI slot secrets complete, embedding model actually loaded, disk usage, the payload staging area (writable, room for one run, no orphaned run directories), component version skew, and (opt-in) whether each AI model answers. Each non-ok check carries a remediation command for the operator; nothing is changed. Do NOT call run_doctor as part of the normal workflow — it is slow. Only use it for diagnostics when something fails or the user asks about the deployment's health. Host-level checks (Docker volumes, containe…

Manually trigger a tap. Executes the script; when a target pipeline is configured, hands records to the pipeline async. The response carries `recordCount`, `publisherToken`, `pipelineTokens`, `persisted`, `persistedReason`, and the script's `logs` — but NOT the records themselves. If you need to preview what the script produces, call `test_tap` instead. BEFORE the first run of a newly-created or newly-updated tap, you MUST have called `test_tap` and seen it succeed. See the VALIDATION RULE in the server instructions. Skipping the test on a fresh script pushes potentially-broken data into the d…

Semantic search across a Chroma vector database collection. Takes a natural language query, generates an embedding, and returns the most similar document chunks with similarity scores. For RAG: pass the returned text to ai_answer with the user's question.

Semantic search across a Milvus vector database collection. Takes a natural language query, generates an embedding, and returns the most similar document chunks with similarity scores. For RAG: pass the returned text to ai_answer with the user's question.

Semantic search across a PostgreSQL pgvector table using cosine distance. Takes a natural language query, generates an embedding, and returns the most similar document chunks with similarity scores. Use list_postgres_tables with vector_only=true to discover available pgvector tables. For RAG: pass the returned text to ai_answer.

Semantic search across a Qdrant vector database collection. Takes a natural language query, generates an embedding, and returns the most similar document chunks with similarity scores. For RAG: pass the returned text to ai_answer with the user's question.

Semantic search across a Weaviate vector database class. Takes a natural language query, generates an embedding, and returns the most similar document chunks with similarity scores. For RAG: pass the returned text to ai_answer with the user's question.

Set or clear the catalog grouping label on an existing pipeline or tap. ONLY call this when the user has explicitly asked to organize work under a named catalog. Do NOT call it proactively — catalogs are a user-chosen organizational convention; assigning one for them puts the pipeline/tap into a taxonomy they didn't ask for. Pass exactly one of `pipeline` or `tap` to identify the target. Pass `catalog` to set the label, or omit it (or pass an empty string) to clear it. Survives subsequent re-ingests — `datris ingest` no longer rewrites an existing pipeline's config.

Overwrite or reset a tap's incremental-sync state. Pass `state` (a JSON object) to set the bookmark the next run receives via DATRIS_TAP_STATE — e.g. rewind a cursor so a window is re-fetched. Pass `reset: true` to delete the state entirely: the next run sees no DATRIS_TAP_STATE and does a full first-run fetch. The state shape is defined by the tap's own script (read its code via get_tap to see what keys it expects). Only use this on explicit request or to recover a broken cursor — normal runs manage state themselves, committing it only after a successful run.

Suggest per-field protection (hmac, mask with an optional preserve, redact, drop, or none, each with a one-line reason) for a pipeline's source fields, computed by the configured CodeGen model from field NAMES and TYPES ONLY: no row value is sent to the model. Stateless: nothing is saved or changed. Pass `pipeline` (an existing pipeline name; its stored source schema is used) or `fields` (an array of {name, type}, e.g. the schema you are about to create). A field that already carries `protect` shows it as `current` next to the suggestion. Show the suggestions to the user and ask which to accep…

Test-run a tap without pushing data to the pipeline. Executes the tap's script and returns results, record count, and any errors. Use this to validate a script before running it for real. By default a test pulls the first 20 records and returns; `recordCount` from a test is the preview size, not what `run_tap` will produce. If the error reports exit code -9 (or 137, or "killed") with no traceback, the script ran out of memory because fetch() built its whole result in memory: rewrite fetch() to yield records one at a time (read the source in chunks / pages) instead of returning a list, then tes…

Update an AI provider secret in the Datris platform. Use this to configure your AI API keys so Datris can use AI features (data profiling, schema generation, AI transformations, RAG). Only AI-related secrets can be updated: anthropic, openai, azure, grok, ollama, embedding.

Update an existing tap's CONFIG without regenerating the script. Change the enabled state, CRON schedule, target pipeline, or description. USE THIS to set or adjust a tap's schedule (`cron_expression`) whenever the user describes a recurrence (nightly, daily, every morning, market open, etc.). The platform's scheduler runs the tap on the cadence you set — no external cron, Airflow DAG, or shell loop is needed (or wanted). See the SCHEDULING RULE in the server instructions. VALIDATION RULE: if you're enabling a `cron_expression` on a tap whose script has NEVER been validated, call `test_tap` FI…

Upload a configuration file to the Datris platform. Supports 'validation-schema' (JSON Schema files used in pipeline dataQuality schema validation). Send the file content as base64.

Upload data to a registered pipeline for processing. Send the ENTIRE file content as a single base64-encoded string in ONE call — do not pre-split or chunk the content client-side. Vector destinations (pgvector, qdrant, weaviate, milvus, chroma) apply recursive chunking server-side using the pipeline's configured chunkSize/chunkOverlap; for those, one upload_data call yields many embedded chunks automatically. The pipeline's rules are applied: schema validation, data quality checks, transformations, then routing to the configured destination. A Live Read (`scratch`) pipeline validates or trans…

Sleep for a fixed number of seconds, then return. Use this to pace polling against long-running platform work (most often `get_pipeline_status` after `run_tap`, or `get_job_status` after `upload_data`) so you do not burn tool calls hammering an endpoint that is still in progress. ALWAYS poll once BEFORE the first wait — many runs finish in 1–5 seconds. Then use exponential backoff between polls: 5s, 10s, 20s, 30s, 60s, 60s, ... (cap at 60s normally, 120s only if the run is genuinely glacial). Reset to a short wait (5–15s) on the next cycle whenever a poll shows new jobs flipped to a terminal s…