Skip to main content
Glama
github-fetcher

github-fetcher

by KurvCygnus

GitHub pin ref

github_pin_ref
Read-onlyIdempotent

Pin a repo to a specific commit for the session so file, tree, and commit reads without an explicit ref anchor to that sha, keeping line-number references consistent.

Instructions

Pin a repository to a commit for the session: file, tree, and commit reads without an explicit ref anchor to this sha, keeping line-number references internally consistent across a session. The pin lives in server memory and is lost on restart. Costs 1 core call (2 for a default-branch pin; 0 when unpinning or passing a full sha). Returns {repo, ref, sha, pinned}; after an unpin the answer carries only repo and pinned (false).

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>"
    },
    "name": "github_pin_ref"
  }
}

Input Schema

NameRequiredDescriptionDefault
refNoBranch, tag, or commit to pin; resolves to a full commit sha. Omit to unpin when unpin is true
repoYesRepository in owner/name form
unpinNoRemove this repository's pin

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?

Beyond the annotations, the description discloses that the pin lives in server memory and is lost on restart, quantifies cost (1 core call, 2 for a default-branch pin, 0 for unpin or a full sha), and gives the exact return shape including the reduced answer after unpin. That is substantial added context. It could go further on concurrency or what happens if two sessions pin the same repo, but the annotations already cover safety and idempotency.

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?

The description is front-loaded with the core action and effect, then layers cost and return-value detail with no filler sentences. The parenthetical cost clause and the mix of state, cost, and return information in one block make it slightly dense on first read, but nothing is wasted.

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?

With no output schema, the description supplies the return object inline, covers persistence lifetime, cost accounting, and the unpin end-state. For a three-parameter session-state tool, an agent has everything needed to call it and interpret the result.

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 the baseline is 3, and the description earns an increment by tying parameter choices to observable behavior: a full sha costs 0 calls while a branch or default-branch pin costs 2, and unpinning returns only repo and pinned. The ref-to-sha resolution rule is echoed from the schema rather than added, so it is not a full 5.

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 leads with a specific verb and resource ('Pin a repository to a commit for the session') and immediately explains the downstream effect on file, tree, and commit reads, so the tool's role is unmistakable. It stops short of naming a sibling tool it competes with, which is the only thing keeping it from a 5.

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?

Use is implied by the stated rationale 'keeping line-number references internally consistent across a session', which tells an agent this is for multi-read workflows. However, there is no explicit 'use this when / avoid this when' and no guidance on the alternative of passing an explicit ref on each individual read instead of pinning.

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