Skip to main content
Glama
Sign In

Nopaque TotalPath

by uk.co.nopaque
OverviewDiscussionsAdmin

Get Discovered IVR Tree

getMappingTree
Read-onlyIdempotent

Get the discovered IVR tree structure for a mapping job — every node visited, the DTMF/voice paths between them, audio recordings, and (if enrichment ran) IVR menu transcripts and probe classifications.

USE WHEN:
- User asks for the discovered tree / map / structure of an IVR
- User wants leaf-node count, depth, or aggregate tree statistics (use `format=flat`)
- User wants to inspect specific tree-node fields (voice prompts, probe classifications, audio URLs)
- User wants to compare two historical runs (call twice with different `version`)

BEST CALLED: after `currentRun.status === 'completed'` (from getMapping). If you call earlier and
the run is still active, the response will document that via `reason: 'in_progress'` (see below).

QUERY PARAMS (optional):
- format: `tree` (default) = hierarchical nesting; `flat` = array of nodes with depth/path fields
  for aggregation. Use `flat` for "how many leaves?" / "how deep?" / "list all voice prompts" questions.
- version: Run number (1-indexed) — fetches the tree of that historical run. Default: latest run.

RESPONSE — SUCCESS (tree built from steps):
- jobId, runId, runNumber, status, stats: identifiers + run-level summary.
- tree (when `format=tree`): a hierarchical TreeNode with .children[] recursion.
- steps (when `format=flat`): an array of TreeNode (each with empty .children, depth, path).

TreeNode fields (each is OPTIONAL — omitted when absent; never null per the AJV contract):
- stepId, digit, label, depth, path, status, transcript, isTerminal, children, duration
- stepType: 'dtmf' | 'voice' — interaction type (Phase 30 voice-agent)
- voicePrompt: spoken prompt text at this node (voice nodes only)
- menuLabel: semantic tag emitted per bot turn (e.g. 'greeting', 'capabilities_listed', 'balance_captured'); from Phase 55 voice-agent enrichment
- spokenResponse: what the agent said back at this turn (Phase 55 voice-agent)
- probeCategory / probeClassification / probeRationale: probe-enrichment fields (Phase 31). Only present
  after probe enrichment ran. Trigger probes via REST POST /mapping/{id}/runs/{runId}/probe (not exposed
  via MCP today).
- audioUrl: presigned S3 URL for the recorded audio of this step. **Valid for approximately 1 hour.
  Do not cache or store** — re-call getMappingTree to refresh URLs for long sessions.
- inputRequired: per-step UX hint when a prompt requires user input. Contains type, description,
  formatHint, terminator, startTimeMs.

RESPONSE — EMPTY-STATE ENVELOPE (200 OK, tree: null):
The handler returns 200 with `tree: null` and a `reason` discriminator in three cases:
- `reason: 'no_runs'` — the job has never been started. Message suggests POST /mapping/{id}/start.
- `reason: 'no_steps'` — a run started but no steps recorded yet. May still be initialising; retry shortly.
- `reason: 'in_progress'` — the latest run is still active and only the root step has been recorded.
  Don't treat the current tree as complete. Retry shortly OR ask getMapping for `currentRun.status` to confirm.

All three empty-state cases return 200 OK with the same envelope shape; only `reason` + `message` differ.

USAGE PATTERNS:
- "Show me the IVR tree for mapping <id>" → getMappingTree { id }
- "How many leaves does mapping <id> have?" → getMappingTree { id, format: 'flat' } then filter steps where children.length === 0 OR isTerminal === true
- "How deep is the tree?" → getMappingTree { id, format: 'flat' } then max(steps[].depth)
- "What voice prompts did mapping <id> discover?" → getMappingTree { id, format: 'flat' } then filter where stepType === 'voice' or voicePrompt is present
- "Show me run 1's tree" → getMappingTree { id, version: 1 }
- "What probe classifications fired?" → getMappingTree { id } then walk tree filtering nodes where probeClassification is present

RELATED TOOLS:
- getMapping — job + run metadata, including `currentRun.status` (check this before deciding the tree is "done")
- listMappings — find jobs by phoneNumber/status/tag if you don't have the id
- REST GET /mapping/{id}/runs — run history (REST-only today; useful for picking a `version` for historical tree fetches)

ERRORS:
- 404: job does not exist or belongs to another workspace (cross-workspace 404 by design — do not retry)
- 400: invalid version (non-integer or < 1) OR invalid format (not 'tree' or 'flat')
- 404: requested version not found
- 200 + reason: 'no_runs' | 'no_steps' | 'in_progress' — NOT errors; empty-state envelope (see above)

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": {
      "id": "<id>"
    },
    "name": "getMappingTree"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesMapping job UUID. Find via listMappings if unknown.
formatNoResponse shape. `tree` = hierarchical nesting (default). `flat` = array of nodes with depth/path fields for aggregation.tree
versionNoRun number (1-indexed) — fetches the tree of that historical run. Default: latest run.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already establish a safe read (readOnlyHint, idempotentHint, non-destructive), but the description adds substantial behavior the annotations cannot express: presigned audioUrl expires in ~1 hour and must not be cached, the three empty-state `reason` discriminators returned as 200 OK, the in_progress caution, and the enumeration of error statuses including the deliberate cross-workspace 404.

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?

Well front-loaded: purpose, then when-to-use, then params, then response shapes, patterns, related tools, errors. It is long, and parts (format/version definitions, TreeNode field list) duplicate the input and output schemas, but every section is scannable and goal-relevant rather than padded.

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

Completeness5/5

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

For a read tool with three params, an output schema, and multiple enrichment phases, the definition covers the edge cases an agent would otherwise get wrong: the null-tree envelope, enrichment-gated fields (probe*, voicePrompt, menuLabel), and the out-of-band probe REST route. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is a 3, but the description goes further by explaining what each `format` value produces (`tree` = children[] recursion vs `flat` = array with depth/path) and ties `version` to comparing two historical runs. That operational meaning exceeds the schema's terse field descriptions, though it restates a fair amount of the schema text verbatim.

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?

The opening sentence gives a specific verb and resource ("Get the discovered IVR tree structure for a mapping job") and enumerates the payload (nodes, DTMF/voice paths, audio, enrichment fields). It is clearly differentiated from sibling getMapping, which the definition explicitly frames as metadata-only.

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?

A dedicated USE WHEN block lists four concrete triggering intents plus six worked usage patterns mapping natural-language questions to exact calls and post-processing. It also names alternatives (getMapping for currentRun.status, listMappings to find the id) and the condition that selects them.

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

All Nopaque TotalPath toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources