MCP Tools

pretensor serve registers the tools below over MCP. They are read-only against the indexed Kuzu graph — no tool mutates schema, runs DDL, or queries rows from your source database. For agent-side guidance on when to reach for which tool, see Use Cases; for what’s actually returned and the data-handling boundary, see Privacy Model.

All tools accept a database argument naming a registered connection (the same name shown by pretensor list). When omitted on tools where it’s optional, Pretensor selects a database deterministically when only one is registered, and asks for disambiguation otherwise.

Tool index

Tool	Purpose
`list_databases`	Inventory of indexed connections with table counts and staleness
`schema`	Live catalog: node labels, edge types, properties
`query`	BM25 keyword search over table and entity metadata
`semantic_search`	Meaning-based table search via embeddings (requires the `embeddings` extra)
`context`	Full table context — columns, joins, lineage, cluster
`cypher`	Read-only Kuzu Cypher against the graph
`traverse`	Best-cost join paths between two tables
`impact`	Downstream tables reachable via FK and inferred edges
`consumers`	Services that read or write a table, from `pretensor analyze`
`detect_changes`	Compare live schema to last indexed snapshot
`compile_metric`	Compile semantic-layer YAML to validated SQL
`validate_sql`	Validate SQL against the indexed graph

`list_databases`

Lists every database registered with pretensor add or indexed under a config-file source.

Input: none.

Returns: { databases: [{ name, db_type, table_count, column_count, row_count, schemas, capabilities, last_indexed, is_stale, staleness_days, … }] }.

Use it when the agent doesn’t know which database to operate against, or before any other tool that takes a database argument.

`schema`

Returns the graph-level catalog the indexer wrote — node labels, edge types, available properties — without traversing any data. Use it before writing a Cypher query so the agent knows what’s actually in the graph.

Input:

database (string, required)
label (string, optional) — narrow the response to one node label

Returns: { nodes: [{ label, description, properties: [{ name, type }] }], edges: [{ type, from, to, description, properties }] }.

`query`

BM25 keyword search across table descriptions, dbt aliases, column comments, and entity metadata. The intent is finding objects whose exact names you don’t know.

Input:

q (string, required) — natural-language query
db (string, optional) — limit to one database; if omitted, searches every indexed database
limit (int, default 10, range 1–50)

Returns: { query, db, results: [{ node_type, name, database_name, connection_name, description, snippet, score }] }. When the embeddings extra is installed and table vectors exist, results are reranked with Reciprocal Rank Fusion of BM25 and cosine similarity, and the envelope gains rerank: "rrf".

Use it when the agent has a business question (“daily revenue by region”) and needs to discover which tables are even relevant. Pair with context once a candidate is found.

`semantic_search`

Natural-language semantic search over tables by cosine similarity against the persisted embedding vectors. Requires the embeddings extra; without it (or when no tables carry vectors), the tool returns a structured hint pointing at query instead.

Input:

query (string, required) — natural-language query to embed and match
k (int, default 10, range 1–50)
database (string, optional) — restrict to one connection or logical database
cluster (string, optional) — restrict to one cluster id

Use it when keyword search misses — the agent is looking for tables by what they contain (“customer lifetime spend”) rather than what they’re named.

`context`

Full structural and semantic context for one table. This is the high-information, single-table tool — replaces having an agent stitch together DESCRIBE, \d+, and FK introspection by hand.

Input:

table (string, required) — fully qualified or unique
db (string, optional)
detail (enum: summary | standard | full, default standard)
include_similar (bool, default false) — append embedding-based similar tables (requires the embeddings extra)
similar_k (int, default 5, range 1–50)

Returns: columns, FK relationships in and out, dbt lineage edges, classification (role + confidence), cluster membership, sample referring/referenced tables, and — at detail: full — column statistics summaries. With include_similar, the response gains similar_tables and similar_reason.

`cypher`

Read-only Kuzu Cypher against the indexed graph. The query must begin with a read clause (MATCH, OPTIONAL MATCH, RETURN, WITH, UNWIND, CALL), and mutating or I/O keywords (CREATE, DELETE, SET, COPY, EXPORT, DROP, ATTACH, LOAD, …) are rejected at the tool layer before they reach the database.

Input:

query (string, required) — Kuzu Cypher
database (string, required)
timeout_seconds (float, default 5.0, range 0.1–120)

Returns: { rows: [...] } on success (plus an optional warning), { error: ... } on parse or runtime failure.

Use it when the agent needs a graph-shaped query that doesn’t fit traverse / impact — e.g., “which tables have more than three FK in-edges and live in cluster X.” Most agents should reach for the higher-level tools first.

`traverse`

Compute best-cost join paths between two tables, including precomputed inferred joins (column-name matches, value-distribution overlap) the indexer built. Supports cross-database paths when entity-link edges exist.

Input:

from_table (string, required)
to_table (string, required)
database (string, required)
to_database (string, optional) — for cross-database joins. Note: accepted by the handler but not yet listed in the tool’s advertised input schema, so strict schema-validating clients may reject it.
max_depth (int, default 4, range 1–8)
top_k (int, default 3, range 1–10)
edge_types (array, optional) — restrict to ["fk"] or ["fk", "inferred"]
max_inferred_hops (int, default 2, range 0–8)

Returns: { from, to, database, paths: [{ confidence, ambiguous, semantic_label, steps: [...], sql_hint }], used_precomputed }, plus a warning when nothing was found and a tie_break block when embedding reranking broke a cost tie.

Use it when the agent needs to write a JOIN but doesn’t know the path — especially when the FK is implicit (named differently on each side, or expressed in dbt rather than as a database constraint).

`impact`

Downstream tables reachable from a starting table (or column) via FK and inferred-join edges. Grouped by hop distance and confidence.

Input:

table (string, required)
database (string, required)
column (string, optional) — narrow to a specific column’s downstream
max_depth (int, default 3, range 1–8)

Returns: { target: { table, column }, database, impact: { direct, two_hop, three_hop, low_confidence }, total_affected }. Each affected entry also lists the code consumers of that table when pretensor analyze has recorded any.

Use it when the agent is reasoning about a schema change (“what breaks if I rename customer.legacy_id?”) or scoping the blast radius of a backfill.

`consumers`

External code locations (services) that read or write a table, recorded by pretensor analyze.

Input:

table (string, required) — table name or schema.table
database (string, required)
op (enum: read | write, optional) — filter by operation
min_confidence (number, default 0.6, range 0–1)

Returns: consumer entries carrying service, file, line range, op, kind, and confidence.

Use it when the question is “which services touch this table?” — pairing naturally with impact before a schema change.

`detect_changes`

Compare the live schema to the last indexed snapshot. Read-only: it does not mutate the graph or trigger a re-index — it only reports what would change.

Input:

database (string, required)

Returns: { database, last_indexed, checked_at, changes: [{ type, target, schema, table, … }], graph_impact, affected_join_paths, affected_metrics, summary, recommendation } — plus up_to_date: true when nothing changed.

Use it when an agent or scheduled check needs to decide whether to call pretensor reindex, or before trusting tool output that may be based on a stale graph.

`compile_metric`

Compile a semantic-layer YAML definition into validated SQL for one indexed database. Validates table and column references, expands joins, and returns the SQL plus its dependency list.

Input:

semantic_yaml (string, required) — the metric definition as YAML text
metric (string, required) — the metric name to compile
database (string, required)

Returns: { sql, validation: {...}, dependencies: [...] }.

`validate_sql`

Statically validates a SQL statement against the indexed graph — checks table existence, column existence, and join validity — before the agent (or a human) runs it.

Input:

sql (string, required)
database (string, required)
dialect (string, default "postgres")

Returns: { valid, missing_tables, missing_columns, invalid_joins, suggestions }.

Use it when an agent has authored SQL via prompt + reasoning and you want a structural sanity check before execution. Suggestions include nearest-name matches for typos.

Resources

pretensor serve also exposes read-only MCP resources at stable URIs. Resources are bulk Markdown reads — useful for grounding an agent’s system prompt or answering “what’s in this database?” without burning tool-call budget.

URI	Returns
`pretensor://databases`	Registry overview — every indexed database with table counts and capabilities
`pretensor://db/{name}/overview`	Per-database summary: table count, entity count, staleness warning
`pretensor://db/{name}/clusters`	Leiden communities and the tables they contain
`pretensor://db/{name}/metrics`	`MetricTemplate` nodes with their compiled SQL and dependencies

Compatibility note

Pretensor is in beta — 0.1.0 is the first stable release. Tool inputs and return shapes can still change between minor versions until 1.0.0 — pin exact versions for reproducibility, and re-read this page after upgrading.