Skip to main content
Glama
SynapCores MCP Server

SynapCores MCP Server

Official

Semantic search in a vector collection

semantic_search
Read-onlyIdempotent

Search vector collections for items closest in meaning to a natural-language query; return matching IDs, similarity scores, and metadata, with optional metadata filters applied after top-k retrieval.

Instructions

Find the k items in a vector collection closest in meaning to a natural-language query: the tool embeds query_text with the engine's configured embedding model, searches the collection, and returns {results: [{id, similarity, metadata}], count, collection}. Use it for vector collections; for vectors stored in SQL table columns, use query with EMBED() and COSINE_SIMILARITY(). filter keeps only results whose metadata equals the given values and is applied after the top-k search, so fewer than k results can come back. Read-only.

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": {
      "collection": "<collection>",
      "query_text": "<query_text>"
    },
    "name": "semantic_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
kNoNumber of nearest matches to return (default 10, max 1000).
filterNoMetadata values results must equal, e.g. {"category": "electronics"}; applied after the top-k search.
collectionYesName of the vector collection to search.
query_textYesNatural-language text to search for; it is embedded for you.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.0.1
    • changedInput schema / properties / collection / description
      Previous value: -"Vector collection / space name"New value: +"Name of the vector collection to search."
    • changedInput schema / properties / filter / description
      Previous value: -"Optional metadata equality predicates, e.g. {\"category\": \"electronics\"}. Applied client-side after search; for large collections, prefer pre-filtered queries."New value: +"Metadata values results must equal, e.g. {\"category\": \"electronics\"}; applied after the top-k search."
    • changedInput schema / properties / k / description
      Previous value: -"Top-K results to return (default: 10, max: 1000)"New value: +"Number of nearest matches to return (default 10, max 1000)."
    • changedInput schema / properties / query_text / description
      Previous value: -"Natural-language query to embed and search with"New value: +"Natural-language text to search for; it is embedded for you."
  2. First observedv1.0.0

TDQS

A4.3/5.0
Behavior4/5

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

The annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description still adds real behavioral context beyond them: it explains that the query is embedded with the engine's configured model, that `filter` runs after top-k so fewer than k results may return, and what the response object contains. It does not discuss cost, latency, or behavior when the collection is empty or missing.

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 definition is front-loaded with the core operation before the alternative-tool routing and the filter caveat, and every sentence carries information. It is a single dense block, so the filter caveat and the read-only note are slightly buried rather than visually separated.

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?

With no output schema, the description compensates by spelling out the return shape, and it covers the non-obvious post-filter behavior and the sibling alternative. For a 4-parameter read tool this is nearly complete, though error or empty-result behavior and the embedding-model configurability are unaddressed.

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 100%, so all four parameters are already documented, including the default and max for `k` and the post-search application of `filter`. The description reinforces the meaning of `query_text` being embedded and the consequence of filtering after top-k, but it largely restates rather than extends what the schema provides, so the baseline of 3 is appropriate.

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 names a specific verb and resource (find the k nearest items in a vector collection) and immediately defines the mechanism: embedding `query_text`, searching, and returning `{results, count, collection}`. It explicitly distinguishes itself from the sibling `query` tool, which handles vectors stored in SQL columns.

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 gives an explicit routing rule: use this tool for vector collections, and use `query` with EMBED() and COSINE_SIMILARITY() for vectors held in SQL table columns. That is a clear when-to-use and when-to-use-something-else statement, not an implied one.

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