DBMCP

get_sample_data

Retrieve representative sample rows from a database table using configurable sampling methods (top, tablesample, modulo). Returns token-efficient results with automatic truncation of large text and binary data.

Instructions

Retrieve sample data from a table.

Returns representative sample rows from a table with support for multiple sampling strategies. Automatically truncates large text (>1000 chars) and binary data (shows first 32 bytes as hex) to keep responses token-efficient.

Args: connection_id: Connection ID from connect_database table_name: Name of the table. May be dotted (e.g. 'schema.table' or 'catalog.schema.table') and is resolved against the dialect. schema_name: Schema name. Defaults to the dialect's default schema (e.g. 'dbo' on MSSQL) when omitted. sample_size: Number of rows to return, 1-1000 (default: 5) sampling_method: Sampling strategy - 'top', 'tablesample', or 'modulo' (default: 'top') - 'top': Fast SELECT TOP N (not representative, just first N rows) - 'tablesample': SQL Server statistical sampling (more representative) - 'modulo': Deterministic sampling using modulo on row number (repeatable) columns: Optional list of column names to include (default: all columns) catalog: Optional Databricks catalog name. Rejected on non-Databricks dialects (returns an error response).

Returns: TOON-encoded string with sample rows and metadata:

    status: "success" | "error"
    sample_id: string                  // on success only
    table_id: string                   // on success only
    sample_size: int                   // on success only
    actual_rows_returned: int          // on success only
    sampling_method: "top" | "tablesample" | "modulo"  // on success only
    rows: list of object               // on success only
    truncated_columns: list of string  // on success only
    sampled_at: ISO 8601 string        // on success only
    error_message: string              // on error only

Input Schema

TableJSON Schema

Name	Required	Default
`catalog`	No
`columns`	No
`table_name`	Yes
`sample_size`	No
`schema_name`	No
`connection_id`	Yes
`sampling_method`	No	top

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 20, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It discloses truncation of large text and binary data, sampling-method semantics, default behaviors, rejection of catalog on non-Databricks dialects, and a detailed error/success response envelope. This goes well beyond a minimal operation summary.

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?

The description is front-loaded with a one-sentence summary followed by logically grouped Args and Returns sections. Every sentence earns its place: parameter details, defaults, edge-case behavior, and return metadata are all useful to an agent. It is long because the tool is complex, not because of redundancy.

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?

Given 7 parameters, no annotations, zero schema-level descriptions, and no sibling differentiation in metadata, the description is complete enough to invoke the tool correctly. It covers parameter semantics, defaults, output format, success/error fields, and dialect-specific rejection. No critical operational detail appears to be missing.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate, and it fully does. Every parameter gets meaningful explanation: connection_id source, dotted table_name resolution, schema default behavior, sample_size range and default, each sampling_method value, optional columns, and catalog restrictions. This adds significant semantic value beyond the bare input schema.

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?

The description opens with a specific verb and resource: 'Retrieve sample data from a table' and expands with 'representative sample rows' plus sampling-strategy details. This clearly distinguishes the tool from siblings like get_table_schema, list_tables, and execute_query, since it is explicitly about sampled row data rather than metadata or arbitrary query results.

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?

The description gives strong context about how sampling strategies work and defaults, so an agent can choose among top, tablesample, and modulo. However, it never explicitly says when to use this tool instead of execute_query or get_table_schema, nor does it state exclusions or alternatives. The intended usage is implied by the 'sample' framing rather than stated as guidance.

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

Deploy Server