agentleFS

Search

search

Read-onlyIdempotent

Search what you can read, and get back hits you can cite: each has a citation (location@commit, and #span for a block), its freshness (when committed; for a mirror, when it last synced and who connected it) and a trust signal (verified_truth, stated_truth, mirror or text) with the truths about it. A document hit also carries matched: why it matched, strongest first (titles, labels, text, meaning). score names no strategy, so matched is the only field that says which of them found the hit. PUBLIC GITHUB, a separate corpus: scope "public" searches agent instruction files (skills, CLAUDE.md, AGENTS.md, cursor rules, copilot instructions, llms.txt) written by strangers, not your organization. They come back only in public, never in hits: 5 by default (limit up to 20), each a pointer with its licence, capabilities (what it would have an agent do), stars, whether its publisher is known, when its repository's agent context changed, a commit-pinned citation, a link for a person, a sourceLink to GitHub (readable whatever the licence) and an agentlefs://public/ URI. The citation and sourceLink are portable references; the uri pins no commit. No field proves one file changed. licensed_only keeps the files whose text may be served. With within owner/repo/path (or the URI) it opens one file in file: its text if licensed, otherwise a description and the link; a long file comes in parts of up to 50,000 bytes (max_bytes for smaller ones), the next by offset; the file's own text is everything above the last ──── end of … line, less its last two line breaks, and an entry before it says it is public. A public query needs two characters or more. Your own folder named public is scope /public. how: auto (default) runs every strategy and merges them; meaning ranks by what a passage is about; text matches the words in a body; titles finds a document by name (file name, title or frontmatter aliases, typo-tolerant, and the excerpt says which name matched). Documents come best first, and a document hit's score is the quantity they were ordered by, comparable only within one answer; a hit's line, when set, is the line its excerpt is from. Narrow it with scope (a location), within (one document: returns its matching spans), thread (a message id: searches that thread), or source (one connected source, by id or a location in it). follow (1-3) adds the links around each hit. Nothing you cannot read is returned or counted. Hits are documents, their spans, messages, and published knowledge (lessons, dead ends, workflows, skills): a knowledge hit cites knowledge:@v, is dated by its last change, and its trust is validated_knowledge, unvalidated_knowledge or refuted_knowledge. Knowledge matches the query as one phrase, so a key term finds a lesson where a whole question may not; drafts are never returned. skills names the skills (.claude/skills or .agents/skills) and memory names the CLAUDE.md and AGENTS.md files that apply at scope and at the hits' folders, ones you can read only.

Input Schema

Name	Required	Description
`how`	No
`seat`	No	the seat token identity_write action=take_seat gave you; pass it on every call while you drive that agent
`limit`	No	how many hits (at most 20 with scope "public")
`query`	No	what you want to know (not needed to open a public file with scope "public" and within)
`scope`	No	"public" searches the public corpus; a folder path (e.g. "specs", or "/public" for your own folder named public) limits the search to it (a document is refused: search one document with within); omit for everything you can read
`follow`	No
`offset`	No	scope "public" with within only: where in the file to start, in bytes as read action=document takes it (a part gives nextOffset)
`source`	No	a sync source id, or a location inside the mirror
`thread`	No	a message id in the thread
`within`	No	a document path or node id; with scope "public", one public file as owner/repo/path, its agentlefs://public/ URI, a hit's citation or its GitHub link at a commit (either also says whether the repository has moved on since), or its link (not one from another console served under a path prefix). A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too.
`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
`max_bytes`	No	scope "public" with within only: the largest part to return, in bytes (default and ceiling 50,000); a part never splits a character, so one smaller than the character at offset holds that character
`licensed_only`	No	scope "public" only: just the files whose licence lets their text be served (default false: every match, unlicensed ones described with a link)

Output Schema

Name	Required	Description
`file`	No
`hits`	Yes
`mode`	Yes
`query`	Yes
`memory`	No	the memory files (CLAUDE.md, AGENTS.md) of scope and of the hits' folders and above, only ones you can read
`public`	No
`skills`	No	the skills that apply at scope and at the folders of the hits (a .claude/skills/<name>/SKILL.md or .agents/skills/<name>/SKILL.md there or above), only ones you can read
`degraded`	Yes
`truncated`	Yes
`licensedOnly`	No
`spansPending`	No

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"

Changed52 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"
+}

removedOutput schema / properties / file / properties / body / anyOf

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

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

removedOutput schema / properties / file / properties / bytes / anyOf

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

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

removedOutput schema / properties / file / properties / changedAt / anyOf

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

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

removedOutput schema / properties / file / properties / citedCommit / anyOf

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

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

removedOutput schema / properties / file / properties / citedCommitCollected / anyOf

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

addedOutput schema / properties / file / properties / citedCommitCollected / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```

removedOutput schema / properties / file / properties / citedLink / anyOf

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

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

removedOutput schema / properties / file / properties / description / anyOf

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

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

removedOutput schema / properties / file / properties / nextOffset / anyOf

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

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

removedOutput schema / properties / file / properties / sourceLink / anyOf

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

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

removedOutput schema / properties / file / properties / stars / anyOf

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

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

removedOutput schema / properties / file / properties / withheld / anyOf

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

addedOutput schema / properties / file / properties / withheld / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / hits / items / properties / freshness / properties / commit / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / hits / items / properties / freshness / properties / commit / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / hits / items / properties / freshness / properties / committedAt / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / hits / items / properties / freshness / properties / committedAt / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / hits / items / properties / freshness / properties / source / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "aclRecorded": {
-        "type": "boolean"
-      },
-      "id": {
-        "type": "string"
-      },
-      "lastError": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "lastSyncedAt": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "location": {
-        "type": "string"
-      },
-      "name": {
-        "type": "string"
-      },
-      "provider": {
-        "type": "string"
-      },
-      "pulledBy": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "syncLagS": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "required": [
-      "id",
-      "provider",
-      "name",
-      "location",
-      "pulledBy",
-      "lastSyncedAt",
-      "syncLagS",
-      "lastError",
-      "aclRecorded"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "aclRecorded": {
+        "type": "boolean"
+      },
+      "id": {
+        "type": "string"
+      },
+      "lastError": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "lastSyncedAt": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "location": {
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "provider": {
+        "type": "string"
+      },
+      "pulledBy": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "syncLagS": {
+        "type": [
+          "number",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "id",
+      "provider",
+      "name",
+      "location",
+      "pulledBy",
+      "lastSyncedAt",
+      "syncLagS",
+      "lastError",
+      "aclRecorded"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / hits / items / properties / knowledgeId / anyOf

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

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

removedOutput schema / properties / hits / items / properties / line / anyOf

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

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

removedOutput schema / properties / hits / items / properties / location / anyOf

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

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

removedOutput schema / properties / hits / items / properties / messageId / anyOf

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

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

removedOutput schema / properties / hits / items / properties / nodeId / anyOf

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

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

removedOutput schema / properties / hits / items / properties / score / anyOf

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

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

removedOutput schema / properties / hits / items / properties / spanId / anyOf

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

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

removedOutput schema / properties / public / items / properties / bytes / anyOf

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

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

removedOutput schema / properties / public / items / properties / changedAt / anyOf

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

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

removedOutput schema / properties / public / items / properties / description / anyOf

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

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

removedOutput schema / properties / public / items / properties / sourceLink / anyOf

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

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

removedOutput schema / properties / public / items / properties / stars / anyOf

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

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

Changed1 schema field 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"
+}

Changed5 schema fields changedOct 6, 2026

changedInput schema / properties / offset / description

Previous value: -"scope \"public\" with within only: where in the file to start, in bytes as read_org_doc takes it (a part gives nextOffset)"New value: +"scope \"public\" with within only: where in the file to start, in bytes as read action=document takes it (a part gives nextOffset)"

changedOutput schema / properties / hits / items / properties / matched / description

Previous value: -"Why this hit matched, strongest evidence first: its file name, title or an alias (titles), a label on it (labels), a literal phrase in its body (text), or a semantically near chunk (meaning). `labels` is evidence you can read but not yet ask for: `how` takes the other three. Document hits carry it; hits from within one document, one thread, or knowledge do not, because there the single strategy is already named in `mode` and `score` is the rank key."New value: +"Why this hit matched, names before body evidence: its file name, title or an alias (titles), a label on it (labels), its words in a chunk by full-text search (keyword), a literal phrase in its body (text), or a semantically near chunk (meaning). `labels` and `keyword` are evidence you can read but not ask for: `how` takes titles, text and meaning. Document hits carry it; hits from within one document, one thread, or knowledge do not, because there the single strategy is already named in `mode` and `score` is the rank key."

changedOutput schema / properties / hits / items / properties / matched / items / enum

Previous value: -[
-  "titles",
-  "labels",
-  "text",
-  "meaning"
-]New value: +[
+  "titles",
+  "labels",
+  "keyword",
+  "text",
+  "meaning"
+]

addedOutput schema / properties / memory

Added value: +{
+  "description": "the memory files (CLAUDE.md, AGENTS.md) of scope and of the hits' folders and above, only ones you can read",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "changed": {
+        "type": "boolean"
+      },
+      "folder": {
+        "type": "string"
+      },
+      "location": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "location",
+      "folder",
+      "changed"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / skills

Added value: +{
+  "description": "the skills that apply at scope and at the folders of the hits (a .claude/skills/<name>/SKILL.md or .agents/skills/<name>/SKILL.md there or above), only ones you can read",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "changed": {
+        "description": "committed since this session last read it",
+        "type": "boolean"
+      },
+      "description": {
+        "type": "string"
+      },
+      "folder": {
+        "description": "the folder it applies in and below; empty for the whole organization",
+        "type": "string"
+      },
+      "location": {
+        "description": "the SKILL.md to read",
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "name",
+      "description",
+      "location",
+      "folder",
+      "changed"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed2 schema fields changedOct 5, 2026

addedOutput schema / properties / hits / items / properties / freshness / properties / spansPending

Added value: +{
+  "description": "true when this document's span map is still being built: staleSpans is 0 because nothing is recorded yet, not because nothing is stale",
+  "type": "boolean"
+}

addedOutput schema / properties / spansPending
```
Added value: +{
+  "type": "boolean"
+}
```

Changed1 schema field changedOct 3, 2026

changedInput schema / properties / scope / description

Previous value: -"\"public\" searches the public corpus; a folder path (e.g. \"specs\", or \"/public\" for your own folder named public) limits the search to it; omit for everything you can read"New value: +"\"public\" searches the public corpus; a folder path (e.g. \"specs\", or \"/public\" for your own folder named public) limits the search to it (a document is refused: search one document with within); omit for everything you can read"

Changed2 schema fields changedSep 30, 2026

addedInput schema / properties / scope / description

Added value: +"\"public\" searches the public corpus; a folder path (e.g. \"specs\", or \"/public\" for your own folder named public) limits the search to it; omit for everything you can read"

removedInput schema / properties / token

Removed value: -{
-  "description": "Bearer token identifying the principal. Usually omitted — supplied by the transport. Over stdio it selects the principal (else the server's AGENTLEFS_TOKEN env). Over HTTP the Authorization header decides and passing this argument is REFUSED, not ignored: it cannot override who you are acting as.",
-  "type": "string"
-}

Changed11 schema fields changedSep 30, 2026

addedInput schema / properties / licensed_only

Added value: +{
+  "description": "scope \"public\" only: just the files whose licence lets their text be served (default false: every match, unlicensed ones described with a link)",
+  "type": "boolean"
+}

addedInput schema / properties / limit / description

Added value: +"how many hits (at most 20 with scope \"public\")"

addedInput schema / properties / max_bytes

Added value: +{
+  "description": "scope \"public\" with within only: the largest part to return, in bytes (default and ceiling 50,000); a part never splits a character, so one smaller than the character at offset holds that character",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "description": "scope \"public\" with within only: where in the file to start, in bytes as read_org_doc takes it (a part gives nextOffset)",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

changedInput schema / properties / query / description

Previous value: -"what you want to know"New value: +"what you want to know (not needed to open a public file with scope \"public\" and within)"

changedInput schema / properties / within / description

Previous value: -"a document path or node id. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too."New value: +"a document path or node id; with scope \"public\", one public file as owner/repo/path, its agentlefs://public/ URI, a hit's citation or its GitHub link at a commit (either also says whether the repository has moved on since), or its link (not one from another console served under a path prefix). A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too."

removedInput schema / required
```
Removed value: -[
-  "query"
-]
```

addedOutput schema / properties / file

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "body": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "bodyTruncated": {
+      "description": "the body is one part of the file, not all of it: offset and nextOffset say which",
+      "type": "boolean"
+    },
+    "bytes": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "the size of the served text in bytes, which parts are counted in; for a withheld file, the size GitHub reported"
+    },
+    "capabilities": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "changedAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "when the repository's agent context last changed: one history lookup per repository (its skills folder, or its first file), so a sibling file moves it too. Freshness, not a per-file clock"
+    },
+    "citation": {
+      "description": "github:owner/repo@<commit>:path, the form to write down: within reopens it and says whether the repository has moved on",
+      "type": "string"
+    },
+    "citedCommit": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "the repository commit a citation, or a GitHub link at a commit, named, when the file was opened by one"
+    },
+    "citedCommitCollected": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "whether that is the repository commit this copy was collected at; false means the repository has moved on since, not that this file did. No field here proves this one file changed: changedAt is per repository, and bytes counts GitHub's size on a search hit but the stored text's on an opened file, so the two do not compare"
+    },
+    "citedLink": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "the file on GitHub at the cited commit, outside this server: the corpus holds one commit per file, so body is those bytes only when citedCommitCollected is true"
+    },
+    "collectedAt": {
+      "type": "string"
+    },
+    "commit": {
+      "type": "string"
+    },
+    "description": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "kind": {
+      "enum": [
+        "skill",
+        "agents_md",
+        "claude_md",
+        "cursor_rule",
+        "copilot_instructions",
+        "llms_txt"
+      ],
+      "type": "string"
+    },
+    "knownPublisher": {
+      "description": "the publisher is an organization we recognise (model labs, agent and editor makers): provenance, not an endorsement",
+      "type": "boolean"
+    },
+    "licence": {
+      "type": "string"
+    },
+    "link": {
+      "description": "where a person reads it: this server's console catalog page, or GitHub when it has no console. within reopens this server's links; another console's may not",
+      "type": "string"
+    },
+    "maxBytes": {
+      "description": "the part size this read asked for; pass it again with nextOffset to keep parts this size",
+      "type": "number"
+    },
+    "name": {
+      "type": "string"
+    },
+    "nextOffset": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "offset": {
+      "type": "number"
+    },
+    "origin": {
+      "const": "public",
+      "type": "string"
+    },
+    "path": {
+      "type": "string"
+    },
+    "redistributable": {
+      "description": "whether the licence lets agentleFS serve the text: false means body is null, withheld says why, and sourceLink is where to read it",
+      "type": "boolean"
+    },
+    "repo": {
+      "type": "string"
+    },
+    "sourceLink": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "the file on GitHub at the commit collected, readable whatever its licence; null when no commit is known. within reopens it and says whether the repository has moved on"
+    },
+    "stars": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "uri": {
+      "description": "agentlefs://public/… for an agent: read it as a resource, or pass it as within",
+      "type": "string"
+    },
+    "withheld": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "origin",
+    "name",
+    "repo",
+    "path",
+    "kind",
+    "description",
+    "licence",
+    "redistributable",
+    "capabilities",
+    "stars",
+    "bytes",
+    "knownPublisher",
+    "changedAt",
+    "citation",
+    "link",
+    "sourceLink",
+    "uri",
+    "commit",
+    "collectedAt",
+    "body",
+    "offset",
+    "nextOffset",
+    "maxBytes",
+    "bodyTruncated",
+    "withheld",
+    "citedCommit",
+    "citedLink",
+    "citedCommitCollected"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / hits / items / properties / matched

Added value: +{
+  "description": "Why this hit matched, strongest evidence first: its file name, title or an alias (titles), a label on it (labels), a literal phrase in its body (text), or a semantically near chunk (meaning). `labels` is evidence you can read but not yet ask for: `how` takes the other three. Document hits carry it; hits from within one document, one thread, or knowledge do not, because there the single strategy is already named in `mode` and `score` is the rank key.",
+  "items": {
+    "enum": [
+      "titles",
+      "labels",
+      "text",
+      "meaning"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / licensedOnly
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / public

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "bytes": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "the file's size in bytes as GitHub reported it, so a read can be budgeted before it is made"
+      },
+      "capabilities": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "changedAt": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "when the repository's agent context last changed: one history lookup per repository (its skills folder, or its first file), so a sibling file moves it too. Freshness, not a per-file clock"
+      },
+      "citation": {
+        "description": "github:owner/repo@<commit>:path, the form to write down: within reopens it and says whether the repository has moved on",
+        "type": "string"
+      },
+      "description": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "kind": {
+        "enum": [
+          "skill",
+          "agents_md",
+          "claude_md",
+          "cursor_rule",
+          "copilot_instructions",
+          "llms_txt"
+        ],
+        "type": "string"
+      },
+      "knownPublisher": {
+        "description": "the publisher is an organization we recognise (model labs, agent and editor makers): provenance, not an endorsement",
+        "type": "boolean"
+      },
+      "licence": {
+        "type": "string"
+      },
+      "link": {
+        "description": "where a person reads it: this server's console catalog page, or GitHub when it has no console. within reopens this server's links; another console's may not",
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "origin": {
+        "const": "public",
+        "type": "string"
+      },
+      "path": {
+        "type": "string"
+      },
+      "redistributable": {
+        "description": "whether the licence lets agentleFS serve the text: false means body is null, withheld says why, and sourceLink is where to read it",
+        "type": "boolean"
+      },
+      "repo": {
+        "type": "string"
+      },
+      "sourceLink": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "the file on GitHub at the commit collected, readable whatever its licence; null when no commit is known. within reopens it and says whether the repository has moved on"
+      },
+      "stars": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "uri": {
+        "description": "agentlefs://public/… for an agent: read it as a resource, or pass it as within",
+        "type": "string"
+      }
+    },
+    "required": [
+      "origin",
+      "name",
+      "repo",
+      "path",
+      "kind",
+      "description",
+      "licence",
+      "redistributable",
+      "capabilities",
+      "stars",
+      "bytes",
+      "knownPublisher",
+      "changedAt",
+      "citation",
+      "link",
+      "sourceLink",
+      "uri"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed1 schema field changedSep 29, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```

Changed1 schema field changedSep 29, 2026

changedInput schema / properties / within / description

Previous value: -"a document path or node id"New value: +"a document path or node id. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too."

Changed5 schema fields changedSep 26, 2026

addedOutput schema / properties / hits / items / properties / kind / enum

Added value: +[
+  "document",
+  "span",
+  "message",
+  "knowledge"
+]

addedOutput schema / properties / hits / items / properties / knowledge

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "decay": {
+      "type": "number"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "score": {
+      "type": "number"
+    },
+    "title": {
+      "type": "string"
+    },
+    "validation": {
+      "type": "string"
+    },
+    "version": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "kind",
+    "title",
+    "version",
+    "validation",
+    "score",
+    "decay"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / hits / items / properties / knowledgeId

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

changedOutput schema / properties / hits / items / properties / trust / enum

Previous value: -[
-  "verified_truth",
-  "stated_truth",
-  "mirror",
-  "text"
-]New value: +[
+  "verified_truth",
+  "stated_truth",
+  "mirror",
+  "text",
+  "validated_knowledge",
+  "unvalidated_knowledge",
+  "refuted_knowledge"
+]

changedOutput schema / properties / hits / items / required

Previous value: -[
-  "kind",
-  "location",
-  "nodeId",
-  "spanId",
-  "messageId",
-  "excerpt",
-  "line",
-  "score",
-  "citation",
-  "freshness",
-  "trust",
-  "truths"
-]New value: +[
+  "kind",
+  "location",
+  "nodeId",
+  "spanId",
+  "messageId",
+  "knowledgeId",
+  "excerpt",
+  "line",
+  "score",
+  "citation",
+  "freshness",
+  "trust",
+  "truths"
+]

Changed1 schema field changedSep 25, 2026

changedInput schema / properties / token / description

Previous value: -"Bearer token. Usually omitted — supplied by the transport."New value: +"Bearer token identifying the principal. Usually omitted — supplied by the transport. Over stdio it selects the principal (else the server's AGENTLEFS_TOKEN env). Over HTTP the Authorization header decides and passing this argument is REFUSED, not ignored: it cannot override who you are acting as."

AddedSep 23, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Beyond the annotations, the description discloses many behavioral traits: freshness, trust signals, citation formats, public-corpus licensing rules, default and maximum limits, pagination with offsets and max_bytes, and that drafts and unreadable content are never returned. These details substantially help an agent understand what the tool returns and what it does not return.

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

Conciseness2/5

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

The description is extremely dense and delivered as one long paragraph, making it hard to scan. While the core purpose is front-loaded, many clauses and parenthetical details obscure the main usage path.

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?

Given the tool's complexity, the rich annotations, the output schema, and the high schema coverage, the description is more than complete. It covers public versus private search, knowledge hits, pagination, licensing, and trust signals, so an agent has enough context to invoke it correctly.

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

Parameters5/5

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

Although schema coverage is already high at 85%, the description adds meaningful semantics for key parameters: the `how` strategies, `scope` public vs. folder behavior, `within` opening a public file, `offset` and `max_bytes` pagination, `licensed_only`, and `follow`. This goes well beyond the schema's field-level descriptions.

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 and resource: 'Search what you can read' and then explains that hits are citable and include documents, spans, messages, public GitHub files, and knowledge. It clearly distinguishes the public corpus from the organization's readable corpus, but it does not explicitly name sibling tools like browse or read as alternatives.

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

Usage Guidelines4/5

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

The description gives extensive usage context: how to search by scope, within, thread, source, and how to open a public file with scope "public" and within. It explains public-corpus behavior and pagination, but it does not explicitly state when to prefer this tool over sibling tools such as browse or read.

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?