MCPg - Production-grade PostgreSQL MCP Server

Overview Schema Source Related Servers Discussions Admin

TurboQuant approx candidates

turboquant_approx_candidates

Read-only

Retrieve approximate k-NN candidates from a turboquant index without exact reranking, returning candidate IDs, approximate distances, and ranks for a query vector.

Instructions

Run tq_approx_candidates against a turboquant index — approximate k-NN retrieval, no exact rerank. metric is 'cosine' | 'inner_product' | 'l2' (mapped to upstream's runtime metric text). half_precision=True switches to the halfvec overload. probes / oversample_factor are optional per-query knobs (consider calling recommend_turboquant_query_knobs first). Requires the pg_turboquant extension. Returns a list of candidate objects with candidate_id, approximate_distance, and approximate_rank.

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": {
      "schema": "<schema>",
      "table": "<table>",
      "id_column": "<id_column>",
      "embedding_column": "<embedding_column>",
      "query_vector": "<query_vector>",
      "metric": "<metric>",
      "candidate_limit": "<candidate_limit>"
    },
    "name": "turboquant_approx_candidates"
  }
}

Input Schema

Name	Required	Description
`table`	Yes
`metric`	Yes
`probes`	No
`schema`	Yes
`database`	No	Optional: a database id from list_databases, to target a configured secondary (read-only) database; omit for the primary. Database names that are not configured ids are rejected.
`id_column`	Yes
`query_vector`	Yes
`half_precision`	No
`candidate_limit`	Yes
`embedding_column`	Yes
`oversample_factor`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.8.4Nov 5, 2026

changedInput schema / properties / database / description

Previous value: -"Optional: target a configured secondary (read-only) database by name; omit for the primary. Call list_databases to see the configured ids."New value: +"Optional: a database id from list_databases, to target a configured secondary (read-only) database; omit for the primary. Database names that are not configured ids are rejected."

First observedv0.6.8Jul 6, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description still adds real behavior: the upstream metric-text mapping, the halfvec overload triggered by half_precision, and the precise return fields (candidate_id, approximate_distance, approximate_rank) with an explicit warning that scores are approximate. It omits cost/latency characteristics and any note on how probes affects recall versus speed.

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-loads the verb and the approximate/no-rerank distinction, then walks the knobs in the order an agent would set them. Dense but every clause carries information; the return-field sentence duplicates the output schema slightly.

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 an 11-parameter tool with an output schema, the description covers the non-obvious pieces (extension requirement, metric mapping, halfvec overload, knob recommendation) and correctly leaves return-shape detail to the output schema. It stops short of telling the agent where to discover valid table/column values, despite list_turboquant_indexes and get_turboquant_index_metadata being available siblings.

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 coverage is only 9%, so the description must carry the load, and it does explain metric's three legal values, half_precision's overload switch, and the role of probes/oversample_factor. However, seven required parameters (schema, table, id_column, embedding_column, query_vector, candidate_limit) get no semantic treatment — notably query_vector's array-or-string form and what candidate_limit actually bounds.

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?

States the exact underlying routine (tq_approx_candidates), the resource (a turboquant index) and the operation (approximate k-NN retrieval), and explicitly bounds it with 'no exact rerank'. That clause alone separates it from the sibling turboquant_rerank_candidates without opening either schema.

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?

Gives concrete preconditions (pg_turboquant extension required) and routes the agent to recommend_turboquant_query_knobs before tuning probes/oversample_factor. The 'no exact rerank' note implies when to escalate to the rerank sibling, but it never names turboquant_rerank_candidates explicitly, so the alternative is inferred rather than stated.

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

Deploy Server