Skip to main content
Glama

write_repo_map

Creates and updates a shared GitHub repository map for developer and reviewer briefs, covering layout, entry points, build/test/lint commands, conventions, and known traps.

Instructions

Write the map of a GitHub repo (owner/name) that the builder and reviewer briefs serve: layout, entry points, how to install, build, test and lint, conventions, the files tickets touch most, known traps. One map per repo, shared by every project on it, at most 8,000 characters (about 2,000 tokens). body replaces the whole map, so start from the one in your brief and pass its version as base (leave it empty when the repo has no map). If someone wrote the map since, nothing is written and the answer is the map now: fold your change into it and write again. note says what changed and becomes a dated line in its history. Write it when the brief says the repo has none; update it when a merged PR changes the layout or the build, test or lint commands.

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>",
      "body": "<body>",
      "note": "<note>"
    },
    "name": "write_repo_map"
  }
}

Input Schema

NameRequiredDescriptionDefault
baseNo
bodyYes
noteYes
repoYes
projectNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.57.0

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the 8,000-character (~2,000 token) cap, that one map is shared across every project on the repo, that body is a full replacement rather than a patch, and that a stale base causes nothing to be written and returns the current map. That last point is the critical conflict-handling behavior an agent must know before calling.

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?

It is front-loaded with the resource and its contents, then moves to mechanics and finally the when-to-use trigger, which is good ordering. The opening enumeration of map contents is long, though defensible since it defines what the artifact must contain, and the whole thing is one dense block rather than separated clauses.

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?

For a mutation tool with five parameters, a concurrency mechanism, and an output schema, this is complete: semantics, size limit, scope, conflict behavior, and invocation triggers are all covered, and return values need not be explained because an output schema exists. Only the project parameter and any permission requirements are left unstated.

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 description coverage is 0%, so the description must define the parameters, and it explains four of five: repo as owner/name, body as whole-map replacement, base as the version to thread (empty when no map exists), and note as the dated history line. The fifth parameter, project, is never mentioned, leaving its role ambiguous.

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?

States a specific verb and resource ('Write the map of a GitHub repo (owner/name)') and enumerates exactly what the artifact contains: layout, entry points, install/build/test/lint, conventions, hot files, traps. That scope makes it clearly distinct from the sibling write_doc / write_ticket tools, which write other artifact types.

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

Usage Guidelines5/5

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

The final sentence gives explicit triggering conditions: write when the brief says the repo has none, update when a merged PR changes layout or the build/test/lint commands. It also specifies the prerequisite of starting from the map in the brief and threading its version as base, so the agent knows the correct entry path rather than guessing.

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