Skip to main content
Glama

gograph_explore

Read-onlyIdempotent

Explore a Go symbol or lexical term in one bounded call, returning ranked matches, source context, callers/callees, tests, and impact to navigate large codebases without raw file reads.

Instructions

Explore a lexical term or Go symbol in one bounded call. Standard mode combines ranked matches with selected-symbol source, direct callers/callees, tests, and exact impact. compact=true returns discovery, selected-node metadata, role, complete counts, and explicit omitted_sections while suppressing token-heavy bodies (default limit 5). deep=true retains standard evidence and adds bounded depth-3 exact identity callers/callees, package context, and explanation (default limit 25). compact and deep are mutually exclusive; an explicit limit overrides their defaults. Possible dispatch is excluded from bundled identity impact and deep traversals. Question-like text is lexical, not model-interpreted. Focused tools remain authoritative for complete output. RETURNS: shared gograph.explore.v1 with mode, selection_basis, ambiguity, totals, truncation, and omission metadata.

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": {
      "query": "<query>"
    },
    "name": "gograph_explore"
  }
}

Input Schema

NameRequiredDescriptionDefault
deepNoExpanded response: standard evidence plus bounded depth-3 exact callers/callees, package context, and explanation; mutually exclusive with compact
rootNoAbsolute path of your checkout or worktree (alias cwd).
exactNoRequire exact resolution for selected-symbol context; broad lexical matches remain visible
limitNoMaximum rows returned per section, clamped to 1-100; defaults to 5 compact, 10 standard, or 25 deep
queryYesA symbol, fully-qualified ID, lexical feature term, or short question-like phrase to explore
compactNoLow-token response: matches, selected node/role, complete counts, and explicit omissions; mutually exclusive with deep
intentionNoRationale; required with an active session.
session_idNoSession from session_create; omit for none.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.7.21
    • changedInput schema / properties / intention / description
      Previous value: -"Technical rationale, required for analytical calls selecting an active session."New value: +"Rationale; required with an active session."
    • changedInput schema / properties / root / description
      Previous value: -"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."New value: +"Absolute path of your checkout or worktree (alias cwd)."
    • changedInput schema / properties / session_id / description
      Previous value: -"Caller selector returned by session_create. Omission means an independent caller; never inherits server environment or another caller's session."New value: +"Session from session_create; omit for none."
  2. 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"
      +}
  3. Addedv1.7.5

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so safety is covered. The description adds real behavioral context beyond them: results are bounded, limits are clamped 1-100 with per-mode defaults, compact suppresses token-heavy bodies while emitting explicit omitted_sections, and possible dispatch is deliberately excluded from bundled identity impact and deep traversals — a meaningful scoping caveat an agent could otherwise misread as a completeness gap.

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-loads the one-line purpose, then mode semantics, then a clearly marked RETURNS block; no filler sentences. It is dense to the point of being hard to parse in a single pass, and the compact/deep mutual exclusion is stated in the description as well as twice in the schema, a minor redundancy.

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 no output schema, the description carries the return burden and does so by naming the shared gograph.explore.v1 envelope and its fields (mode, selection_basis, ambiguity, totals, truncation, omission metadata). Coverage of modes, limits, exclusions and session/intention gating is adequate for an 8-parameter tool; only the interaction between exact and the deep traversal is left implicit.

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%, so every parameter is already documented, which sets the baseline at 3. The description adds some cross-parameter meaning the schema states only partially — that compact and deep are mutually exclusive and that an explicit limit overrides their defaults — but much of it restates defaults already present in the limit and mode parameter descriptions.

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 object ('Explore a lexical term or Go symbol in one bounded call') and immediately scopes it as a bundle rather than a single query. It also carves out the boundary against siblings: 'Focused tools remain authoritative for complete output,' so an agent knows this is the aggregated view, distinct from gograph_callers/gograph_callees/gograph_impact-style tools.

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?

Gives concrete mode-selection rules: compact for low-token discovery, deep for depth-3 evidence and explanation, they are mutually exclusive, and an explicit limit overrides mode defaults. It also sets expectations that question-like text is treated lexically rather than model-interpreted, and that focused tools are authoritative for complete output. It stops short of naming which focused tool to drop to for a given need, leaving that inference to the agent.

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