How do you expose hybrid search as an agent tool via MCP?

Exposing hybrid search as an agent tool via MCP means the model can call Weaviate’s weaviate-query-hybrid the same way it calls any other MCP tool. Hybrid search blends BM25 keyword matching with vector similarity inside one ranked list. Alpha steers that blend. Tenants, filters, and property targets keep the call inside the right slice of data. This chapter explains why hybrid belongs on the tool surface, how to describe and parameterize the MCP tool so agents use it deliberately, how Weaviate Engram offers the same hybrid idea for scoped memory without hand-rolled glue, and how to keep tool calls from drifting across collections or tenants they should never open.

Why Is Hybrid Search the Right Default Tool for Agents?

Agents ask messy questions. Some turns need an exact plate number or sheet code. Others paraphrase a vague goal. Pure vector search misses brittle tokens. Pure BM25 misses synonyms. Hybrid runs both legs and fuses the rankings so either signal can promote a hit. Weaviate’s MCP server exposes that operator directly as weaviate-query-hybrid. The agent does not invent a merge. The database already knows how.

That matters in the Thought-Action-Observation loop. When the model decides it needs evidence, a single well-described hybrid tool beats a pair of brittle custom functions. The call returns ranked objects with scores. The agent reads them and continues. Filters and tenant names apply before scoring, so authorization and isolation stay inside the engine rather than in prompt hope.

If hybrid is the tool, the next design job is teaching the model when and how to call it.

How Should You Shape the MCP Hybrid Tool for Reliable Calls?

Weaviate lets you override tool and argument descriptions through MCP_SERVER_CONFIG_PATH. Write descriptions that name your domain. Say what collection holds map sheets. Say that alpha near zero favors sheet codes and near one favors paraphrase. Say that tenant_name must match the authenticated workshop bay. Vague defaults invite the model to guess collection names and wander.

The tool arguments map to real hybrid controls. query and collection_name are required. Optional alpha defaults to the server hybrid default near three quarters toward vectors when left unset on the wire. Optional limit, tenant_name, target_properties, return_properties, return_metadata, and filters tighten the search. Teach the agent to set lower alpha when operators hunt codes like plate ids. Teach higher alpha when language is fuzzy. Cap limit so tool results do not flood the context window.

Always bind tenant identity from the session when collections are multi-tenant. Do not let the model invent tenant_name from free text if that string is a security boundary. The same rule applies to filters that encode customer ids. Hybrid is powerful. Unscoped hybrid is a leak waiting to happen.

Product memory still needs a simpler path than teaching every agent to pick Weaviate collection names. Engram wraps hybrid recall for user-scoped memories.

How Does Engram Expose Hybrid Recall Without an MCP Wrapper?

Engram’s recommended retrieval type is hybrid. You call memories.search with HybridRetrieval through retrieval_config. Engram runs on Weaviate underneath, so you still get keyword-plus-vector ranking. You also get project keys, groups, topics, and required user_id isolation for user-scoped topics. For everyday agent memory, that is usually the better default than wiring MCP hybrid to a raw memory collection.

Keep the split clear in architecture. Use MCP weaviate-query-hybrid for operational collections your app already manages in Weaviate. Use Engram hybrid search for durable facts the pipeline extracted from conversations and notes. Both speak hybrid. They answer different ownership questions.

A cartography lab scenario shows the Engram side with codes that BM25 should catch and phrasing that vectors should catch.

What Does Hybrid Memory Search Look Like in Engram Code?

A map drawer stores plate notes per bench. Sheet codes must match. Language about coastline revisions still needs semantic recall. Hybrid covers both.

import os
from engram import EngramClient, HybridRetrieval

client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])

drawer = "map-drawer-12"
group = "cartography_lab"

run = client.memories.add(
    "Drawer 12 holds coastal sheet C-4417 with the revised jetty line from March. "
    "Ink the harbor sounding updates in blue before the Friday proof. "
    "Do not pull C-4402 for this client; that plate still shows the old breakwater.",
    user_id=drawer,
    group=group,
)
client.runs.wait(run.run_id)

# Hybrid helps both the plate code and the paraphrase about harbor updates
hits = client.memories.search(
    query="C-4417 harbor sounding updates for the jetty proof",
    user_id=drawer,
    group=group,
    retrieval_config=HybridRetrieval(limit=5),
)

assert any("C-4417" in m.content for m in hits)
assert any("jetty" in m.content.lower() for m in hits)

If this same shop also kept a Weaviate MapCatalog collection for published SKUs, an MCP client could call weaviate-query-hybrid on that collection with a domain-specific description and a session-bound tenant. Engram remains the store for bench-level working memory. MCP hybrid remains the tool for catalog search. The agent sees two clear jobs instead of one overloaded function.

Tool quality still fails when descriptions, alpha habits, or permissions drift. Close those gaps before you scale the agent fleet.

What Failure Modes Show Up When Hybrid Is a Tool?

Agents love to call search with giant limits. Truncate aggressively. Prefer five tight hits over fifty noisy ones. Agents also forget alpha. When operators complain that codes never surface, lower alpha in the tool guidance and in examples. When paraphrase fails, raise it. Measure on real shop queries, not on a single demo sentence.

Permission mistakes are worse than ranking mistakes. Grant read_mcp and read_data only on collections the agent should see. Keep write MCP tools disabled unless mutation is required. Log hybrid tool calls with collection, tenant, query, and result ids so you can replay bad answers. Pair those checks with Engram cross-user probes so memory hybrid stays isolated even when catalog hybrid is wide.

Hybrid search earns its place on the MCP surface because agents live in mixed language. Wire the tool with honest descriptions, bound tenants, and small limits. Reach for Engram when the artifact you need is scoped personal or workspace memory rather than a raw collection scan.

Our next chapter, How do granular MCP permissions work for memory access?, tightens the authorization story. It shows how MCP-specific RBAC permissions combine with collection and tenant rights so hybrid tools cannot outrun the access model you just relied on.