Tirith

Official

Overview Schema Source Related Servers Discussions Admin

notice_list

List change notices for a path, since a time, or only unread ones. Viewing unread notices marks them as seen so they do not appear again.

Instructions

List change notices for a path, since a time, or only those you have not been shown (unread=true), newest first. unread without path is scoped to the paths you hold, and all=true looks beyond them. Listing unread notices marks them seen by you, durably, so they do not come back. A claim's brief already delivers the unread notices for the paths it claims; use this for other paths or older pages. 20 rows per page; pass next_before as before for older rows.

Input Schema

TableJSON Schema

Name	Required	Description
`all`	No	With `unread`, look beyond the paths you hold.
`path`	No	Only notices affecting this path.
`agent`	Yes	Your stable agent name.
`limit`	No	Rows to return (default 20, max 200), newest first.
`since`	No	Only notices published at or after this RFC 3339 timestamp.
`before`	No	Only notices published before this cursor: an RFC 3339 timestamp or a previous response's `next_before`.
`unread`	No	Only notices you neither published nor were already shown. Without `path` or `all`, this is scoped to the paths you currently hold.

Output Schema

TableJSON Schema

Name	Required	Description
`count`	No	Rows in this response.
`total`	No	Rows that matched, across all pages.
`status`	Yes	ok, with zero rows and a message when unread is scoped to paths and you hold none. invalid: bad input.
`message`	No	Human-readable detail, on most outcomes other than ok.
`notices`	No	Newest first: id, kind, summary, from, to, affected_paths, published_by, published_at. Rows returned for unread=true are now marked seen by you.
`truncated`	No	True when older rows were left out.
`next_before`	No	Present when truncated: pass it back as before for the next older page.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv1.1.2Sep 18, 2026

addedInput schema / properties / agent / description
```
Added value: +"Your stable agent name."
```

addedInput schema / properties / all / description

Added value: +"With `unread`, look beyond the paths you hold."

addedInput schema / properties / before / description

Added value: +"Only notices published before this cursor: an RFC 3339 timestamp\nor a previous response's `next_before`."

addedInput schema / properties / limit / description

Added value: +"Rows to return (default 20, max 200), newest first."

addedInput schema / properties / path / description

Added value: +"Only notices affecting this path."

addedInput schema / properties / since / description

Added value: +"Only notices published at or after this RFC 3339 timestamp."

addedInput schema / properties / unread / description

Added value: +"Only notices you neither published nor were already shown. Without\n`path` or `all`, this is scoped to the paths you currently hold."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "Any result may also carry lost, inbox, inbox_more and persist_error; see guide.",
+  "properties": {
+    "count": {
+      "description": "Rows in this response.",
+      "type": "integer"
+    },
+    "message": {
+      "description": "Human-readable detail, on most outcomes other than ok.",
+      "type": "string"
+    },
+    "next_before": {
+      "description": "Present when truncated: pass it back as before for the next older page.",
+      "type": "string"
+    },
+    "notices": {
+      "description": "Newest first: id, kind, summary, from, to, affected_paths, published_by, published_at. Rows returned for unread=true are now marked seen by you.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "status": {
+      "description": "ok, with zero rows and a message when unread is scoped to paths and you hold none. invalid: bad input.",
+      "enum": [
+        "ok",
+        "conflict",
+        "not_found",
+        "none",
+        "invalid",
+        "cancelled"
+      ],
+      "type": "string"
+    },
+    "total": {
+      "description": "Rows that matched, across all pages.",
+      "type": "integer"
+    },
+    "truncated": {
+      "description": "True when older rows were left out.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "type": "object"
+}

First observedv1.1.1Sep 18, 2026

TDQS

A4.9/5.0

Behavior5/5

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

The description discloses a critical side effect beyond the annotations: 'Listing unread notices marks them seen by you, durably, so they do not come back.' It also reveals pagination behavior with 20-row pages and the next_before cursor semantics, which annotations do not cover. No contradiction with destructiveHint=false exists since marking-as-read is not destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tight, front-loaded with purpose, then scope, side effect, alternative routing, and pagination. Every sentence adds distinct value with no filler or redundancy. It is dense but immediately scannable.

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?

For a tool with 7 parameters and no output schema details in the description, this is complete: it covers what the tool does, how unread scoping works, the side effect of reading, when to use an alternative, and pagination mechanics. The existing output schema covers return shape, and the agent parameter is explained in the schema.

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 the baseline is 3, but the description adds cross-parameter meaning beyond the schema: unread without path is scoped to held paths, all=true expands beyond them, and next_before from a prior response should be passed as before for older pages. This is substantive supplementary semantics beyond the individual parameter descriptions.

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 description opens with a specific verb and resource—'List change notices'—and immediately distinguishes filtering dimensions: path, since time, and unread status, with ordering. It also contrasts with the claim brief and notice_publish sibling, so an agent can identify this as the retrieval tool rather than a mutation tool.

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?

The description explicitly tells the agent when NOT to use this tool: 'A claim's brief already delivers the unread notices for the paths it claims; use this for other paths or older pages.' This is clear routing guidance, and the unread/all scoping rules further clarify which invocation is appropriate.

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