DBMCP

find_pk_candidates

Find columns in a table that could serve as primary keys, using declared constraints and uniqueness/nullability checks. Returns candidates with evidence to guide schema analysis.

Instructions

Identify columns that meet primary key candidacy criteria.

EXPERIMENTAL — Results are based on common heuristics but have not been battle-tested for utility. They may contain false positives or exclude valid candidates. Use as a starting point for investigation, not as definitive answers.

Discovers PK candidates via two approaches:

Constraint-backed: Columns with declared PK or UNIQUE constraints
Structural: Columns that are unique, non-null, and match the type filter

Does not detect composite keys. Structural uniqueness checks query the full table and may be slow on very large tables.

Args: connection_id: Connection ID from connect_database table_name: Table to search for PK candidates. 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. type_filter: SQL types considered for structural PK candidacy. Default: ["int", "bigint", "smallint", "tinyint", "uniqueidentifier"]. Set to empty list to disable type filtering. catalog: Optional Databricks catalog name. Rejected on non-Databricks dialects (returns an error response). On Databricks the catalog is threaded end-to-end (IDENT-08): the existence check and PK discovery run against the requested catalog via catalog-scoped reflection (cross-catalog supported — no default-catalog binding required).

Returns: TOON-encoded string with status, table/schema metadata, and candidates list:

    status: "success" | "error"
    table_name: string                 // on success only
    schema_name: string                // on success only
    candidates: list                   // on success only
        column_name: string
        data_type: string
        is_constraint_backed: bool
        constraint_type: "PRIMARY KEY" | "UNIQUE" | null
        is_unique: bool                // all values distinct
        is_non_null: bool              // no nulls
        is_pk_type: bool               // data_type matches type_filter
    error_message: string              // on error only

Error conditions: - Invalid connection_id: returns status "error" with error_message - Table not found: returns status "error" with error_message - No candidates found: returns status "success" with empty candidates list

Input Schema

TableJSON Schema

Name	Required	Description	Default
`catalog`	No
`table_name`	Yes
`schema_name`	No
`type_filter`	No
`connection_id`	Yes

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.7/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses the experimental heuristic nature, potential false positives, inability to detect composite keys, full-table scanning behavior, Databricks catalog threading, and error conditions. This goes well beyond a minimal safety profile.

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?

The description is long, but it is well structured into sections (purpose, args, returns, errors) and nearly every sentence adds necessary detail for a tool with five parameters and a structured result. It could be slightly trimmed without losing meaning, hence not a perfect 5.

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?

The description is complete for safe invocation: it documents all parameters, the output schema fields, error conditions, edge cases like empty candidate lists, and dialect-specific behavior. An agent has enough to select and invoke the tool correctly without needing additional sources.

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 explain every parameter, and it does. It defines connection_id, table_name with dotted-name resolution, schema_name defaults, type_filter defaults and empty-list behavior, and catalog's Databricks-specific semantics. This fully compensates for the schema's lack of narrative detail.

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: 'Identify columns that meet primary key candidacy criteria.' It further clarifies two discovery approaches (constraint-backed and structural), which makes the tool's scope precise and distinct from sibling tools like find_fk_candidates and get_column_info.

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?

The description gives clear usage context: it is experimental, meant as a starting point for investigation rather than definitive answers, and warns that structural checks may be slow on large tables. It does not explicitly name alternative tools or state when not to use it, so it stops short of a full 5.

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

Deploy Server