Skip to main content
Glama
Datris MCP Server

Datris MCP Server

test_tap

Validate a tap script before a real run by previewing records and returning results, record counts, and errors. Use it to catch script issues without pushing data to the pipeline.

Instructions

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 test again. For a large columnar or tabular source, yield each batch (a pyarrow RecordBatch, a pandas DataFrame, or a list of dicts) instead of each row — the platform serialises a batch natively, several times faster — and read only the columns the pipeline needs (columns=[...]). Yielding one row at a time remains correct for small or API-paged sources. A test is bounded by TAP_SCRIPT_TIMEOUT_SECONDS (default 300 s), which is deliberately shorter than the ceiling a real run gets — a test that times out on a large source does not mean run_tap will. A run that timed out returns the script's logs, its [wrapper] streamed N records progress lines and a partial record count. Read them first: a script that reached the source and was still streaming records when the timeout hit is healthy and too long, not wrong — do not rewrite it; tell the user how far it got and offer a smaller window via params or the operator's timeout setting. After two consecutive failed tests, stop and report the exact error text to the user instead of iterating further; never probe the runner environment or read the wrapper to diagnose. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status pending_approval with an approvalId. Tell the user it is waiting for approval in Datris, then poll get_approval with that id (pause with wait_seconds between polls) — do not re-issue the action.

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": {
      "name": "<name>"
    },
    "name": "test_tap"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesName of the tap to test
limitNoMax records to pull for the preview (default 20). 0 = no cap: streams the whole source — only when the user explicitly asks for a full test.
reasonNoOptional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are supplied, so the description carries the full load, and it does: no data is pushed, the test is bounded by TAP_SCRIPT_TIMEOUT_SECONDS (default 300s) which is shorter than a real run's ceiling, exit code -9/137/"killed" means OOM, and a timed-out run returns logs, `[wrapper] streamed N records` lines and a partial count. The approval branch disclosure (status `pending_approval` with an `approvalId`) is exactly the kind of side-effect detail an agent cannot infer elsewhere.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the run_tap contrast are correctly front-loaded, but the block runs long for a three-parameter tool and drifts into script-authoring advice (pyarrow RecordBatch vs pandas DataFrame, `columns=[...]` projection). That guidance is useful in a docs page but repeats and dilutes the invocation-relevant content an agent needs at call time.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description correctly describes what comes back (results, record count, errors, log lines) and what the record count actually means. Timeout behavior, the OOM signature, and the approval polling loop are all covered, leaving nothing essential an agent must guess before calling it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3 and the schema already explains `name`, `limit` (including 0 = no cap) and `reason`. The description adds value on `limit` semantics indirectly ("recordCount from a test is the preview size"), but it also refers to a `params` argument for narrowing the window that does not exist in the input schema, which muddies rather than clarifies parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Test-run a tap without pushing data to the pipeline" gives a specific verb (test-run), resource (tap), and the key distinguishing negative (no pipeline write). The second sentence adds what it returns, and the reference to running "for real" implicitly contrasts with run_tap, so an agent can separate the two without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the use case explicitly ("Use this to validate a script before running it for real"), defines when to stop ("After two consecutive failed tests, stop and report the exact error text"), and forbids behavior ("never probe the runner environment or read the wrapper"). It also handles the approval path by naming get_approval and warning against re-issuing the action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools