herald

Overview Schema Source Related Servers Discussions Admin

inbox_fetch

Fetch buffered work-chat messages to read and mark as taken, with optional filters for time, chat, and recovery of previously taken items.

Instructions

Fetch buffered messages for reading and mark them as taken. This is not an archive operation and must never be described as importing or recording them.

since and until are ISO-8601 timestamps compared against the message date in UTC. Rows carry the forwarded-message origin, so a forwarded quote keeps its real author instead of the person who forwarded it. Fetching does not remove anything. For archival work use inbox_export, import that bundle, then call inbox_done with the imported keys and an archive_ref.

Set include_taken to see messages handed out earlier but never archived - that is how a batch interrupted halfway is recovered.

Input Schema

TableJSON Schema

Name	Required	Default
`chat`	No
`limit`	No
`scope`	No	project
`since`	No
`until`	No
`project`	No
`include_taken`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.8.0Sep 25, 2026

addedInput schema / properties / project

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Project"
+}

addedInput schema / properties / scope

Added value: +{
+  "default": "project",
+  "enum": [
+    "project",
+    "source",
+    "all"
+  ],
+  "title": "Scope",
+  "type": "string"
+}

First observedv0.3.0Aug 13, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the annotations, the description adds valuable behavioral detail: messages are marked as taken, fetching does not remove anything, forwarded messages preserve their real author, and include_taken reveals previously handed-out but unarchived messages. These details meaningfully inform an agent about side effects and data semantics.

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 organized into three focused paragraphs, each carrying essential information: core behavior, date and data semantics, and recovery workflow. Every sentence adds value, and the most important warning is front-loaded.

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

Completeness4/5

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

The description covers the core workflow, non-destructive nature, date filtering, forwarded-origin behavior, and interrupted-batch recovery. The output schema exists, so return values need no explanation. The main gap is that some parameters (scope, chat, project, limit) are left to inference from names and defaults rather than being explicitly described.

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 0%, so the description must compensate. It explains since/until as ISO-8601 timestamps compared in UTC and explains include_taken, but it does not explain scope, chat, project, or limit. Those parameter names and the scope enum provide partial meaning, but the description leaves a real gap for the filtering parameters.

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: 'Fetch buffered messages for reading and mark them as taken.' It clearly distinguishes itself from archive operations and names the archival siblings, so an agent can identify what this tool does and what it does not do.

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 says this is not an archive operation, names the correct archival path (inbox_export, import, inbox_done), and explains when include_taken should be used for recovering interrupted batches. This gives clear when-to-use and when-not-to-use guidance.

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