Skip to main content
Glama

trace_path

Read-onlyIdempotent

Map call graphs, data flow, or cross-service paths with hop-by-hop relations and totals. Defaults skip tests for focused output.

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, or service edges.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. 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."
  2. Changed1 schema field changedv0.10.4
    • changedOutput schema / (root)
      Previous value: -{
      -  "additionalProperties": true,
      -  "type": "object"
      -}New value: +null
  3. 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"
      +}
  4. 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"
      +}
  5. First observedv1.0.0

TDQS

A3.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral details: default exclusions of tests and resolver evidence, and the fact that rows preserve qn/hop with explicit totals, relations, and continuations. No contradiction with annotations.

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?

Two compact sentences with the core purpose front-loaded. Every phrase adds information, and there is no filler or repetition of schema details.

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 tool with 14 parameters and no output schema, the description is relatively sparse. It covers basic behavior and output row shape, but leaves mode-specific behavior, direction/edge_types semantics, and pagination details largely to the schema. Adequate but with clear gaps.

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 only 57%, so the description should compensate. It does add implicit meaning around include_tests and include_evidence by mentioning defaults, but it does not explain direction, edge_types, depth, or cursor behavior beyond what the schema already provides.

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?

The description opens with the specific verb 'Trace' and names the resource types: callers/callees, data flow, and cross-service paths. It clearly distinguishes what the tool operates on, though it does not explicitly contrast it with sibling graph/query tools.

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 guidance on when to use trace_path versus search_graph, query_graph, or get_architecture. The description only states default exclusions (tests, resolver evidence) and row content, leaving the selection decision to the agent.

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