> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/mcp/tool-search.md).

# telys\_search

Reference for the telys\_search MCP tool — semantic and lexical search over a Telys memory collection, with an optional single-key equality filter.

`telys_search` runs a **semantic + lexical search over a Telys memory collection** and returns the best-matching records. It is one of the 19 tools on the Telys MCP server (`telys mcp`), called by name over JSON-RPC 2.0 (protocol version `2025-06-18`) on stdio.

The server embeds `query` with its default embedder (`AlgentaMultigramEmbedder`, a lexical multigram space), searches the named collection in the active store (`$TELYS_MEMORY_PATH`, default `~/.telys/memory`), and returns the matching external IDs and their metadata. The client selects the tool and fills the arguments from a natural-language prompt — you rarely call it by hand.

## Input schema

Required: `collection`, `query`.

| Field        | Type    | Required | Default | Description                                                                                         |
| ------------ | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------- |
| `collection` | string  | yes      | —       | Name of the collection to search. Must already exist in the store.                                  |
| `query`      | string  | yes      | —       | Text query. The server embeds it with the default embedder, then searches.                          |
| `top_k`      | integer | no       | `5`     | Maximum number of hits to return, ordered best-first.                                               |
| `where`      | object  | no       | —       | A **single-key** equality filter (`Eq`). Exactly one key is allowed; more than one raises an error. |

{% hint style="info" %}
Over MCP, `where` accepts **one key only** — Telys filters are `Eq` (single-column equality), with no `AND`/`OR`/`NOT`/range operators. MCP-created collections are partitioned by `scope`, so `{"where": {"scope": "project:acme"}}` restricts the search to that partition. See [Filter results](https://docs.telys.ai/working-with-data/filter-results.md) and [Filters (Eq)](https://docs.telys.ai/reference/filters.md).
{% endhint %}

## Output schema

The tool returns a JSON object with this shape:

| Field        | Type   | Description                                                                                                                                                                                              |
| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collection` | string | Echoes the collection that was searched.                                                                                                                                                                 |
| `query`      | string | Echoes the query text.                                                                                                                                                                                   |
| `hits`       | array  | Matches ordered best-first. Each item is `{ "id": string, "score": number, "metadata"?: object }`. `score` is the similarity score; `metadata` is present only when the record was stored with metadata. |

{% hint style="info" %}
Each hit carries its similarity `score` alongside the id and metadata. For `explain` or `target_recall`, call the SDK's `Collection.search_text(...)` — those parameters are not exposed over MCP.
{% endhint %}

## Example call

A `tools/call` request from the client:

{% code title="request.json" %}

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "telys_search",
    "arguments": {
      "collection": "notes",
      "query": "how do partitions and scope keys work",
      "top_k": 3,
      "where": { "scope": "project:acme" }
    }
  }
}
```

{% endcode %}

Every result is wrapped so a failure never crashes the server: the payload is JSON-encoded into one text content block, and `isError` signals success or failure.

{% code title="response.json" %}

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"collection\": \"notes\", \"query\": \"how do partitions and scope keys work\", \"hits\": [{\"id\": \"n-018\", \"score\": 0.87, \"metadata\": {\"scope\": \"project:acme\", \"source\": \"design-doc\"}}, {\"id\": \"n-004\", \"score\": 0.74, \"metadata\": {\"scope\": \"project:acme\"}}]}"
      }
    ],
    "isError": false
  }
}
```

{% endcode %}

Decoding the `text` field yields the tool payload:

{% code title="payload.json" %}

```json
{
  "collection": "notes",
  "query": "how do partitions and scope keys work",
  "hits": [
    { "id": "n-018", "score": 0.87, "metadata": { "scope": "project:acme", "source": "design-doc" } },
    { "id": "n-004", "score": 0.74, "metadata": { "scope": "project:acme" } }
  ]
}
```

{% endcode %}

## In practice

Once connected, drive the tool in natural language and it fills the arguments:

```
Search my notes collection for what we decided about scope keys, and show the top 3.
```

## Errors

On failure the server returns the same envelope with `isError: true` and a single text block of the form `<Type>: <message>` — for example, searching a collection that does not exist. See [MCP configuration & scoping](https://docs.telys.ai/mcp/configuration-and-scoping.md) for the full error shape and [Exceptions & error codes](https://docs.telys.ai/reference/exceptions-and-errors.md).

## See also

* [Tool: telys\_add](https://docs.telys.ai/mcp/tool-add.md) — write the documents this tool searches.
* [Search by text](https://docs.telys.ai/working-with-data/search-by-text.md) — the SDK equivalent, with scores and `explain`.
* [Filter results](https://docs.telys.ai/working-with-data/filter-results.md) — how `Eq` / single-key filters behave.
* [MCP configuration & scoping](https://docs.telys.ai/mcp/configuration-and-scoping.md) — store path, install scope, and result wrapping.
