> 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-stats.md).

# telys\_stats

Reference for the telys\_stats MCP tool — report row counts and index state for a Telys memory collection in the active store.

`telys_stats` returns **stats for a Telys memory collection**. 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 opens the named collection in the active store (`$TELYS_MEMORY_PATH`, default `~/.telys/memory`) and returns its runtime statistics — the collection name, its partition key name, and its live external-ID count, plus any counters the installed runtime provides. Use it to confirm a collection exists, count its records, and see how it is partitioned.

## Input schema

Required: `collection`.

| Field        | Type   | Required | Description                                                           |
| ------------ | ------ | -------- | --------------------------------------------------------------------- |
| `collection` | string | yes      | Name of the collection to report on. Must already exist in the store. |

## Output schema

| Field        | Type   | Description                                        |
| ------------ | ------ | -------------------------------------------------- |
| `collection` | string | Echoes the collection that was inspected.          |
| `stats`      | object | Runtime statistics for the collection (see below). |

The `stats` object always includes these fields, and may carry additional runtime-provided counters (row counts, dimension, and index state) depending on the installed runtime:

| Field          | Type    | Description                                                      |
| -------------- | ------- | ---------------------------------------------------------------- |
| `name`         | string  | The collection's name.                                           |
| `key_name`     | string  | The partition key name (the `partition_by` value, e.g. `scope`). |
| `external_ids` | integer | Number of live external IDs in the collection.                   |

## Example call

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

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "telys_stats",
    "arguments": {
      "collection": "notes"
    }
  }
}
```

{% endcode %}

The wrapped result:

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

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      { "type": "text", "text": "{\"collection\": \"notes\", \"stats\": {\"name\": \"notes\", \"key_name\": \"scope\", \"external_ids\": 128}}" }
    ],
    "isError": false
  }
}
```

{% endcode %}

Decoding the `text` field:

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

```json
{
  "collection": "notes",
  "stats": {
    "name": "notes",
    "key_name": "scope",
    "external_ids": 128
  }
}
```

{% endcode %}

{% hint style="info" %}
The exact counters inside `stats` come from the runtime and can vary by version, so treat fields beyond `name`, `key_name`, and `external_ids` as best-effort. For the fullest view, use the SDK's `Collection.stats()`.
{% endhint %}

## In practice

```
How many records are in my notes collection?
```

## Errors

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

## See also

* [Tool: telys\_list\_collections](https://docs.telys.ai/mcp/tool-list-collections.md) — discover the collections you can inspect.
* [Inspect collection stats](https://docs.telys.ai/working-with-data/inspect-stats.md) — the SDK's `Collection.stats()` in full.
* [MCP configuration & scoping](https://docs.telys.ai/mcp/configuration-and-scoping.md) — store path, install scope, and result wrapping.
