Skip to main content
Glama

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

TableJSON Schema
NameRequiredDescriptionDefault
howNo
limitNohow many hits (at most 20 with scope "public")
queryNowhat you want to know (not needed to open a public file with scope "public" and within)
scopeNo"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
followNo
offsetNoscope "public" with within only: where in the file to start, in bytes as read action=document takes it (a part gives nextOffset)
sourceNoa sync source id, or a location inside the mirror
threadNoa message id in the thread
withinNoa 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.
max_bytesNoscope "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_onlyNoscope "public" only: just the files whose licence lets their text be served (default false: every match, unlicensed ones described with a link)

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
fileNo
hitsYes
modeYes
queryYes
memoryNothe memory files (CLAUDE.md, AGENTS.md) of scope and of the hits' folders and above, only ones you can read
publicNo
skillsNothe 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
degradedYes
truncatedYes
licensedOnlyNo
spansPendingNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • 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"
      +}
  2. Changed2 schema fields changed
    • 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"
      +}
  3. Changed1 schema field changed
    • 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"
  4. Changed2 schema fields changed
    • 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"
      -}
  5. Changed11 schema fields changed
    • 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"
      +}
  6. Changed1 schema field changed
    • addedInput schema / additionalProperties
      Added value: +false
  7. Changed1 schema field changed
    • 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."
  8. Changed5 schema fields changed
    • 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"
      +]
  9. Changed1 schema field changed
    • 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."
  10. Added

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds real behavioral context on top: drafts are never returned, nothing unreadable is returned or counted, the public corpus is a separate limited set (5 by default, 20 max), and file reads are chunked at 50,000 bytes with offset paging. The content is valuable, though the dense run-on phrasing makes it harder to absorb than it should be.

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 a single enormous paragraph of chained clauses with no headings or paragraph breaks, mixing return-field semantics, public-corpus rules, and file-paging mechanics. Much of it restates what the output schema and parameter descriptions already carry, and the front-loaded summary is quickly buried.

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?

For an 11-parameter, zero-required tool with an output schema and a dual public/private corpus, the description covers the tricky cases an agent would otherwise get wrong (public needs 2+ characters, licensed_only filters servable text, knowledge hits are phrase-matched, your own folder named public is scope /public). Return-value explanation is partly redundant given the output schema, but nothing critical 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 already 82%, so the baseline is 3, and the description genuinely adds meaning beyond it: it explains what each `how` strategy matches on, the semantics of `matched` versus `score`, how `within` accepts a citation, URI, GitHub link, or console link, and that `offset`/`max_bytes` are byte-based and only apply to public single-file reads.

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 opening clause states a clear verb and resource ('Search what you can read, and get back hits you can cite') and the description goes on to enumerate what a hit contains, so an agent knows this is a corpus search returning citable results. It never names or contrasts with siblings like browse or read, however, and the sprawling middle makes the core purpose hard to extract on a first read.

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?

It gives substantial conditional guidance on how to narrow a query (scope, within, thread, source, follow) and what each `how` strategy does, which implies when to reach for each option. But it never states when to use search versus read/browse, even though `within` on a public file returns a single file's text – exactly the overlap a routing statement should resolve.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources