Skip to main content
Glama
ozgurcd

gograph

by ozgurcd
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

gograph_plan

Read-onlyIdempotent

Generate a structured pre-edit plan for a Go symbol: identify symbols to read first, covering tests, routes, env vars, and API/SQL risks before refactoring.

Instructions

Generate a structured pre-edit plan for a target symbol: which symbols to read first, which tests cover them, which routes and env vars they touch, and whether the change is public-API or SQL-touching. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. Set with_context=true to inline full source+callers+callees for each symbol to inspect — eliminates follow-up gograph_context calls. WHEN TO USE: Before multi-file refactoring or architectural changes to understand scope upfront. NOT TO USE: For trivial single-line fixes; for post-edit verification (use gograph_review instead). RETURNS: JSON with inspect_first[], tests[], routes[], env[], and a risk object (public_api, touches_sql, etc.); with with_context=true, also includes inspect_contexts[] with full per-symbol bundles. Uncommitted modes compare declarations against HEAD, including selected untracked Go files. Current-graph consumers refuse incomplete comparisons, deleted declarations requiring historical caller evidence, and missing/ambiguous graph identities. Inspect changes --git REF for the declaration census; rebuild before traversing newly added symbols.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
symbolNoThe name of the symbol you intend to modify (supports short name 'ValidateToken', dot-notation 'graph.Graph', or fully-qualified ID)
uncommittedNoSet to true to generate a global plan for all currently uncommitted changes across the repository
with_contextNoIf set to true, bundles full context, source code, callers, callees, and architectural roles for each symbol to be inspected

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.5.3
  2. Removedv1.5.3
  3. Changed1 schema field changed
    • changedInput schema / properties / symbol / description
      Previous value: -"The name of the symbol you intend to modify (e.g., 'ValidateToken')"New value: +"The name of the symbol you intend to modify (supports short name 'ValidateToken', dot-notation 'graph.Graph', or fully-qualified ID)"
  4. Changed3 schema fields changedv1.4.66
    • changedInput schema / properties / symbol / description
      Previous value: -"The symbol to plan changes for"New value: +"The name of the symbol you intend to modify (e.g., 'ValidateToken')"
    • changedInput schema / properties / uncommitted / description
      Previous value: -"Set to true to plan all uncommitted changes"New value: +"Set to true to generate a global plan for all currently uncommitted changes across the repository"
    • changedInput schema / properties / with_context / description
      Previous value: -"If true, include full context (source, callers, callees, role) for each inspect_first symbol"New value: +"If set to true, bundles full context, source code, callers, callees, and architectural roles for each symbol to be inspected"
  5. First observedv1.0.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare read-only/idempotent/non-destructive, yet the description adds real behavioral context: the server checks freshness before the call, retries CHA/SSA for precise modes, uncommitted modes compare declarations against HEAD, and consumers refuse incomplete comparisons or missing/ambiguous graph identities. This is disclosure well beyond the structured hints.

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?

Front-loaded with the core purpose and well-organized into WHEN/NOT/RETURNS blocks. It is dense and long, and 'Read-only; no side effects' partially restates the readOnlyHint annotation, but nearly every sentence carries actionable information.

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 compensates by fully describing the JSON return shape (inspect_first[], tests[], routes[], env[], risk object, inspect_contexts[] with with_context). Combined with the freshness and refusal semantics, an agent has everything needed to call it correctly.

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, but the description adds genuine meaning: with_context=true inlines full source/callers/callees and eliminates follow-up gograph_context calls, and uncommitted=true produces a global plan for all uncommitted changes. Only the symbol parameter's short/dot/fully-qualified forms are left to 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?

States a specific verb ('Generate') and resource ('structured pre-edit plan for a target symbol') and enumerates the plan's contents (symbols to read first, tests, routes, env vars, public-API/SQL risk). It distinguishes itself from siblings by naming gograph_review and gograph_context explicitly.

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 WHEN TO USE / NOT TO USE block is explicit: use before multi-file refactoring or architectural changes; do not use for trivial single-line fixes or post-edit verification, and it routes the latter to gograph_review. The with_context guidance further tells the agent how to avoid follow-up gograph_context calls.

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

Deploy Server

Other Tools