Skip to main content
Glama
Sign In
gograph

gograph

by ozgurcd
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

gograph_stale

Read-onlyIdempotent

Check whether the persisted Go graph index is stale against current files, build context, or source digests. Read-only, no refresh; helps decide if snapshot analysis or enrichment needs rebuilding.

Instructions

Check whether the trusted persisted graph index loaded from a regular, repository-confined .gograph/graph.json differs from the current selected-file inventory, effective Go build context, or selected source content digests. Modification times are returned only as diagnostics; legacy indexes without digests temporarily use the former mtime fallback until rebuilt. This tool intentionally does not refresh first; when the artifact is missing, unreadable, unsafe, or uses an unsupported source policy it compares against the startup auto-build fallback. Read-only; no side effects. WHEN TO USE: To decide whether CLI snapshot analysis or precise enrichment needs rebuilding. NOT TO USE: For module dependency freshness; for changed symbols (use gograph_changes). RETURNS: is_stale, graph_age, newest source metadata, changed_files, and build_context_changed.

Input Schema

NameRequiredDescriptionDefault
rootNoAbsolute path of the checkout you are working in (your cwd or git worktree). Must be this server's repository or one of its git worktrees; the answer then comes from that checkout's own graph. A path elsewhere is refused. Alias: cwd. Omit only when the configured checkout is the one you mean.
intentionNoTechnical rationale, required for analytical calls selecting an active session.
session_idNoCaller selector returned by session_create. Omission means an independent caller; never inherits server environment or another caller's session.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.7.18
    • addedInput schema / properties / intention
      Added value: +{
+  "description": "Technical rationale, required for analytical calls selecting an active session.",
+  "type": "string"
+}
    • addedInput schema / properties / root
      Added value: +{
+  "description": "Absolute path of the checkout you are working in (your cwd or git worktree). Must be this server's repository or one of its git worktrees; the answer then comes from that checkout's own graph. A path elsewhere is refused. Alias: cwd. Omit only when the configured checkout is the one you mean.",
+  "type": "string"
+}
    • addedInput schema / properties / session_id
      Added value: +{
+  "description": "Caller selector returned by session_create. Omission means an independent caller; never inherits server environment or another caller's session.",
+  "type": "string"
+}
  2. First observedv1.0.0

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already cover readOnly/idempotent/non-destructive, yet the description adds real behavior: it deliberately does not refresh first, falls back to the startup auto-build result when the artifact is missing/unreadable/unsafe, and uses an mtime fallback for legacy indexes. The 'Read-only; no side effects' clause partly duplicates the annotations, and return-shape behavior such as graph_age semantics is only lightly sketched, keeping this just below a 5.

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 comparison, then qualifications, then WHEN/NOT/RETURNS blocks in a predictable order. The opening sentence is dense and multi-clause, but no sentence is filler aside from the redundant read-only restatement.

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?

No output schema exists, so the RETURNS list (is_stale, graph_age, newest source metadata, changed_files, build_context_changed) fills that gap, and the fallback/degraded-mode discussion covers the edge cases an agent would otherwise misread as errors. Nothing needed to invoke or interpret the result is missing.

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% with three self-documenting parameters (root, intention, session_id), so the baseline is 3. The description adds no parameter-level meaning beyond the schema, though its mention of 'repository-confined' and effective build context loosely reinforces what root selects.

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: comparing the persisted .gograph/graph.json index against the current file inventory, build context, and source digests. It scopes exactly what is compared and what 'stale' means, so an agent can separate it from gograph_changes or gograph_check without opening the schema.

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?

Explicit WHEN TO USE (deciding whether snapshot analysis or enrichment needs rebuilding) and NOT TO USE (module dependency freshness; changed symbols -> gograph_changes), naming the alternative sibling directly. The condition selecting this tool versus that one is stated rather than implied.

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