MCPg - Production-grade PostgreSQL MCP Server

Overview Schema Source Related Servers Discussions Admin

Hybrid BM25 vector search

hybrid_bm25_vector_search

Read-only

Combines BM25 keyword search and pgvector semantic search with Reciprocal Rank Fusion to return one ranked result set, solving relevance gaps when either method alone misses matches.

Instructions

Combine a BM25 search and a pgvector search via Reciprocal Rank Fusion — the canonical v2 pattern ParadeDB documents in the 2025-10-22 'Hybrid Search Missing Manual' blog post. Returns hits as {id, score, bm25_rank, vector_rank}. score is the summed sum(weight * 1.0 / (k + rank)) across both legs; per-leg ranks are surfaced for transparency (either can be NULL if a row only appeared in one leg's top-K). distance_op is the pgvector operator ('<=>'/'<->'/'<#>' — RRF is operator-agnostic). bm25_columns=None searches the whole BM25 index; bm25_columns=["col"] restricts the BM25 leg to a single field. Defaults mirror upstream's demonstrated form (cosine, k=60, equal weights, per_leg_limit=20). Requires the pg_search and pgvector extensions.

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>",
      "query_text": "<query_text>",
      "query_vector": "<query_vector>",
      "key_field": "<key_field>",
      "vector_column": "<vector_column>",
      "final_limit": "<final_limit>"
    },
    "name": "hybrid_bm25_vector_search"
  }
}

Input Schema

Name	Required	Description	Default
`k`	No
`table`	Yes
`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.
`key_field`	Yes
`query_text`	Yes
`bm25_weight`	No
`distance_op`	No		<=>
`final_limit`	Yes
`bm25_columns`	No
`query_vector`	Yes
`per_leg_limit`	No
`vector_column`	Yes
`vector_weight`	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

A3.6/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, so safety is covered; the description adds genuinely new behavior: the exact return shape, the fact that bm25_rank/vector_rank can be NULL when a row appears in only one leg's top-K, the RRF scoring formula, and the extension prerequisites. It doesn't mention cost or latency of running two ranked legs, which is the only meaningful omission.

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 core operation and the return shape are front-loaded, and the parameter notes follow in a compact sequence. The citation of the specific blog post and date is the one piece of provenance that doesn't help an agent decide or invoke, though it does justify the 'canonical' claim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so explaining return values isn't strictly required (the score formula explanation is a bonus). Against a 14-parameter, 7-required tool, however, the definition leaves the join key, the vector column's dimension expectations, and the final_limit/per_leg_limit relationship unspecified, which are exactly the fields an agent is most likely to get wrong.

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 description coverage is only 7% across 14 parameters, so the description has to carry the load. It does explain k (60), distance_op with its three operators and operator-agnosticism, bm25_columns=None vs single-field behavior, equal default weights, and per_leg_limit=20 — but key_field, vector_column, final_limit, and the query_vector format are left entirely undocumented in both places, including how final_limit relates to per_leg_limit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states precisely what the tool does: it fuses a BM25 leg and a pgvector leg with Reciprocal Rank Fusion and returns ranked hits. That is far more specific than the name alone. It stops short of 5 because it never names the sibling `hybrid_search` it is presumably a v2 of — 'the canonical v2 pattern' only implies an alternative exists.

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?

Usage is implied rather than stated: the reader infers you should call this when you want RRF-fused keyword+semantic ranking, and the prerequisite (pg_search and pgvector extensions) is called out. There is no explicit when-not, and no routing guidance against `hybrid_search`, `vector_search`, or `full_text_search`, all of which sit in the same sibling list.

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

Deploy Server