Skip to main content
Glama

Synapse

Plan a code change

plan_change
Read-onlyIdempotent

Call ONCE at the start of a coding task. A complete brief: files and line ranges to change, the key functions in full with their callers, the existing pattern to follow, decisions not to break and the only tests to run. From the code graph, not guesses.

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": {
      "task": "<task>",
      "repository": "<repository>"
    },
    "name": "plan_change"
  }
}

Input Schema

NameRequiredDescriptionDefault
taskYesWhat you are about to do, in plain words (e.g. "add rate limiting to the refresh token endpoint").
pathsNoFiles or folders you already know are involved.
termsNoWords this codebase would use for the task, e.g. ["throttle"] for "rate limiting", ["revoke", "grant"] for "disconnect apps".
detailNomap: a short edit map (files, line ranges, pattern, unit tests); full: also the key functions in full. Default: map for code changes, full for plans and questions.
targetsNoReal names in this repo the task is about (functions, classes, constants, files), from the vocabulary in the server instructions, e.g. ["AuthController.refresh"].
repositoryYesPublic GitHub repository as "owner/name" (e.g. "pallets/flask") or its github.com URL.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4/5.0
Behavior4/5

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

The annotations already declare that the tool is a safe, idempotent read (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false). The description adds real value beyond that: it discloses that results derive from the code graph rather than guesses, and it lists the exact sections of the brief. It says nothing about cost, latency, or failure when the graph lacks coverage, so it isn't fully transparent.

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

Conciseness5/5

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

Two sentences, no filler: the first front-loads the timing and one-call constraint, the second enumerates the payload. Every phrase, including "From the code graph, not guesses," carries information an agent would otherwise lack.

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 six parameters, no output schema, and a fairly complex planning function, the description compensates by describing what the brief contains, which is exactly what the input schema cannot convey. Minor gaps remain: nothing about behavior when the repository or code graph cannot be resolved, and no explicit prerequisite that the repository must be public.

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 description coverage is 100%, with every one of the six parameters documented in the schema, including examples for task, terms, and targets. The description only lightly touches on semantics by noting that "the key functions in full" are included, which loosely maps to detail=full, but the schema already explains the map/full distinction. This is the baseline of 3 for a schema that does the heavy lifting.

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 states a specific action (produce a complete planning brief at the start of a coding task) and enumerates exactly what the brief contains: files and line ranges, key functions with callers, the pattern to follow, decisions not to break, and which tests to run. It is clear what the tool returns, but it never names a sibling, so an agent must infer for itself how this differs from tests_for, blast_radius, or why, which cover similar ground.

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?

"Call ONCE at the start of a coding task" gives explicit timing and even a frequency constraint, which is stronger than most definitions offer. It does not say when to skip this tool or which sibling to reach for instead (for example, blast_radius for impact analysis alone), so there is no routing guidance.

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