Skip to main content
Glama
platypus-db

platypus-db

Official

sample_rows

Preview the first rows of a table, view, or MongoDB collection as an aligned text table or JSON, with configurable row, byte, and timeout limits.

Instructions

Returns the first rows of a table, view, MongoDB collection or search index (default 20 rows), as run_query returns them: an aligned text table, or JSON with format=json. max_rows, max_bytes and timeout_seconds work as in run_query. The rows come in the order the database reads them: no order is implied.

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": {
      "connection": "<connection>",
      "schema": "<schema>",
      "table": "<table>"
    },
    "name": "sample_rows"
  }
}

Input Schema

NameRequiredDescriptionDefault
tableYesThe table, view or collection.
formatNo`text` (an aligned table, the default) or `json`.
schemaYesThe table's schema (a database in MySQL and MongoDB, `main` in SQLite and DuckDB).
max_rowsNoRows returned at most (default 20, up to 10000).
max_bytesNoBytes of output at most (default 32768, up to 1048576).
connectionYesThe connection's name, as `list_connections` shows it.
timeout_secondsNoSeconds the query may run before it is cancelled (default 30, up to 300).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.2

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations at all, the description carries the full burden and does meaningful work: it discloses the sampling semantics ('the order the database reads them: no order is implied'), which prevents an agent from mistaking this for a random or sorted sample, and it documents the default row count and the text-vs-JSON return shape. It does not state read-only safety explicitly (only implied by 'Returns') or any permission requirements, which leaves a small gap for an unannotated tool.

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 tight sentences, front-loaded with what is returned and how, then limits, then the ordering caveat last where it is most likely to be missed. No filler or repetition.

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

Completeness4/5

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

For a seven-parameter read tool with no output schema, the description explains the return format adequately and covers the sampling caveat. The notable gap is pagination: nothing says how to fetch subsequent rows (next_page exists as a sibling) or whether max_rows up to 10000 is the only way to see more data.

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 all seven parameters are already documented, including defaults and caps for max_rows, max_bytes and timeout_seconds. The description's main addition is the cross-reference that these three 'work as in run_query', which adds mild semantic value but mostly restates the schema.

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?

The description gives a specific verb and resource set ('Returns the first rows of a table, view, MongoDB collection or search index') and distinguishes itself from run_query by saying it returns rows 'the way run_query returns them' without requiring SQL. It stops short of an explicit 'use this instead of run_query when you just want a peek' statement, so sibling differentiation is implied rather than stated.

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

Usage Guidelines3/5

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

Usage is only implied: an agent can infer this is a quick sampling tool because of the 20-row default and the 'first rows' framing. There are no explicit when-to-use / when-not-to-use rules and no named alternative (run_query, describe_table, next_page) for the common adjacent cases.

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