MemAI

pulse

Read-onlyIdempotent

Warm up an AI agent session by returning the current checkpoint, pending reads, pinned memories, and next steps for a scope.

Instructions

Session warm-up: the latest checkpoint, what is pending, and what to read next.

Returns {project, latest_checkpoint, must_read, pinned, read_next, scope}, plus overdue when a checkpoint in scope stayed open past the age limit -- the same block must_read() carries, and read_next then puts settling it first.

latest_checkpoint is picked by created_at DESC, never by similarity -- a similarity-ranked top-1 can return a stale checkpoint over a same-day one, which is exactly the failure mode this avoids. It is returned in full (that's the point of pulse), with its relations attached so linked memories are visible without a separate get_relations call, and carries est_tokens, what this response already spent on it.

must_read is the categories list must_read(domain) returns without a type: a count per category (task, anti_pattern, handoff, note, diagram), leaving out the empty ones. read_next is the instruction to follow with it, before acting: pinned memories, then open tasks, then must_read(domain, type=...) for each other category, numbered when there is more than one step. It is "" when nothing is pending. A pulse lists no memories besides the checkpoint; must_read(domain, type=...) lists headers and get_memory(uid) opens one.

pinned counts the pins in scope the same way (see must_read()); when it is non-empty read_next asks for them before anything else.

scope is the rest of the brief: what the scope HOLDS. scope.by_type counts every memory per type and scope.subdomains says which level it is sitting in (own = filed there, subtree = with its descendants). Read them as the drill-down plan: search(query, domain=...) or list_by_domain(domain, type=..., limit=...) on the child that holds what you need. A pulse is the state of a scope, never its contents.

scope.stale is the one thing here about DECAY rather than contents: how many memories in the scope carry a review_after date that has passed. Present only when non-zero. It means somebody who knew the subject said when to look again and nobody has -- optimize_scan lists which ones, with their source_ref.

A scope holds what is CROSS-LISTED into it as well as what is filed there, so warming up an end-to-end flow brings back the routines that are steps of it wherever they live. scope.also counts how much of the brief arrived that way, and a subdomain carries its own also -- present only when non-zero, so a store that never cross-lists never sees the field.

A long checkpoint is cut (next names the rest).

Input Schema

Name	Required	Description	Default
`domain`	No	warms up a path and everything under it, so pulse('acme/x100') is the module-wide brief and pulse('acme/x100/p200') the routine's. A domain that names only the deep end of a path ('p200') is resolved to the branches it sits in -- `scope.paths` reports which, and an ambiguous name resolves to ALL of them.
`offset`	No	where the page of `scope.subdomains` starts.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.16.1Oct 16, 2026

addedInput schema / properties / domain / description

Added value: +"warms up a path and everything under it, so pulse('acme/x100') is the module-wide brief and pulse('acme/x100/p200') the routine's. A domain that names only the deep end of a path ('p200') is resolved to the branches it sits in -- `scope.paths` reports which, and an ambiguous name resolves to ALL of them."

removedInput schema / properties / domain / title
```
Removed value: -"Domain"
```

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "where the page of `scope.subdomains` starts.",
+  "type": "integer"
+}

removedInput schema / title
```
Removed value: -"pulseArguments"
```

First observedv0.1.0Jul 10, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: checkpoint selection is by created_at DESC 'never by similarity' with the rationale, relations are attached to avoid a get_relations call, est_tokens is disclosed, and truncation behavior is stated ('A long checkpoint is cut (`next` names the rest)'). Conditional fields (overdue, scope.stale, scope.also) and their presence rules are disclosed.

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 with a one-line summary, then organized field-by-field. It is long for a 2-param tool, but most sentences earn their place by explaining non-obvious return semantics. Minor redundancy in the repeated 'present only when non-zero' clauses keeps it from a 5.

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, the description carries the full burden and delivers: it enumerates the response keys (project, latest_checkpoint, must_read, pinned, read_next, scope, overdue) and explains each. An agent has everything needed to interpret the return value without a schema.

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 the schema already documents `domain` (path resolution, scope.paths, ambiguity) and `offset` (subdomain paging). The prose adds context on how scope behaves but doesn't extend the parameter contract beyond the schema. Baseline 3 applies where the schema does the heavy lifting.

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?

Opens with a specific verb+resource+scope: 'Session warm-up: the latest checkpoint, what is pending, and what to read next.' It explicitly differentiates from siblings, noting 'A pulse lists no memories besides the checkpoint; must_read(domain, type=...) lists headers and get_memory(uid) opens one.' An agent can distinguish it from search, must_read, and get_memory without opening a schema.

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?

Explicit when-to-use and routing to alternatives: 'Read them as the drill-down plan: search(query, domain=...) or list_by_domain(domain, type=..., limit=...)'. It also names the follow-up tool ('optimize_scan lists which ones') and clarifies read_next sequencing. Nothing about tool selection is left to inference.

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

pulse

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools