Skip to main content
Glama

trace_path

Read-onlyIdempotent

Map callers, callees, data flow, or cross-service paths in a codebase to understand dependencies, with configurable depth, direction, and pagination.

Instructions

Trace callers/callees, data flow, or cross-service paths. Defaults exclude tests and resolver evidence. Rows keep qn/hop with explicit totals, relations, and continuations.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modeNocalls; argument-aware data_flow; service edges; topology: infra objects, routes, controllers (from a Resource/Route); deploy: what CI jobs and scripts run and deploy; run: what a Service runs (image, Dockerfile, program, env).calls
depthNo
limitNoRows/page; gte flags the 5000-node engine ceiling.
cursorNoPass next/next_cursor with traversal args unchanged; budget may increase.
formatNotree chooses smaller complete direct/grouped output; json uses stable grouped tables.tree
projectYes
directionNoboth
edge_typesNo
risk_labelsNoAdd hop-risk labels.
function_nameYes
include_testsNo
parameter_nameNodata_flow parameter filter.
include_evidenceNoAdd resolver class and confidence.
max_output_tokensNoSizing hint; hard ceiling is 4 UTF-8 bytes/token. Evidence/args yield before nearest graph rows.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.12.1
    • changedInput schema / properties / mode / description
      Previous value: -"calls, argument-aware data_flow, or service edges."New value: +"calls; argument-aware data_flow; service edges; topology: infra objects, routes, controllers (from a Resource/Route); deploy: what CI jobs and scripts run and deploy; run: what a Service runs (image, Dockerfile, program, env)."
    • changedInput schema / properties / mode / enum
      Previous value: -[
      -  "calls",
      -  "data_flow",
      -  "cross_service"
      -]New value: +[
      +  "calls",
      +  "data_flow",
      +  "cross_service",
      +  "topology",
      +  "deploy",
      +  "run"
      +]
  2. Changed11 schema fields changedv0.11.0
    • changedInput schema / properties / cursor / description
      Previous value: -"Resume token from a previous response's 'next' field. Pass it back with ALL other arguments identical to get the following page with no duplicates. Cursors outlive nothing: after a reindex you get a stale_cursor error — just re-run the original query."New value: +"Pass next/next_cursor with traversal args unchanged; budget may increase."
    • addedInput schema / properties / depth / maximum
      Added value: +15
    • addedInput schema / properties / depth / minimum
      Added value: +1
    • changedInput schema / properties / format / description
      Previous value: -"Response encoding. tree (default): prefix-grouped text rows. json: the SAME tree model as structured JSON (groups + column-ordered row arrays)."New value: +"tree chooses smaller complete direct/grouped output; json uses stable grouped tables."
    • changedInput schema / properties / include_evidence / description
      Previous value: -"Add how each hop was resolved: a strategy class (lsp | language_rule | heuristic | unresolved) and the resolver's confidence. Off by default — it adds two columns per row. Use it to judge whether an edge is trustworthy, not to find edges."New value: +"Add resolver class and confidence."
    • removedInput schema / properties / include_tests / description
      Removed value: -"Include test files in results. When false (default), test files are filtered out. When true, test nodes are included with a test column/marker."
    • changedInput schema / properties / limit / description
      Previous value: -"Rows per page. callees_total/callers_total always carry the exact full counts; when a page is truncated the response carries next — see cursor."New value: +"Rows/page; gte flags the 5000-node engine ceiling."
    • addedInput schema / properties / max_output_tokens
      Added value: +{
      +  "default": 3200,
      +  "description": "Sizing hint; hard ceiling is 4 UTF-8 bytes/token. Evidence/args yield before nearest graph rows.",
      +  "maximum": 1000000,
      +  "minimum": 128,
      +  "type": "integer"
      +}
    • changedInput schema / properties / mode / description
      Previous value: -"calls: follow CALLS edges. data_flow: follow CALLS+DATA_FLOWS with arg expressions. cross_service: follow HTTP_CALLS+ASYNC_CALLS+DATA_FLOWS through Routes, plus CROSS_* cross-repo edges (CROSS_HTTP_CALLS/ASYNC_CALLS/CHANNEL/GRPC_CALLS/GRAPHQL_CALLS/TRPC_CALLS) to hop into other services."New value: +"calls, argument-aware data_flow, or service edges."
    • changedInput schema / properties / parameter_name / description
      Previous value: -"For data_flow mode: scope trace to a specific parameter name"New value: +"data_flow parameter filter."
    • changedInput schema / properties / risk_labels / description
      Previous value: -"Add risk classification (CRITICAL/HIGH/MEDIUM/LOW) based on hop distance"New value: +"Add hop-risk labels."
  3. Changed1 schema field changedv0.10.4
    • changedOutput schema / (root)
      Previous value: -{
      -  "additionalProperties": true,
      -  "type": "object"
      -}New value: +null
  4. Changed5 schema fields changedv0.10.0
    • addedInput schema / properties / cursor
      Added value: +{
      +  "description": "Resume token from a previous response's 'next' field. Pass it back with ALL other arguments identical to get the following page with no duplicates. Cursors outlive nothing: after a reindex you get a stale_cursor error — just re-run the original query.",
      +  "type": "string"
      +}
    • addedInput schema / properties / format
      Added value: +{
      +  "default": "tree",
      +  "description": "Response encoding. tree (default): prefix-grouped text rows. json: the SAME tree model as structured JSON (groups + column-ordered row arrays).",
      +  "enum": [
      +    "tree",
      +    "json"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / include_evidence
      Added value: +{
      +  "default": false,
      +  "description": "Add how each hop was resolved: a strategy class (lsp | language_rule | heuristic | unresolved) and the resolver's confidence. Off by default — it adds two columns per row. Use it to judge whether an edge is trustworthy, not to find edges.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / include_tests / description
      Previous value: -"Include test files in results. When false (default), test files are filtered out. When true, test nodes are included with is_test=true marker."New value: +"Include test files in results. When false (default), test files are filtered out. When true, test nodes are included with a test column/marker."
    • addedInput schema / properties / limit
      Added value: +{
      +  "default": 100,
      +  "description": "Rows per page. callees_total/callers_total always carry the exact full counts; when a page is truncated the response carries next — see cursor.",
      +  "maximum": 5000,
      +  "minimum": 1,
      +  "type": "integer"
      +}
  5. Changed2 schema fields changedv0.9.0
    • changedInput schema / properties / mode / description
      Previous value: -"calls: follow CALLS edges. data_flow: follow CALLS+DATA_FLOWS with arg expressions. cross_service: follow HTTP_CALLS+ASYNC_CALLS+DATA_FLOWS through Routes."New value: +"calls: follow CALLS edges. data_flow: follow CALLS+DATA_FLOWS with arg expressions. cross_service: follow HTTP_CALLS+ASYNC_CALLS+DATA_FLOWS through Routes, plus CROSS_* cross-repo edges (CROSS_HTTP_CALLS/ASYNC_CALLS/CHANNEL/GRPC_CALLS/GRAPHQL_CALLS/TRPC_CALLS) to hop into other services."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "type": "object"
      +}
  6. First observedv1.0.0

TDQS

B3.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds real value on defaults (tests and resolver evidence excluded) and on row shape (qn/hop plus totals, relations, continuations), which is not derivable from structured fields. It stops short of describing pagination limits or failure behavior.

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?

Three dense sentences, front-loaded with the action and mode variety, then defaults, then output shape. No filler, though it is somewhat telegraphic ('qn/hop', 'continuations') in a way that may be opaque to a first-time caller.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter tool with no output schema, the description sketches row structure but omits usage context relative to siblings and any prerequisite on indexing. It is adequate but leaves meaningful gaps an agent would otherwise have to discover by trial.

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 57%, a middling level, with the mode enum, limit, cursor, risk_labels, and evidence descriptions already carrying the weight. The description's only param-relevant content is the restatement that defaults exclude tests and evidence, adding little beyond the schema.

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?

States a specific verb (Trace) and the resources traversed (callers/callees, data flow, cross-service paths), so an agent knows it walks graphs rather than searching them. It does not name or contrast the obvious siblings (query_graph, search_graph), so an agent must infer the boundary itself, keeping it just under a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to reach for trace_path versus query_graph, search_graph, or get_architecture, nor any stated preconditions (e.g., that the project must be indexed first). The mode list in the schema implies use cases but the description contributes no selection criteria.

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