agentleFS

Send messages and comments

message_write

Destructive

Say something to other agents and people in this organization. A message, comment or room item cannot be unsent once read. Use comments for authorized review feedback, clarification questions and disagreements on shared content; continue the existing thread for the same issue. Messages are typed; a comment sits on a document or folder in the threads people use in the editor; a room is a shared space for agents of different chains. Two agents answering each other without new evidence are refused further rounds (loop_detected). Actions — send: send a typed message (kind: question, answer with reply_to, finding, request, handoff, commitment, with that kind's field) to identities, exact names or role:; location anchors it to a document, where its readers can see it in the console; wait=true with a deadline registers a wait for the reply. decline: say no to a message addressed to you; whoever asked is woken by it (message_id, note). close: close a message you sent (message_id, outcome done or broken for a commitment, note). comment: comment on a document or folder with authorized feedback or a new question (location, body); optional span or exact quote anchors passage-specific feedback; omit both for general discussion. reply_comment: reply in a comment thread to answer feedback, continue a discussion or report a fix with evidence (thread, body); status=taken says you took its work on, by a date (by, default seven days), status=reported says it is done, with where it is (link). resolve_comment: resolve an addressed or explicitly closed comment thread when authorized, as its author or an editor of the document (thread); a reply alone does not establish resolution. create_room: make a room (name, invite: identity ids or names); its documents live under the folder it returns. invite: invite identities to a room (room_id, invite). Invitees are identities in this organization; someone in another organization is reached by sharing a folder out with access_grant action=share_out, never by a room. join: join a room you were invited to (room_id). leave: leave a room (room_id). move_in: move content into a room (room_id, name, content, derived_from): a declassification, allowed only for data your chain can approve sharing; members who cannot read a source see it once its share request is approved.

Input Schema

Name	Required	Description
`by`	No	send: commitment / request: when, as an ISO date or time · reply_comment: reply_comment status=taken: the date you will have it by (default seven days from today)
`to`	No	send: identity id, an agent's @handle, exact name, or role:<capability>; repeatable
`body`	No	comment, reply_comment: the comment's text
`kind`	No	send: what the message is; each kind has its field
`link`	No	reply_comment: reply_comment status=reported: the document or folder the work is in. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too.
`name`	No	create_room, move_in: create_room: the room's name; move_in: the item's file name
`node`	No	send: the node it is about, by id. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too.
`note`	No	decline, close: a short note to the other side
`seat`	No	the seat token identity_write action=take_seat gave you; pass it on every call while you drive that agent
`span`	No	send: the section it is about, as its heading text · comment: the span id it is about, from browse action=spans
`wait`	No	send: register a durable wait for the reply, woken through your card's channel
`what`	No	send: commitment: what you commit to. A person reads this field on its own in the console, without the thread: it is clearest as a sentence or two that stands alone, with longer detail in a document named in evidence
`quote`	No	comment: the exact text it is about, when you have no span id
`action`	Yes	what to do; each action takes the arguments its line names
`answer`	No	send: answer: the answer itself, first. A person reads this field on its own in the console, without the thread: it is clearest as a sentence or two that stands alone, with longer detail in a document named in evidence
`invite`	No	create_room, invite: identity ids or exact names in this organization; repeatable
`packet`	No	send: handoff: the packet itself
`reason`	No	send, decline, close, create_room, invite, join, leave, move_in: why you are doing this, in one line (at most 200 characters); recorded with the event and exported with the log
`status`	No	reply_comment: reply_comment: say you took the thread's work on, or report it done; taken is refused while someone else holds the thread until its date
`thread`	No	reply_comment, resolve_comment: the thread's root id
`content`	No	move_in: what goes in: the raw text, or your own redaction of it
`finding`	No	send: finding: what you found. A person reads this field on its own in the console, without the thread: it is clearest as a sentence or two that stands alone, with longer detail in a document named in evidence
`outcome`	No	close: closed (default), or done or broken for a commitment
`request`	No	send: request: what you need, from whom. A person reads this field on its own in the console, without the thread: it is clearest as a sentence or two that stands alone, with longer detail in a document named in evidence
`room_id`	No	invite, join, leave, move_in: the room's id, from create_room or browse action=rooms
`summary`	No	send: handoff: what is being handed over. A person reads this field on its own in the console, without the thread: it is clearest as a sentence or two that stands alone, with longer detail in a document named in evidence
`deadline`	No	send: with wait: when to stop waiting (ISO)
`evidence`	No	send: what supports this — doc paths, commit hashes, message ids, URLs; repeatable
`location`	No	send: the document or folder it is about. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too. · comment: the document or folder path. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too.
`question`	No	send: question: what you are asking. A person reads this field on its own in the console, without the thread: it is clearest as a sentence or two that stands alone, with longer detail in a document named in evidence
`reply_to`	No	send: the message this replies to
`acting_as`	No	an agent identity below you (its id, from identity_write action=spawn) to make this one call as, with that agent's narrower access; for a helper whose session signs in as its person
`message_id`	No	decline, close: the message's id, from browse action=inbox, brief_me or send
`cannot_share`	No	send: answer: you hold more on this that the asker's chain may not see; the platform says so for you
`continuation`	No	send: with wait: a note to your future self about what to do when it resolves
`derived_from`	No	move_in: paths or node ids the content came from; repeatable. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too.
`idempotency_key`	No	Any unique string you choose for this write, e.g. a UUID. If you retry the call with the same key and the same arguments, the first answer is returned and nothing is done twice. Reusing a key for a different request is refused. Keys are kept 24 hours.

Output Schema

Name	Required	Description
`loop`	No
`room`	No
`wait`	No
`moved`	No
`rooms`	No
`action`	Yes	the action that answered
`thread`	No	resolve_comment: the thread resolved
`comment`	No
`message`	No
`comments`	No
`messages`	No
`replayed`	No
`truncated`	No	inbox: more are waiting past this page
`nextOffset`	No	inbox: the offset that shows them
`already_resolved`	No	resolve_comment: it was resolved before this call

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 30, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed66 schema fields changedOct 24, 2026

addedInput schema / properties / seat

Added value: +{
+  "description": "the seat token identity_write action=take_seat gave you; pass it on every call while you drive that agent",
+  "maxLength": 64,
+  "type": "string"
+}

changedInput schema / properties / to / description

Previous value: -"send: identity id, exact name, or role:<capability>; repeatable"New value: +"send: identity id, an agent's @handle, exact name, or role:<capability>; repeatable"

removedOutput schema / properties / comment / properties / anchor_prefix / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comment / properties / anchor_prefix / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comment / properties / anchor_suffix / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comment / properties / anchor_suffix / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comment / properties / author_id / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comment / properties / author_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comment / properties / commit_hash / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comment / properties / commit_hash / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comment / properties / marker_by / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comment / properties / marker_by / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comment / properties / marker_link / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comment / properties / marker_link / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comment / properties / quote / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comment / properties / quote / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comment / properties / span_id / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comment / properties / span_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comment / properties / span_text / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comment / properties / span_text / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / comments / items / properties / anchor_prefix / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / comments / items / properties / anchor_prefix / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / comments / items / properties / anchor_suffix / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / comments / items / properties / anchor_suffix / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comments / items / properties / author_id / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comments / items / properties / author_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / comments / items / properties / commit_hash / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / comments / items / properties / commit_hash / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comments / items / properties / marker_by / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comments / items / properties / marker_by / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / comments / items / properties / marker_link / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / comments / items / properties / marker_link / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comments / items / properties / quote / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comments / items / properties / quote / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comments / items / properties / span_id / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comments / items / properties / span_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / comments / items / properties / span_text / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / comments / items / properties / span_text / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / message / properties / about / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "nodeId": {
-        "type": "string"
-      },
-      "span": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "required": [
-      "nodeId",
-      "span"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "nodeId": {
+        "type": "string"
+      },
+      "span": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "nodeId",
+      "span"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / message / properties / closeNote / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / message / properties / closeNote / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / message / properties / recipients / items / properties / note / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / message / properties / recipients / items / properties / note / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / message / properties / replyTo / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / message / properties / replyTo / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / message / properties / roomId / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / message / properties / roomId / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / message / properties / senderId / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / message / properties / senderId / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / messages / items / properties / about / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "nodeId": {
-        "type": "string"
-      },
-      "span": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "required": [
-      "nodeId",
-      "span"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "nodeId": {
+        "type": "string"
+      },
+      "span": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "nodeId",
+      "span"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / messages / items / properties / closeNote / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / messages / items / properties / closeNote / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / messages / items / properties / recipients / items / properties / note / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / messages / items / properties / recipients / items / properties / note / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / messages / items / properties / replyTo / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / messages / items / properties / replyTo / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / messages / items / properties / roomId / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / messages / items / properties / roomId / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / messages / items / properties / senderId / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / messages / items / properties / senderId / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / nextOffset / anyOf

Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / nextOffset / type
```
Added value: +[
+  "number",
+  "null"
+]
```

removedOutput schema / properties / wait / properties / counterparty / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / wait / properties / counterparty / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / wait / properties / resolvedAt / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / wait / properties / resolvedAt / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed1 schema field changedOct 20, 2026

changedInput schema / properties / status / description

Previous value: -"reply_comment: reply_comment: say you took the thread's work on, or report it done"New value: +"reply_comment: reply_comment: say you took the thread's work on, or report it done; taken is refused while someone else holds the thread until its date"

Changed10 schema fields changedOct 16, 2026

addedInput schema / properties / acting_as

Added value: +{
+  "description": "an agent identity below you (its id, from identity_write action=spawn) to make this one call as, with that agent's narrower access; for a helper whose session signs in as its person",
+  "type": "string"
+}

changedInput schema / properties / by / description

Previous value: -"send: commitment / request: when, as an ISO date or time"New value: +"send: commitment / request: when, as an ISO date or time · reply_comment: reply_comment status=taken: the date you will have it by (default seven days from today)"

addedInput schema / properties / link

Added value: +{
+  "description": "reply_comment: reply_comment status=reported: the document or folder the work is in. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too.",
+  "type": "string"
+}

addedInput schema / properties / status

Added value: +{
+  "description": "reply_comment: reply_comment: say you took the thread's work on, or report it done",
+  "enum": [
+    "taken",
+    "reported"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / comment / properties / marker

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "taken",
+        "reported"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "a reply's status for the thread's work"
+}

addedOutput schema / properties / comment / properties / marker_by

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "taken: the date it is promised by, YYYY-MM-DD"
+}

addedOutput schema / properties / comment / properties / marker_link

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "reported: where the work is; null when you cannot read it"
+}

addedOutput schema / properties / comments / items / properties / marker

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "taken",
+        "reported"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "a reply's status for the thread's work"
+}

addedOutput schema / properties / comments / items / properties / marker_by

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "taken: the date it is promised by, YYYY-MM-DD"
+}

addedOutput schema / properties / comments / items / properties / marker_link

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "reported: where the work is; null when you cannot read it"
+}

Changed2 schema fields changedOct 14, 2026

addedOutput schema / properties / comment / properties / commit_hash

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "the document's commit when this was written; null on a folder's discussion"
+}

addedOutput schema / properties / comments / items / properties / commit_hash

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "the document's commit when this was written; null on a folder's discussion"
+}

Changed11 schema fields changedOct 12, 2026

changedInput schema / properties / location / description

Previous value: -"send: the document or folder it is about · comment: the document or folder path"New value: +"send: the document or folder it is about. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too. · comment: the document or folder path. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too."

addedOutput schema / properties / comment / properties / anchor_prefix

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "the text just before quote, which places it when the quote repeats"
+}

addedOutput schema / properties / comment / properties / anchor_suffix

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "the text just after quote"
+}

addedOutput schema / properties / comment / properties / span_text

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "comments: the span's current text"
+}

changedOutput schema / properties / comment / required

Previous value: -[
-  "id",
-  "location",
-  "thread_id",
-  "quote",
-  "author_id",
-  "author_display",
-  "actor_kind",
-  "span_id",
-  "body",
-  "resolved",
-  "created_at"
-]New value: +[
+  "id",
+  "location",
+  "thread_id",
+  "quote",
+  "anchor_prefix",
+  "anchor_suffix",
+  "author_id",
+  "author_display",
+  "actor_kind",
+  "span_id",
+  "body",
+  "resolved",
+  "created_at"
+]

addedOutput schema / properties / comments / items / properties / anchor_prefix

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "the text just before quote, which places it when the quote repeats"
+}

addedOutput schema / properties / comments / items / properties / anchor_suffix

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "the text just after quote"
+}

addedOutput schema / properties / comments / items / properties / span_text

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "comments: the span's current text"
+}

changedOutput schema / properties / comments / items / required

Previous value: -[
-  "id",
-  "location",
-  "thread_id",
-  "quote",
-  "author_id",
-  "author_display",
-  "actor_kind",
-  "span_id",
-  "body",
-  "resolved",
-  "created_at"
-]New value: +[
+  "id",
+  "location",
+  "thread_id",
+  "quote",
+  "anchor_prefix",
+  "anchor_suffix",
+  "author_id",
+  "author_display",
+  "actor_kind",
+  "span_id",
+  "body",
+  "resolved",
+  "created_at"
+]

addedOutput schema / properties / nextOffset

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "inbox: the offset that shows them"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "inbox: more are waiting past this page",
+  "type": "boolean"
+}

AddedOct 6, 2026

TDQS

A4.3/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description corroborates the irreversible nature ('cannot be unsent once read'), adds loop_detected, the declassification constraint on move_in ('allowed only for data your chain can approve sharing'), and the pending-share visibility rule. That is real added context beyond annotations. However, for an 11-action destructive tool it does not cover permission requirements per action, what a failed/refused call returns, or how seat/acting_as delegation affects authorization — a 3 reflects solid additions against remaining behavioral gaps.

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

Conciseness3/5

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

The purpose and the comment/room disambiguation are properly front-loaded, and given 37 parameters and 11 actions length is unavoidable. But the action rundown is a single run-on paragraph with em-dash dependent clauses, and the return-visibility rule ('A person reads this field on its own in the console') is repeated five times across parameter descriptions in the schema. Structure is serviceable but not tight.

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?

An output schema exists, so return values need not be described. For a high-complexity, destructive, 37-parameter multiplexer the description supplies the action taxonomy, cross-organizational boundary, irreversibility, and delegation caveats an agent needs before calling. Nothing essential 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 binding each action to its argument set ('decline: ... (message_id, note)', 'reply_comment: ... (thread, body)', 'move_in: ... (room_id, name, content, derived_from)'), which is genuine routing value the schema's flat property list does not supply. It also explains defaults the schema only hints at, such as status=taken defaulting to seven days. It stops short of explaining idempotency_key or seat semantics beyond what the schema states.

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 concrete verb and resource ('Say something to other agents and people in this organization') and then explicitly distinguishes the three modes it covers: messages, comments, and rooms. The distinctions ('a comment sits on a document or folder', 'a room is a shared space for agents of different chains') let an agent separate this from siblings like coordination_write or doc_update without schema inspection.

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?

Gives explicit when-to-use routing for near-identical actions: comments for 'authorized review feedback, clarification questions and disagreements'; reply_comment to 'answer feedback, continue a discussion or report a fix with evidence'; resolve_comment requires authorship or editor rights because 'a reply alone does not establish resolution'. It also states an exclusion — cross-organization reach is via access_grant action=share_out, 'never by a room' — and a behavioral guardrail (loop_detected refusal).

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

All agentleFS tools Inspect

Try in Browser

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?