Skip to main content
Glama
token-context-mcp

token-context-mcp

Symbol context

get_symbol_context
Read-onlyIdempotent

Fetch bounded body and 0–3-hop context edges for a known symbol ID; page long bodies by line offset and cap tokens to avoid oversized context.

Instructions

Fetch bounded body and 0-3 hop edges for a known symbol_id (use body_offset_line to page long bodies; omits body if over max_tokens). If symbol_id is unknown, call inspect_symbol.

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_id": "<repo_id>",
      "symbol_id": "<symbol_id>"
    },
    "name": "get_symbol_context"
  }
}

Input Schema

NameRequiredDescriptionDefault
depthNoNeighborhood traversal depth around the target symbol (0 for target only, up to 3 hops).
profileNoNamed budget profile preset ('locate', 'orient', 'impact', 'read'); defaults to 'read'.
repo_idYesRegistered repository ID from list_repositories (never a filesystem path).
symbol_idYesCanonical or compact 8-char symbol_id from get_repo_map, find_symbols, or search_source.
max_tokensNoToken cap for packet and neighbors (32 to max_result_tokens; defaults to 'read' profile budget).
include_bodyNoInclude target symbol body; defaults to True in 'read' profile. If body exceeds budget, emits root_body_hint.
body_offset_lineNo1-based line offset inside the symbol body to read oversized functions in pages via body_window.next_offset.
include_omitted_idsNoInclude up to 10 truncated neighbor IDs in omitted_symbol_ids when neighbors exceed max_tokens.

Output Schema

NameRequiredDescriptionDefault
dataNoTarget symbol packet (with optional windowed body) and neighborhood edges.
errorNoPresent when the tool call fails (either a structured {code, message, details} object or a diagnostic string).
budgetNoToken budget accounting for this response.
repo_idNoRegistered repository identifier.
evidenceNoSource-verified file line spans and SHA-256 hashes backing the response.
warningsNoFreshness, ambiguity, redaction, or security warnings.
freshnessNoIndex freshness state ('fresh', 'pending', 'stale', or 'unknown').
truncatedNoTrue if items were omitted due to budget or node limits.
ledger_revNoCurrent evidence ledger revision for repo_id.
completenessNoCoverage/resolution completeness indicator.
index_run_idNoIdentifier of the active index snapshot run.
edge_precisionNoResolved vs. ambiguous edge ratio summary.
schema_versionNoEnvelope schema version ('1.0').
untrusted_repository_contentNoTrue when payload embeds raw repository text.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv0.3.8
    • changedInput schema / properties / body_offset_line / description
      Previous value: -"1-based relative line offset within the symbol body to page through large functions."New value: +"1-based line offset inside the symbol body to read oversized functions in pages via body_window.next_offset."
    • changedInput schema / properties / depth / description
      Previous value: -"Caller/callee neighborhood traversal depth around the symbol (0 to 3)."New value: +"Neighborhood traversal depth around the target symbol (0 for target only, up to 3 hops)."
    • changedInput schema / properties / include_body / description
      Previous value: -"Include the source code body of the target symbol (defaults to True for 'read' profile)."New value: +"Include target symbol body; defaults to True in 'read' profile. If body exceeds budget, emits root_body_hint."
    • changedInput schema / properties / include_omitted_ids / description
      Previous value: -"Include symbol IDs omitted when neighbors exceed the token budget."New value: +"Include up to 10 truncated neighbor IDs in omitted_symbol_ids when neighbors exceed max_tokens."
    • changedInput schema / properties / max_tokens / description
      Previous value: -"Maximum token budget for the context packet (32 to max_result_tokens)."New value: +"Token cap for packet and neighbors (32 to max_result_tokens; defaults to 'read' profile budget)."
    • changedInput schema / properties / profile / description
      Previous value: -"Named budget profile ('locate', 'orient', 'impact', 'read'); defaults to 'read'."New value: +"Named budget profile preset ('locate', 'orient', 'impact', 'read'); defaults to 'read'."
    • changedInput schema / properties / symbol_id / description
      Previous value: -"Exact symbol_id obtained from find_symbols, get_repo_map, or search_source."New value: +"Canonical or compact 8-char symbol_id from get_repo_map, find_symbols, or search_source."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "budget": {
      +      "additionalProperties": true,
      +      "description": "Token budget accounting for this response.",
      +      "properties": {
      +        "envelope_reserve": {
      +          "description": "Wire-framing token reserve when budget >= 512.",
      +          "type": "integer"
      +        },
      +        "estimated_tokens": {
      +          "description": "Estimated serialized response tokens.",
      +          "type": "integer"
      +        },
      +        "requested_tokens": {
      +          "description": "Requested or profile-default token budget.",
      +          "type": "integer"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "completeness": {
      +      "additionalProperties": true,
      +      "description": "Coverage/resolution completeness indicator.",
      +      "properties": {
      +        "basis": {
      +          "description": "How completeness was computed.",
      +          "type": "string"
      +        },
      +        "value": {
      +          "description": "Completeness ratio in [0.0, 1.0], or null if N/A.",
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "data": {
      +      "additionalProperties": true,
      +      "description": "Target symbol packet (with optional windowed body) and neighborhood edges.",
      +      "properties": {
      +        "edges": {
      +          "description": "Observed caller/callee edges within depth.",
      +          "items": {
      +            "additionalProperties": true,
      +            "description": "Observed AST/lexical call or reference edge between symbols.",
      +            "properties": {
      +              "backend": {
      +                "description": "Extractor backend producing this edge.",
      +                "type": "string"
      +              },
      +              "confidence": {
      +                "description": "Edge resolution confidence in [0.0, 1.0].",
      +                "type": [
      +                  "number",
      +                  "null"
      +                ]
      +              },
      +              "edge_kind": {
      +                "description": "Relationship kind (e.g. calls, instantiates, inherits).",
      +                "type": "string"
      +              },
      +              "source_line": {
      +                "description": "1-based line number of the edge.",
      +                "type": "integer"
      +              },
      +              "source_path": {
      +                "description": "File path where the edge occurs.",
      +                "type": "string"
      +              },
      +              "source_symbol_id": {
      +                "description": "Caller or source symbol ID.",
      +                "type": "string"
      +              },
      +              "status": {
      +                "description": "Resolution status ('resolved', 'ambiguous', or 'unresolved').",
      +                "type": "string"
      +              },
      +              "target_name": {
      +                "description": "Target symbol name at call site.",
      +                "type": "string"
      +              },
      +              "target_symbol_id": {
      +                "description": "Resolved target symbol ID, or null if external/unresolved.",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              }
      +            },
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "estimator_version": {
      +          "description": "Token estimator version.",
      +          "type": "string"
      +        },
      +        "external_stubs": {
      +          "additionalProperties": true,
      +          "description": "External library stub metadata for cross-package calls.",
      +          "type": "object"
      +        },
      +        "omitted_count": {
      +          "description": "Count of neighbor symbols omitted due to budget.",
      +          "type": "integer"
      +        },
      +        "omitted_edge_count": {
      +          "description": "Count of edges omitted due to budget.",
      +          "type": "integer"
      +        },
      +        "omitted_symbol_ids": {
      +          "description": "Up to 10 omitted neighbor symbol IDs when include_omitted_ids=True.",
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "root_body_hint": {
      +          "description": "Paging instruction when body exceeds max_tokens.",
      +          "type": "string"
      +        },
      +        "root_body_lines": {
      +          "description": "Line count of target symbol when body was omitted.",
      +          "type": "integer"
      +        },
      +        "root_body_tokens_needed": {
      +          "description": "Estimated tokens needed if body was omitted due to budget.",
      +          "type": "integer"
      +        },
      +        "root_symbol_id": {
      +          "description": "Canonical symbol_id of the target symbol.",
      +          "type": "string"
      +        },
      +        "symbols": {
      +          "description": "Root and neighbor symbol packets.",
      +          "items": {
      +            "additionalProperties": true,
      +            "properties": {
      +              "body_included": {
      +                "description": "True if full/windowed body is included.",
      +                "type": "boolean"
      +              },
      +              "body_window": {
      +                "additionalProperties": true,
      +                "description": "Paging window metadata when body_offset_line is used.",
      +                "properties": {
      +                  "end_line": {
      +                    "description": "1-based last line in this window.",
      +                    "type": "integer"
      +                  },
      +                  "next_offset": {
      +                    "description": "Next body_offset_line to read, or null at EOF.",
      +                    "type": [
      +                      "integer",
      +                      "null"
      +                    ]
      +                  },
      +                  "start_line": {
      +                    "description": "1-based first line in this window.",
      +                    "type": "integer"
      +                  },
      +                  "total_lines": {
      +                    "description": "Total lines in symbol body.",
      +                    "type": "integer"
      +                  }
      +                },
      +                "type": "object"
      +              },
      +              "content": {
      +                "description": "Source code body or signature header (null if stale).",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "redacted_lines": {
      +                "description": "Number of secret-redacted lines.",
      +                "type": "integer"
      +              },
      +              "symbol": {
      +                "additionalProperties": true,
      +                "description": "Indexed symbol definition metadata.",
      +                "properties": {
      +                  "end_line": {
      +                    "description": "1-based declaration end line.",
      +                    "type": "integer"
      +                  },
      +                  "kind": {
      +                    "description": "Symbol kind (function, class, method, interface, etc.).",
      +                    "type": "string"
      +                  },
      +                  "name": {
      +                    "description": "Short symbol name.",
      +                    "type": "string"
      +                  },
      +                  "path": {
      +                    "description": "Repository-relative file path.",
      +                    "type": "string"
      +                  },
      +                  "qualified_name": {
      +                    "description": "Qualified symbol name.",
      +                    "type": "string"
      +                  },
      +                  "roles": {
      +                    "description": "Detected semantic/architectural roles.",
      +                    "items": {
      +                      "type": "string"
      +                    },
      +                    "type": "array"
      +                  },
      +                  "signature": {
      +                    "description": "Declaration signature header.",
      +                    "type": "string"
      +                  },
      +                  "start_line": {
      +                    "description": "1-based declaration start line.",
      +                    "type": "integer"
      +                  },
      +                  "symbol_id": {
      +                    "description": "Canonical repository-scoped symbol identifier.",
      +                    "type": "string"
      +                  }
      +                },
      +                "type": "object"
      +              },
      +              "warnings": {
      +                "description": "Per-symbol warnings.",
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              }
      +            },
      +            "type": "object"
      +          },
      +          "type": "array"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "edge_precision": {
      +      "additionalProperties": true,
      +      "description": "Resolved vs. ambiguous edge ratio summary.",
      +      "properties": {
      +        "ambiguous_rate": {
      +          "description": "Fraction of edges marked ambiguous.",
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        },
      +        "basis": {
      +          "description": "Measurement basis.",
      +          "type": "string"
      +        },
      +        "resolved_rate": {
      +          "description": "Fraction of edges resolved unambiguously.",
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "error": {
      +      "additionalProperties": true,
      +      "description": "Present when the tool call fails (either a structured {code, message, details} object or a diagnostic string).",
      +      "properties": {
      +        "code": {
      +          "description": "Machine-readable error code.",
      +          "type": "string"
      +        },
      +        "details": {
      +          "description": "Optional structured metadata for the error.",
      +          "type": "object"
      +        },
      +        "message": {
      +          "description": "Human-readable error explanation.",
      +          "type": "string"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "string"
      +      ]
      +    },
      +    "evidence": {
      +      "description": "Source-verified file line spans and SHA-256 hashes backing the response.",
      +      "items": {
      +        "additionalProperties": true,
      +        "properties": {
      +          "end_line": {
      +            "description": "1-based end line in source.",
      +            "type": "integer"
      +          },
      +          "path": {
      +            "description": "Repository-relative file path.",
      +            "type": "string"
      +          },
      +          "sha256": {
      +            "description": "12-character hex prefix of indexed file SHA-256.",
      +            "type": "string"
      +          },
      +          "start_line": {
      +            "description": "1-based start line in source.",
      +            "type": "integer"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "freshness": {
      +      "description": "Index freshness state ('fresh', 'pending', 'stale', or 'unknown').",
      +      "type": "string"
      +    },
      +    "index_run_id": {
      +      "description": "Identifier of the active index snapshot run.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "ledger_rev": {
      +      "description": "Current evidence ledger revision for repo_id.",
      +      "type": "integer"
      +    },
      +    "repo_id": {
      +      "description": "Registered repository identifier.",
      +      "type": "string"
      +    },
      +    "schema_version": {
      +      "description": "Envelope schema version ('1.0').",
      +      "type": "string"
      +    },
      +    "truncated": {
      +      "description": "True if items were omitted due to budget or node limits.",
      +      "type": "boolean"
      +    },
      +    "untrusted_repository_content": {
      +      "description": "True when payload embeds raw repository text.",
      +      "type": "boolean"
      +    },
      +    "warnings": {
      +      "description": "Freshness, ambiguity, redaction, or security warnings.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Changed8 schema fields changedv0.3.7
    • addedInput schema / properties / body_offset_line / description
      Added value: +"1-based relative line offset within the symbol body to page through large functions."
    • addedInput schema / properties / depth / description
      Added value: +"Caller/callee neighborhood traversal depth around the symbol (0 to 3)."
    • addedInput schema / properties / include_body / description
      Added value: +"Include the source code body of the target symbol (defaults to True for 'read' profile)."
    • addedInput schema / properties / include_omitted_ids / description
      Added value: +"Include symbol IDs omitted when neighbors exceed the token budget."
    • addedInput schema / properties / max_tokens / description
      Added value: +"Maximum token budget for the context packet (32 to max_result_tokens)."
    • addedInput schema / properties / profile / description
      Added value: +"Named budget profile ('locate', 'orient', 'impact', 'read'); defaults to 'read'."
    • addedInput schema / properties / repo_id / description
      Added value: +"Registered repository ID from list_repositories (never a filesystem path)."
    • addedInput schema / properties / symbol_id / description
      Added value: +"Exact symbol_id obtained from find_symbols, get_repo_map, or search_source."
  3. Changed1 schema field changedv0.3.3
    • addedInput schema / properties / body_offset_line
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Body Offset Line"
      +}
  4. First observedv0.1.0

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, closed-world, non-destructive behavior. The description adds important operational context: body is bounded, over-budget bodies are omitted, and body_offset_line pages long bodies. It does not discuss return shape, but an output schema exists.

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?

The definition is two short sentences with the primary behavior front-loaded. The parenthetical pagination and omission notes are relevant and not padded.

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 a full schema and an output schema, the description covers the core fetch/paging/omission behavior and the unknown-ID fallback. It leaves profile/depth/include_omitted_ids details to the schema, which is acceptable but not fully explanatory.

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%, so the schema already explains depth, profile, max_tokens, include_body, body_offset_line, and include_omitted_ids. The description mentions symbol_id, body_offset_line, and max_tokens behavior, but adds little beyond the schema text.

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 the exact action (fetch), the resources (bounded body and 0-3 hop edges), and the prerequisite (known symbol_id). It also contrasts with inspect_symbol for the unknown-ID case, so an agent can distinguish the intended use.

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?

Explicitly ties use to a known symbol_id and routes unknown IDs to inspect_symbol. That gives a clear when-to-use and when-to-use-alternative rule without requiring inference.

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