benthic-mcp

Official

by benthic-io

Overview Schema Source Related Servers Discussions Admin

Python

Remote

benthic_query

Read-onlyIdempotent

Runs a bounded read-only query on a signed data provenance dataset, with filters, aggregates, and ordering.

Instructions

Run one bounded read-only relation query.

Call benthic_discover first and pass its source value verbatim. where uses column=operator.value,
metrics uses output_name=function:column, having uses output_name>value, and order uses
column:asc or column:desc. The name in a metric is the output column, not the source column.
Operators: eq, neq, gt, gte, lt, lte, like, ilike, in, is.null, not.is.null. Aggregates are complete
or rejected; never infer totals from a truncated source.

Call benthic_playbook(dataset) first when a question depends on dataset conventions, then call benthic_report once if this tool call taught you something the playbook lacks.

Input Schema

Name	Required	Description
`limit`	No
`order`	No
`where`	No
`having`	No
`offset`	No
`select`	No
`source`	Yes
`metrics`	No	Aggregates as 'output_name=function:column' or 'output_name:function:column', where output_name is the output column, not a source column. Functions: count, sum, avg, min, max. 'n=count:*' counts rows.
`group_by`	No
`question`	Yes

Output Schema

Name	Required	Description	Default
`rows`	Yes
`joins`	Yes
`columns`	Yes
`sources`	Yes
`warnings`	No
`row_count`	Yes
`truncated`	Yes
`next_offset`	No
`source_complete`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 2, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so safety is covered. The description adds real behavior beyond that: the query is bounded, aggregates are 'complete or rejected' rather than partially returned, and the caller must never infer totals from a truncated source. Those are non-obvious failure semantics the schema cannot express.

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

Conciseness4/5

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

Front-loaded one-line purpose followed by dense but relevant syntax clauses, then a short trailing routing sentence. Nearly every clause earns its place, though the metrics output-name rule and the '=' vs ':' variant are duplicated in the schema's metrics description, and the prose is tightly packed rather than cleanly separated.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. What remains for a 10-parameter, low-schema-coverage query tool — the custom filter/aggregate DSL, the required discovery prerequisite, and the aggregate-completeness guarantee — is all present, so an agent has enough to invoke it correctly.

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

Parameters4/5

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

Schema description coverage is only 10% (just the metrics field), so the description carries the burden. It defines the mini-language for where (column=operator.value), metrics (output_name=function:column, with the output-vs-source-column warning), having (output_name>value), and order (column:asc/desc), plus the operator list. It does not explain select, group_by, limit, or offset semantics, so it compensates substantially but not fully.

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?

Opens with a specific verb+resource: 'Run one bounded read-only relation query.' The scope word 'bounded' plus 'read-only' pins down exactly what class of operation this is, and the text immediately routes the agent to benthic_discover for the source value, which makes it distinguishable from the other benthic_* siblings.

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?

Explicit sequencing is given: 'Call benthic_discover first and pass its source value verbatim,' plus 'Call benthic_playbook(dataset) first when a question depends on dataset conventions.' That is concrete when-to-use guidance tied to named alternatives. It stops short of saying when to prefer benthic_join or benthic_rpc over this tool, so it is not a full when/when-not rubric.

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

Deploy Server