MCPg - Production-grade PostgreSQL MCP Server

Overview Schema Source Related Servers Discussions Admin

Recommend HNSW ef search

recommend_hnsw_ef_search

Read-only

Recommends the minimum hnsw.ef_search value that meets a target recall@k by verifying an HNSW index, sampling queries, and sweeping ef values to compare recall and latency.

Instructions

Recommend an hnsw.ef_search value for a target recall@k — the actionable companion to analyze_hnsw_recall. Samples sample_queries rows (default 10) as query vectors, builds an exact brute-force top-k ground truth per query, sweeps ef_values (default 16/32/64/128/256) measuring mean recall@k and p50/p95 latency at each, and recommends the smallest value clearing target_recall (default 0.95). Unlike the single-query curve tool, this VERIFIES an HNSW index actually exists on the column (returns has_hnsw_index=false with guidance otherwise — a sweep without one just measures sequential scans). The query row is excluded from its own results. Requires the vector extension. Returns an object with available, has_hnsw_index, index_name, metric, k, target_recall, sample_queries, recommended_ef_search (int or null), detail, and sweep (list of objects with ef_search, mean_recall_at_k, p50_latency_ms, p95_latency_ms, meets_target).

Example: recommend_hnsw_ef_search(schema='public', table='docs', column='embedding', k=10, target_recall=0.95)

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>",
      "column": "<column>"
    },
    "name": "recommend_hnsw_ef_search"
  }
}

Input Schema

Name	Required	Description	Default
`k`	No
`table`	Yes
`column`	Yes
`metric`	No		l2
`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.
`target_recall`	No
`sample_queries`	No

Output Schema

Name	Required	Description	Default
`k`	Yes
`sweep`	Yes
`detail`	No
`metric`	Yes
`available`	Yes
`index_name`	Yes
`target_recall`	Yes
`has_hnsw_index`	Yes
`sample_queries`	Yes
`recommended_ef_search`	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.5/5.0

Behavior4/5

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

Annotations already cover safety (readOnlyHint=true, openWorldHint=false), and the description adds substantial behavior: sampling `sample_queries` rows, exact top-k ground truth per query, the default ef sweep ladder, exclusion of the query row from its own results, and the vector-extension requirement. The only gap is cost/latency expectations for a brute-force sweep over N queries, which an agent sizing this call would want.

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-loaded with purpose and mechanism, then verification behavior, then the example — a sensible order with no filler sentences. It runs long, and the enumerated return-object field list is the weakest part since an output schema is supplied.

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 sampling-plus-sweep tool with 8 parameters and a rich output schema, the description covers prerequisites (vector extension, HNSW index), the algorithm, and the recommendation rule, which is close to complete. It is docked slightly for enumerating return fields already present in the output schema and for leaving `metric` semantics unstated.

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

Parameters4/5

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

Schema description coverage is only 13% (only `database` is documented in-schema), so the description must compensate — and it does for the key knobs: `sample_queries` default 10, `target_recall` default 0.95, and `k` via recall@k plus the example call. However `metric` (default l2) is never explained, and `ef_values` is described as sweepable with defaults but does not exist in the schema, which could confuse an agent trying to set it.

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+resource ('Recommend an `hnsw.ef_search` value for a target recall@k') and immediately positions it against a named sibling ('the actionable companion to `analyze_hnsw_recall`'). The mechanism — sample queries, brute-force ground truth, ef sweep, pick smallest value clearing target — makes it unmistakable versus `vector_recall_at_k` or `recommend_ivfflat_probes`.

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

Usage Guidelines5/5

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

It states both when to use it (you want an actionable ef_search setting, not just a curve) and an explicit when-not/precondition: without an HNSW index the tool returns `has_hnsw_index=false` with guidance because 'a sweep without one just measures sequential scans'. It also names the alternative tool it complements, so the agent can route between the two without opening schemas.

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

Deploy Server