Adopt

5 surfaces
Tools/Spec Introspection/trace

trace

[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing tracing, invoke the /upg-trace skill instead of calling this tool directly. Trace approach: path of arrival to "walk a meaningful path through existing graph". Returns the Trace record + invocation params in the family-resemblance envelope. The LLM uses `anchor` + `path` to compose `query()` calls and emits `{ trail: [{ depth, entity_id, edge_type_in }], reached: entity_id[] }`. `path` is type-shorthand: `["persona","job","feature"]` walks persona→job→feature using the canonical edge per pair (via `resolve_edge_for_pair`). Optional `edges_override` selects non-canonical edges per hop; `null` per element means "use canonical".

Spec Introspectionatomic (read-only)

Arguments

anchorstringrequired

Required. entity_id where the traversal starts.

patharrayrequired

Required. UPGEntityType[] type-shorthand path. Each step walks via the canonical edge for the source→target pair.

edges_overridearrayoptional

Optional. Per-hop edge override array. Length must match path length; element null means "use canonical edge for this pair".

Returns

JSON envelope: { approach_id, scope, generated_at, approach, params, trail, reached, error?, halted_at_depth?, execution_mode: "execution_v0_4_0" }

Examples

Live call against the Notion example graph.

Input

{
  "anchor": "ec3d5479-4947-4bd9-9e77-b5ee01beb851",
  "path": [
    "opportunity_drives_solution"
  ]
}

Output

{
  "approach_id": "trace",
  "scope": "ec3d5479-4947-4bd9-9e77-b5ee01beb851",
  "generated_at": "2026-05-29T20:13:19.988Z",
  "approach": {
    "id": "trace",
    "label": "Trace",
    "description": "The path of arrival to \"walk a meaningful path through existing graph\". Trace engages an anchor entity and follows a path expressed as a UPGEntityType[] shorthand. Example: `[\"persona\", \"job\", \"feature\"]` walks persona→job→feature using the canonical edge for each pair (resolved via `resolve_edge_for_pair`). An optional `edges_override` array selects non-canonical edges per hop when a pair has multiple resolutions. Cartographic sense: you are tracing a route across charted terrain; anchor is the departure, path is the heading sequence, the canonical edges are the roads. No DSL invented; the shorthand IS the path expression.",
    "question_answered": "walk a meaningful path through existing graph",
    "signature_hint": "({ anchor: entity_id, path: UPGEntityType[], edges_override?: (string | null)[] }) → { trail: [{ depth, entity_id, edge_type_in }], reached: entity_id[] }",
    "framework_id_examples": [
      "opportunity-solution-tree",
      "strategic-cascade",
      "metrics-tree",
      "user-journey-map",
      "impact-map",
      "dependency-map"
    ]
  },
  "params": {
    "anchor": "ec3d5479-4947-4bd9-9e77-b5ee01beb851",
    "path": [
… (truncated)

See Also