Telemetry Machine

Run query

run_query

Read-only

Query one dataset with Apache DataFusion SQL (https://datafusion.apache.org/user-guide/sql/). Use raw_sql for joins, subqueries, CTEs and window functions. A slow query returns a query ID in place of rows.

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": {
      "dataset": "<dataset>",
      "description": "<description>"
    },
    "name": "run_query"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Default: 100.
`since`	No	Required unless you pass raw_sql.
`until`	No	End: a duration ago or ISO 8601. Default: now.
`where`	No	A SQL condition, e.g. "resource.service.name = 'api' AND status_code = 2".
`select`	No	Default: . E.g. "name, count() AS n".
`dataset`	Yes	A dataset name.
`raw_sql`	No	A whole query, in place of the other clauses. Refer to the dataset as __table__. Bound time yourself: WHERE timestamp_unix_ns >= <ns> AND timestamp_unix_ns <= <ns>.
`group_by`	No
`order_by`	No
`description`	Yes	A short label for what the query is about, e.g. "checkout errors by route, last hour".

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 7, 2026
- changedInput schema / properties / dataset / description
```
Previous value: -"Dataset name, from list_datasets."New value: +"A dataset name."
```
First observedOct 30, 2026

TDQS

A3.9/5.0

Behavior4/5

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a real behavioral trait those annotations cannot express: a slow query returns a query ID instead of rows. It omits the timeout threshold and any row-cap behavior beyond the schema's limit field.

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

Conciseness5/5

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

Three short sentences, front-loaded with purpose and dialect link, then the raw_sql escalation path, then the async behavior. Nothing is redundant and the documentation URL earns its place because SQL dialect differences are not inferable elsewhere.

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

Completeness3/5

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

For a 10-parameter query tool with no output schema, the description covers the dialect, the raw_sql escape hatch, and the slow-query behavior. It leaves the query-ID follow-up path (to get_query_result) unstated and does not describe what rows or errors look like, so an agent still has gaps at invocation time.

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 coverage is 80%, which sets the baseline at 3. The description reinforces that raw_sql substitutes for the other clauses, but the __table__ placeholder and time-binding requirement it mentions are already documented in the raw_sql schema entry, and group_by/order_by are undocumented in both places.

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

Purpose4/5

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

"Query one dataset with Apache DataFusion SQL" gives a specific verb, resource, and scope (single dataset), which separates it from siblings like run_surface or list_datasets. It stops short of naming get_query_result, so the boundary for slow-query retrieval is only implied.

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

Usage Guidelines4/5

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

It clearly states when to reach for raw_sql (joins, subqueries, CTEs, window functions), which is the main branching decision in this tool. It never says what to do with the returned query ID or when structured clauses are preferable, so the routing is incomplete rather than absent.

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

All Telemetry Machine tools Inspect

Try in Browser

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?