Skip to main content
Glama
Sign In

Nopaque TotalPath

by uk.co.nopaque
OverviewDiscussionsAdmin

Get Mapping Job

getMapping
Read-onlyIdempotent

Get the current state and run metadata for a specific IVR mapping job.

USE WHEN:
- User asks about a specific mapping job by ID
- User wants to know if a mapping run has finished
- User wants run-level metadata (stats, in-flight calls, start/completion times)
- You need a job's currentRun.id to feed into getMappingTree or REST /mapping/{id}/runs

QUERY PARAMS (optional):
- version: Run number (1-indexed) — fetches that specific historical run. Default: latest run.

JOB vs RUN STATUS (critical):
Mapping JOBS cycle status `running` ↔ `idle` and **never reach `completed`** between runs.
Only RUNS reach `completed` / `failed` / `limited`. To detect a finished run, read
`currentRun.status === 'completed'`. **Do NOT poll for `status === 'completed'` at the
job level — that state never arrives.** See getMappingTree for the discovered IVR tree,
available once `currentRun.status === 'completed'`.

RESPONSE FIELDS:
- id: Job UUID.
- status: Job-level status (always `idle` between runs; `running` during an active run).
- tags: String labels for grouping (set via createMapping or update).
- config: mappingMode, maxDepth, maxCalls, probeMode.
- currentRun: The run this response describes — the active/latest run by default, or the run
  identified by `version` when supplied. Contains: id, status, runNumber, stats, inFlightCount,
  limitReason, startedAt, completedAt. **Prefer `currentRun.status` over the flat `status`.**
- status / runNumber / stats / inFlightCount / limitReason / startedAt / completedAt: Flat-merged
  duplicates of currentRun fields, kept for back-compat. New code should read currentRun.*.

USAGE PATTERNS:
- "Is mapping <id> finished?" → getMapping { id } then read `currentRun.status`
- "Show me run 2 of mapping <id>" → getMapping { id, version: 2 }
- "What's the in-flight call count for mapping <id>?" → getMapping { id } then read `currentRun.inFlightCount`

RELATED TOOLS:
- listMappings — find a job by phoneNumber/status/tag/createdAfter (use this before getMapping if you don't have the id)
- getMappingTree — discovered IVR tree once `currentRun.status === 'completed'` (use `?format=flat` for leaf-count / depth aggregation)
- cancelMapping — **DESTRUCTIVE** — stop an in-progress run; only call when explicitly asked
- createMapping — **REAL CALL** — starts a new mapping run (initiates external phone call); only call when explicitly asked
- REST GET /mapping/{id}/runs — run history (REST-only today; may surface as a future MCP tool if eval shows demand)

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)
- 404: requested version not found in this job's run history (response message lists available versions)

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": "getMapping"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesMapping job UUID. Find via listMappings if unknown.
versionNoRun number (1-indexed) — fetches that specific historical run. Default: latest run.

Output Schema

NameRequiredDescriptionDefault
idYesUnique mapping-job identifier.
nameYesJob display name.
tagsNoString labels for filtering and grouping. Lowercase alphanumeric + hyphens.
errorNoError message if the job failed.
statsNoAggregate statistics for the current run, populated while the job executes.
configYesPer-job configuration knobs that govern exploration shape and call orchestration. Sensible defaults are applied server-side when fields are omitted on create.
statusYesCurrent job status. Note: mapping jobs typically cycle `running` → `idle` after each run completes — they rarely persist `completed` state.
userIdYesUser who created the job.
createdAtYesCreation timestamp.
runNumberNoFlat-merged run number from the active or requested (via `?version=`) run. Phase 04 D-09 — preserved at top level for frontend back-compat alongside the new nested `currentRun` object.
startedAtNoMost-recent run start timestamp.
updatedAtYesLast update timestamp.
currentRunNoNested run summary on single-job responses (Phase 04 D-09 / D-10). Unlike the job-level `status` (which cycles `running` ↔ `idle` and never reaches `completed`), `currentRun.status` CAN reach `completed`/`failed`/`limited`. Read this field to decide whether the discovery is done — do NOT poll for `status === 'completed'` on the job itself. The field name stays `currentRun` even when `?version=N` is supplied — the wrapper describes the run this response describes (active by default, or the historical run identified by `version`).
completedAtNoMost-recent run completion timestamp.
limitReasonNoReason the run stopped early (only present when `status` is `limited`).
phoneNumberYesTarget phone number in E.164 format.
workspaceIdYesOwning workspace.
currentRunIdNoIdentifier of the most-recent run (absent if never started).
inFlightCountNoCurrently executing calls.

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 cover safety (readOnly, idempotent, non-destructive), yet the description adds a critical non-obvious behavioral fact: jobs cycle running↔idle and never reach 'completed', so polling job-level status would hang forever. It also discloses the cross-workspace 404-by-design (do not retry) and the back-compat flat-merged duplicate fields, none of which are derivable from annotations.

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?

Headers are front-loaded (USE WHEN, QUERY PARAMS, then the critical JOB vs RUN section) and the most failure-prone fact is surfaced early. The RESPONSE FIELDS block duplicates what the existing output schema already declares and is the one section that does not fully earn its length.

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 two-parameter read tool with an output schema, this covers everything an agent needs: correct completion detection, which field to prefer over the back-compat duplicates, run-history selection via version, and the full error taxonomy with retry guidance.

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 100% and the schema already documents id and version, so the baseline is 3; the description still adds value by tying version to concrete usage patterns ('Show me run 2' → version: 2) and by mapping invalid version to the 400 error and a version-not-found 404. It stops short of 5 because the parameter wording largely restates the schema field descriptions.

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 a specific verb and resource ('Get the current state and run metadata for a specific IVR mapping job') and explicitly separates itself from getMappingTree (discovered tree, post-completion) and listMappings (find the id). An agent can distinguish this from every named sibling without opening a schema.

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 USE WHEN block gives four concrete trigger conditions, RELATED TOOLS names alternatives and the condition that selects each (listMappings when you lack the id, getMappingTree after completion, REST runs endpoint for history), and it names when-not-to-call behaviors for siblings (cancelMapping/createMapping only when explicitly asked).

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