> 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

`telys_search` runs a **semantic + lexical search over a Telys memory collection** and returns the best-matching records. It is one of the five 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](/working-with-data/filter-results.md) and [Filters (Eq)](/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, "metadata"?: object }`. `metadata` is present only when the record was stored with metadata. |

{% hint style="warning" %}
`telys_search` returns IDs and metadata, **not similarity scores**. For scores, `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\", \"metadata\": {\"scope\": \"project:acme\", \"source\": \"design-doc\"}}, {\"id\": \"n-004\", \"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", "metadata": { "scope": "project:acme", "source": "design-doc" } },
    { "id": "n-004", "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](/mcp/configuration-and-scoping.md) for the full error shape and [Exceptions & error codes](/reference/exceptions-and-errors.md).

## See also

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/mcp/tool-search.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.