Skip to main content
Glama

agentleFS

by com.agentlefs
OverviewDiscussionsAdmin

Read one item

read
Read-onlyIdempotent

Read one item by its location or id. A path or id you cannot read answers not-found, exactly as one that does not exist. action=document returns the document's text: the body comes first, frontmatter on its first line, and everything after the LAST ──── end of document ──── line describes it (location, type, node id, the commit to pass as expected_commit, its [[wikilinks]] both ways where you can read both ends, the memory and skills that apply in its folder, a console link to cite). The document ends two line breaks before that line, and those two are not part of it. A large document comes in parts, each ending ──── end of part: NOT the whole document ──── with the next offset. When somebody has it open in the editor, the body is their unsaved text and the answer says revision: live. Actions — document: a document (location or node; offset and maxBytes page a large one). message: one message (message_id). thread: a message thread with its loop risk (thread_id, or message_id for the thread it is in). truth: a truth with its debate (id). span_history: how a span was rewritten, and by how many editors (span). lesson: a knowledge item and its standing (id). lesson_notes: the usage notes left on a knowledge item (id). package: a public registry package and its public comments (slug, optional version); the registry spans every organization. room: a room and its members (room_id). wait: a wait's state (wait_id); with timeout_s (at most 25) it blocks until the wait resolves or the time runs out, answering pending. A wait resolves once: fired, timed_out, or counterparty_gone; a reply wait's resolution says replied (with replyId) or declined (with declinedBy) and points at the message rather than quoting it. changes: what changed on your subscriptions since you last acknowledged (coordination_write action=ack_changes).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNotruth: the truth's id · lesson, lesson_notes: an item id, or the citation search returns for it (knowledge:<id>@v<version>)
nodeNodocument: the document's id, as returned beside its location — survives a rename or a move, so a citation written into a stored document keeps pointing at the right thing. Give this OR location, never both. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too.
slugNopackage: the package's name in the registry
spanNospan_history: a span id, from browse action=spans
actionYeswhat to do; each action takes the arguments its line names
offsetNodocument: byte offset to start at (page large files)
room_idNoroom: the room's id, from create_room or browse action=rooms
versionNopackage: a published version; default the latest
wait_idNowait: the wait's id, from wait_for or browse action=waits
locationNodocument: full path from the workspace root, e.g. "handbook/vendor/acme.md". Give this OR node. A path is what a person reads; a node is what survives somebody reorganizing.
maxBytesNodocument: max bytes to return (clamped to MAX_READ_BYTES)
thread_idNothread: the thread's id
timeout_sNowait: block up to this many seconds (0–25) for it to resolve; omit to answer at once
message_idNomessage, thread: the message's id, from browse action=inbox, brief_me or send

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
itemNo
linkNo
loopNo
roomNo
textNothe answer as prose, for an action that answers in prose
waitNo
addedNo
itemsNo
linksNo
movedNo
notesNo
roomsNo
sinceNo
spansNo
truthNo
waitsNo
actionYesthe action that answered
debateNo
failedNo
pulledNo
truthsNo
historyNo
messageNo
packageNo
pendingNo
commentsNo
messagesNo
packagesNo
positionNo
proposalNo
replayedNo
standingNo
escalatedNo
subscriptionNo
retiringUntilNo
subscriptionsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedOutput schema / properties / added
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "created": {
+      "type": "boolean"
+    },
+    "diverged": {
+      "type": "boolean"
+    },
+    "follow": {
+      "enum": [
+        "latest",
+        "pinned"
+      ],
+      "type": "string"
+    },
+    "location": {
+      "type": "string"
+    },
+    "version": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "location",
+    "version",
+    "follow",
+    "diverged",
+    "created"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / package / properties / files
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "content": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "path",
+          "content"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "a folder package's documents by path; null for one document or knowledge item"
+}
    • changedOutput schema / properties / package / required
      Previous value: -[
-  "slug",
-  "kind",
-  "title",
-  "summary",
-  "publisher",
-  "version",
-  "body",
-  "fields",
-  "approvedBy",
-  "publishedAt",
-  "standing"
-]New value: +[
+  "slug",
+  "kind",
+  "title",
+  "summary",
+  "publisher",
+  "version",
+  "body",
+  "fields",
+  "approvedBy",
+  "publishedAt",
+  "standing",
+  "files"
+]
    • addedOutput schema / properties / packages / items / properties / files
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "content": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "path",
+          "content"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "a folder package's documents by path; null for one document or knowledge item"
+}
    • changedOutput schema / properties / packages / items / required
      Previous value: -[
-  "slug",
-  "kind",
-  "title",
-  "summary",
-  "publisher",
-  "version",
-  "body",
-  "fields",
-  "approvedBy",
-  "publishedAt",
-  "standing"
-]New value: +[
+  "slug",
+  "kind",
+  "title",
+  "summary",
+  "publisher",
+  "version",
+  "body",
+  "fields",
+  "approvedBy",
+  "publishedAt",
+  "standing",
+  "files"
+]
  2. Added

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already cover read-only/idempotent semantics, but the description adds substantial behavior the annotations cannot: unreadable paths answer not-found exactly like nonexistent ones, documents may be paged with `end of part` markers and a next offset, the body reflects unsaved editor text with `revision: live`, and waits resolve once as fired/timed_out/counterparty_gone or replied/declined. It also discloses that `thread` returns loop risk and that `changes` depends on a prior `ack_changes` acknowledgement.

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?

"Read one item by its location or id" front-loads the core purpose, and the action list at the end is an efficient index. The middle document-formatting passage is dense and carries some details (console link to cite, applicable memory and skills, the commit for expected_commit) that are nice-to-have rather than essential for invocation, so it is slightly over-specified for an otherwise tight definition.

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?

All 11 actions are covered with their inputs, paging is explained, not-found semantics are given, blocking behavior for `wait` is bounded (0–25s, answers pending), and the `changes` ack dependency is stated. An output schema exists, so return values need not be explained, yet the description still clarifies the document body layout and the trailing metadata block, leaving nothing an agent needs to call it correctly.

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 arguments (document: location or node plus offset/maxBytes; message: message_id; wait: wait_id with timeout_s; package: slug plus optional version) and by stating the mutual exclusion of location and node. It adds mapping and interaction semantics that the flat schema cannot express.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ("Read one item by its location or id") and then enumerates all 11 actions with exactly what each returns, so scope is unambiguous. It differentiates itself only indirectly from siblings (it repeatedly routes the agent to `browse`, `wait_for` and `coordination_write` for related operations) rather than stating outright that this tool is the single-item fetch versus `browse`/`search` for lists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied through the per-action argument map ("each action takes the arguments its line names") and through pointers to sibling tools for related work (browse action=spans, browse action=rooms, coordination_write action=ack_changes). There is no explicit when-to-use-this-vs-that guidance, e.g. why an agent should pick `read` over `search` or `access_read`, so the agent must infer the routing.

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

All agentleFS toolsInspect
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