MemAI

list_by_domain

Read-onlyIdempotent

List memories under a domain and its subdomains, newest first, to find relevant records when search misses.

Instructions

List memories for a domain and its subdomains, most recent first.

Fallback when search misses. A task row carries state (open, completed or cancelled) and progress {done, total}.

Returns {"results": [...], "est_tokens": N}. Content is snippet-truncated per result -- call get_memory(uid) for the full record; a result's est_tokens estimates what that full record costs, and the top-level est_tokens is the sum over the results.

Input Schema

Name	Required	Description	Default
`type`	No	one memory type, as search() takes it; empty is every type.
`limit`	No	the most results to return.
`domain`	Yes	a path, matched from the outermost segment in: 'acme/x100' lists the module's own memories plus every routine under it. A domain that matches no path is retried as a run of segments INSIDE one, so list_by_domain('p200') still finds the routine once it lives at 'acme/x100/p200'. The literal reading wins whenever it has rows, and an ambiguous name (the same code under two modules) covers both branches rather than picking one -- each row's `domain` says which branch it came from. list_domains() is the way to see the paths first.
`offset`	No	where the page starts; `next_offset`, when present, starts the next.
`status`	No	'active', 'archived' or 'all'. Closing a task archives its memory, so list_by_domain(domain, type='task', status='archived') returns the completed and cancelled tasks.	active
`subtree`	No	False lists what is filed at exactly that path and nowhere deeper.

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedv0.16.1Oct 16, 2026

addedInput schema / properties / domain / description

Added value: +"a path, matched from the outermost segment in: 'acme/x100' lists the module's own memories plus every routine under it. A domain that matches no path is retried as a run of segments INSIDE one, so list_by_domain('p200') still finds the routine once it lives at 'acme/x100/p200'. The literal reading wins whenever it has rows, and an ambiguous name (the same code under two modules) covers both branches rather than picking one -- each row's `domain` says which branch it came from. list_domains() is the way to see the paths first."

removedInput schema / properties / domain / title
```
Removed value: -"Domain"
```
addedInput schema / properties / limit / description
```
Added value: +"the most results to return."
```
removedInput schema / properties / limit / title
```
Removed value: -"Limit"
```

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "where the page starts; `next_offset`, when present, starts the next.",
+  "type": "integer"
+}

addedInput schema / properties / status / description

Added value: +"'active', 'archived' or 'all'. Closing a task archives its memory, so list_by_domain(domain, type='task', status='archived') returns the completed and cancelled tasks."

removedInput schema / properties / status / title
```
Removed value: -"Status"
```

addedInput schema / properties / subtree / description

Added value: +"False lists what is filed at exactly that path and nowhere deeper."

removedInput schema / properties / subtree / title
```
Removed value: -"Subtree"
```

addedInput schema / properties / type / description

Added value: +"one memory type, as search() takes it; empty is every type."

removedInput schema / properties / type / title
```
Removed value: -"Type"
```

removedInput schema / title

Removed value: -"list_by_domainArguments"

Changed1 schema field changedv0.6.0Oct 3, 2026

addedInput schema / properties / status

Added value: +{
+  "default": "active",
+  "title": "Status",
+  "type": "string"
+}

Changed2 schema fields changedv0.1.1Sep 13, 2026

addedInput schema / properties / subtree

Added value: +{
+  "default": true,
+  "title": "Subtree",
+  "type": "boolean"
+}

changedOutput schema / (root)

Previous value: -{
-  "properties": {
-    "result": {
-      "items": {
-        "additionalProperties": true,
-        "type": "object"
-      },
-      "title": "Result",
-      "type": "array"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "title": "list_by_domainOutput",
-  "type": "object"
-}New value: +null

First observedv0.1.0Jul 10, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context on top: return shape {'results': [...], 'est_tokens': N}, snippet truncation, the need to call get_memory(uid) for full records, and the meaning of both the per-result and top-level est_tokens. This is exactly the kind of value structured fields don't carry.

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?

Front-loaded purpose followed by usage, then return contract — good ordering with no filler sentences. The long parenthetical clauses (est_tokens, truncation) are dense but each earns its place; slightly verbose overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and rich annotation coverage, the description carries the return-format burden and does so fully: result shape, truncation behavior, token estimation, and the follow-up get_memory call. Nothing an agent needs to call it correctly is missing.

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 six parameters are already documented in the schema (including the subtle domain retry/ambiguity semantics). The description adds no parameter-level meaning beyond that; the task-row 'state'/'progress' note describes return values, not inputs. Baseline 3 applies.

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?

States a specific verb+resource with scope and ordering: 'List memories for a domain and its subdomains, most recent first.' It also positions itself against a named sibling ('Fallback when search misses'), so an agent can distinguish it from search without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Fallback when search misses' gives an explicit trigger condition, and the domain parameter routes the agent to list_domains() to discover paths first. It does not spell out the inverse (when search is preferable) or exclusion cases, so it falls short of a full 5.

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

list_by_domain

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools