Skip to main content
Glama
server-noonien

server-noonien

Official

Read Changes

read_changes
Read-onlyIdempotent

Read only entities changed in a chosen time window, including current state and deleted names, to resume a known memory without loading the whole graph. Returns an until timestamp for continuation.

Instructions

Read only what changed in a window you choose: the entities touched in it, as they are now, and the names deleted in it. Use it instead of read_graph when you are coming back to a memory you already know — the whole graph for two changed entities costs the context you came to use. The window reaches five minutes further back than you ask, so a change written by a peer with a slightly lagging clock is not lost, and reading the same window twice is harmless. It also returns until, the moment it stopped at, in this node's clock: pass that back as since and the next read continues from there.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "read_changes"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoThe most entities to return; omit for all of them
sinceNoThe ISO-8601 moment to read after; omit it for the last five minutes, or pass the moment a previous call returned to continue where that call stopped
offsetNoHow many entities to skip before the page; omit for none

Output Schema

NameRequiredDescriptionDefault
sinceYes
untilYes
deletedYes
entitiesYes
relationsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.3.0

TDQS

A4.8/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 closed-world, so the safety profile is covered. The description adds substantive behavior the annotations cannot express: a deliberate five-minute horizon extension to tolerate peer clock lag, that re-reading the same window is harmless, and that deletions are surfaced by name alongside live entities.

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?

Scope is front-loaded, then the alternative, then behavioral caveats — a sound ordering with no filler sentences. The final sentence is long and packs the `until`/`since` round-trip together with a clock-domain caveat, which could be split for faster scanning.

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 an output schema present the description needn't catalog return fields, and it doesn't; it uses that space for the clock-skew tolerance, the deletion semantics, and the cursor pattern that an agent must know to page correctly. Nothing essential to calling this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description goes further by tying `since` to the returned `until` moment and explaining the five-minute lookback when `since` is omitted — context the schema hints at but does not fully motivate. `limit` and `offset` are left entirely to the schema, which is acceptable given how well documented they are.

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?

The first sentence gives a precise verb plus the exact scope of what is read: entities touched in a window, as they are now, plus the names deleted. It distinguishes itself from read_graph by name in the same breath, so an agent can tell the two apart without opening either 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?

It states explicitly when to prefer this over read_graph (returning to a memory you already know) and why (cost of pulling the whole graph for a couple of changed entities). It also documents the continuation pattern — pass back the returned `until` as `since` to continue — which is the primary non-obvious invocation mode.

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