Retrieval over MCP.
Good retrieval over MCP comes from tools that each answer one kind of question, scope before they search, say what they drew from, and abstain rather than guess. The model, not your code, decides which tool to call, so the tool’s name, description and result shape are the retrieval design. Conxt’s memory server is the worked example throughout.
Why retrieval over MCP is different
In a normal RAG pipeline your code decides when to search, with what query, and how many results go into the prompt. Over MCP the model makes all three choices, from text you wrote months earlier. Four things follow:
- The description is the interface. The model sees a tool’s name, its description and its parameter descriptions, and nothing else. If two tools sound alike, it picks between them at random. If a description doesn’t say when to use the tool, it gets used at the wrong time.
- Every result costs the model’s context. Twenty raw matches of a few hundred words each can fill a turn and push the user’s own words out. The server should return the few things that answer the question, not everything that matched.
- The server often can’t see the client. A stateless HTTP server, as Conxt’s is, gets no session, no open files and no workspace roots. Anything it needs to scope the search, such as a project, must come in as a parameter.
- The model will use whatever comes back. Results are read as evidence. A near match, a stale fact or another project’s number is repeated as fact unless the result itself marks it as weak, old or out of scope.
Choosing a retrieval pattern
The eight patterns
Each pattern answers one kind of question. Give each its own tool, so the model’s choice of tool is also its choice of strategy.
| Pattern | Use it when the question is | What the tool does | Conxt tool |
|---|---|---|---|
| 1. Resolve to one answer | “What did we decide about X?” | Searches, checks the hits, retries wider once, and returns one answer with its source, or says nothing is on record | resolve_context |
| 2. Broad recall | “What do we know about X?” | Ranked semantic search; returns several short hits with ids | search_memory, get_context |
| 3. Typed lookup | “What are our coding rules?” | Filters by kind (decision, rule, open question) before ranking | search_decisions, get_memories with memory_type |
| 4. Standing context | Start of a session, before any question | Returns the few pinned facts every task needs | get_pinned, get_context |
| 5. Scoped recall | Work inside one project or team | Reads one project’s memory plus general memory, nothing else | project on every read tool; get_team_memories |
| 6. Newest first | “What is the latest on X?” or “What was true on 1 Oct?” | Filters to the topic, then sorts purely by date; can stop at a date | recall_as_of |
| 7. Provenance | “Who wrote this, and in which session?” | Lists what one agent or session wrote | list_agent_memories |
| 8. Abstain | Any question nothing on record answers | Says so plainly, and records the question as open | built into resolve_context |
Two rules hold across all eight:
- Search, then read. A search returns short hits with ids. A follow-up read fetches the one or two that matter in full. This keeps a broad search from flooding the context.
- Similar is not the same as answering. Ranking puts the closest match first even when nothing is close. Patterns 1 and 8 exist because a ranked list can’t say “nothing answers this”; Conxt’s
resolve_contexttreats a best match under 0.35 similarity as no answer.
Designing retrieval tools on the server
- Write the description as a routing rule. Open with the question the tool answers, then when not to use it and which tool to use instead. Conxt’s
recall_as_ofsays it answers “what’s the MOST RECENT thing you know about X” and whyget_contextcan’t. That one line stops the model using a ranked search for a recency question. - Describe every parameter, including the trap. A filter that looks like an identity gets filled with the caller’s own id. Conxt’s
search_memorysays outright thatagent_idis a filter and must not carry the caller’s id “out of habit”. - Scope in the query, before the limit. Filter by project or team inside the database query, then take the top N. Filtering after the limit returns fewer results than asked for, or none, and the shortfall never shows.
- Fail closed on scope. A project name that matches nothing is refused with the names that do exist, not widened to everything. A row with no project field is dropped while a project is in scope; it never counts as general memory.
- Say what the answer was drawn from. Put one line at the top of every scoped result, such as Conxt’s “Answered from the Lantern project and general memory.” Then the model, and the person reading over its shoulder, can tell scope from content.
- Return short hits with ids and dates. Return a title or first sentence, the type, the date and an id, and offer a separate read for the full text. A date on every hit lets the model judge staleness itself.
- Mark conflicts; don’t hide them or pick silently. When two memories disagree, say so, and prefer the newer one only when the rule is stated. Conxt’s
resolve_contextre-ranks a pair flagged as conflicting by recency instead of returning both raw. - Abstain in words the model will repeat. “Nothing on record answers ‘X’ yet” is quoted to the user. An empty list often isn’t; the model fills the gap from its own knowledge.
- Annotate honestly. Mark every read tool
readOnlyHint: true,destructiveHint: false,idempotentHint: true, and set all four hints to true or false, never null. Clients use these to decide what runs without asking, and directories reject servers whose hints don’t match what the tool does.
Using retrieval tools from an agent
These go in the agent’s instructions or a skill file, because the model won’t infer them from the tools alone.
- Retrieve before answering, not after. Anything that depends on the person’s own decisions, rules or projects is looked up first. An answer written first and checked second rarely gets corrected.
- Pass the scope every time. If the work is in one project, send
projecton each call. A missing scope reads every project, and that is how one client’s price ends up in another’s answer. - Ask the question, not keywords. Semantic search ranks better on “what payment processor do we use for Lantern” than on “payments”. Very short queries work for names: Conxt matches a short query against titles as text as well.
- Pick the tool by the question’s shape. One fact means pattern 1. “What do we know” means pattern 2. “Latest” or “as of” means pattern 6. A tool chosen by habit gives the wrong ranking for the question.
- Stop after two calls on one question. If two retrievals find nothing, say nothing is on record. More calls with reworded queries usually end in a weak match taken as an answer.
- Quote the scope line and the source. Tell the person which project the answer came from and when it was recorded. They can then catch a wrong-scope or stale answer.
- Write back what was settled. When the conversation settles something, save it as a decision in the same project. The next retrieval then finds it, and pattern 8 stops recording the question as open.
Query techniques
The query text decides most of what comes back, so write it for the search behind the tool, not for a person. Semantic search matches meaning, so a full question beats keywords. Name matching matches words, so a short name beats a sentence.
| Weak query | Better query | Why it works |
|---|---|---|
payments | what payment processor does Lantern use | Names the thing and the attribute; one word matches every memory that mentions money |
please find what we decided about the database, thanks | which database did we choose for the API | Filler words dilute the embedding; keep only the question |
Lantern pricing with no scope | what does a clinic pay per month, plus project: "Lantern" | Scope belongs in the parameter, so the query can spend its words on the question |
what is the latest deploy rule | deploy rule, sent to recall_as_of | “Latest” in the text doesn’t change ranking; a tool that sorts by date does |
not Stripe | which payment processor did we switch to | Embeddings ignore “not”; the negated word pulls Stripe memories to the top |
pricing, region and owner for Harborline | three queries: Harborline pricing, Harborline hosting region, Harborline owner | One query per fact; a mixed query ranks memories that touch a bit of each |
money back policy? (no match) | refund policy, then money back | Try the person’s own words, then the common synonym; stop after the second try |
Five habits behind the table:
- Ask for one fact per query. Split a question with several parts, run each, and combine the answers yourself.
- Put the subject and the attribute in the words. “Lantern” plus “payment processor” finds the one memory. Either alone finds dozens.
- Phrase it the way the memory was written. Memories are statements such as “We use Stripe for rider payments”. A query shaped like the expected statement (“we use … for payments”) often ranks the right memory first; this is the HyDE technique, short for hypothetical document embeddings.
- Use short queries for names and ids. In Conxt, a query of three content words or fewer is also matched as text against titles and bodies, so
Pedalway deploysfinds memories that a semantic score would put below the floor. A long query skips that text match. - Move filters out of the text. Project, team, type and date belong in parameters. Words like “latest”, “our rules” or “for Lantern” in the query only blur what the search is ranking.
Failure modes we have seen
Five of these shipped, or nearly shipped, in Conxt in October and November 2026. The stale-note row comes from a developer’s public report about another memory server.
| Failure | What the user saw | Fix |
|---|---|---|
| Another project’s facts in the answer | In a 16-question eval, 5 answers gave another project’s price, region, payment processor or owner | Project bins: every read takes project, filters inside the query, and fails closed on an unknown name |
| Scope filter applied after the limit | A project’s own memories missing from the top results, with no sign anything was cut | Filter in the query, before the limit, in search and in duplicate checks alike |
| An open question returned as the answer | “What did we decide?” answered with the memory that recorded it as undecided | Skip open questions as answers; below 0.35 similarity, say nothing is on record |
| An old, often-repeated fact beating a newer one | A superseded decision ranked first because it had been reinforced many times | recall_as_of sorts by date alone; conflicting pairs are re-ranked by recency |
| A stale note in one tool overriding a newer decision from another | Reported by a developer using a shared memory server across three tools, for two weeks | Record supersession with provenance: which tool decided what, and what replaced it |
| A near-duplicate saved across projects | One project’s memory merged into another’s as a “duplicate” | Duplicate checks look only within the memory’s own project and general memory |
Measuring retrieval
You can’t tune retrieval you don’t measure, and “it found something” is not a measure. Keep a fixed question set in the repository and run it on every change to ranking, scoping or descriptions.
- Write 15 to 30 real questions with the answer you expect, taken from how people actually ask. Include questions that should have no answer.
- Seed a test account with overlapping projects that share vocabulary: two clients that both have “payments”, “pricing” and “owner”. Cross-scope leaks only show up when the projects look alike.
- Score four numbers per run: right answer, from the right scope; wrong scope, an answer taken from another project or team; false answer, something returned where nothing was on record; and missed, nothing returned where an answer existed.
- Run it through a real client, not just the server’s functions. A model choosing the wrong tool is a retrieval failure the unit tests never see.
- Commit the harness and the results. A number nobody can rerun can’t be defended. Conxt’s matcher was tuned against 16 real questions in a harness that lived in a scratch folder, and the headline number couldn’t be reproduced later.
A wrong-scope answer is worse than a miss: the person trusts it. Track it as its own number and treat any rise as a regression.
Checklist before you ship a retrieval tool
- The description opens with the question the tool answers, and names the tool to use instead for nearby questions.
- Every parameter is described, including what not to pass.
- Scope (project, team, owner) is a parameter, applied inside the query before any limit.
- An unknown scope is refused with the valid choices, never widened.
- Scoped results start with a line saying what they were drawn from.
- Hits are short, with an id, type and date; full text comes from a separate read.
- Below a stated similarity floor, the tool says nothing is on record instead of returning the closest match.
- Conflicting memories are flagged, and any preference for the newer one is stated.
- All four annotation hints are set to true or false, and match what the tool does.
- The tool is in the committed question set, scored on right, wrong scope, false answer and missed.