Skip to main content
Glama
github-fetcher

github-fetcher

by KurvCygnus

GitHub file batch

github_files
Read-onlyIdempotent

Reads up to 10 GitHub repository files per call, returning content plus per-path success or error details so one missing file doesn't fail the batch.

Instructions

Batch file read: fetches up to 10 paths per call from one repository concurrently, one core call per uncached path, zero for cache hits, and reports per-item success and failure so one missing or malformed path never rejects the call. Returns {results[{path, ok, data{path, sha, size, encoding, content, binary, truncated}} or {path, ok, error{code, message}}], elapsed_ms, meta}.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "repo": "<repo>",
      "paths": "<paths>"
    },
    "name": "github_files"
  }
}

Input Schema

NameRequiredDescriptionDefault
refNoBranch, tag, or commit; defaults to the repository default branch
repoYesRepository in owner/name form
freshNoBypass the local cache
pathsYesFile paths inside the repository; up to 10 per call

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.5.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety bar is low; the description still adds real behavior beyond them — concurrency, the core-call cost model ("one core call per uncached path, zero for cache hits"), and per-item failure isolation. It does not explain whether a failed item is retried or whether rate-limit exhaustion affects only some items.

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?

Two sentences, both front-loaded and free of filler — the batch scope and the cost model come first. The second sentence is a dense inline type notation for the return shape, which is information-rich but harder to scan than prose.

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?

With no output schema, the description correctly carries the return shape, including both the success and error item variants, which is the information an agent would otherwise lack. It leaves auth/private-repo behavior and partial rate-limit effects unstated, though those are minor for a read-only batch fetch.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents repo, ref, paths and fresh including the 10-item cap. The description reinforces the batch limit and the cache/core-call behavior that gives `fresh` meaning, but adds no format or syntax detail beyond the schema.

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

Purpose5/5

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

The description opens with a specific verb+resource pair ("Batch file read") and immediately defines the scope: "fetches up to 10 paths per call from one repository concurrently." The word "Batch" plus the per-call limit distinguishes it from the single-file sibling github_file without needing to name it.

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 rather than stated: an agent can infer this is the right tool when it has multiple paths in one repo. But there is no explicit "use github_file for a single path" routing, and no guidance on when the batch overhead or cache accounting makes it a poor fit.

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