Nopaque TotalPath

Create IVR Mapping Job

createMapping

Destructive

Create an IVR mapping job that will call the specified phone number, navigate the menu tree via DTMF and/or voice prompts, transcribe audio, and analyse with AI to discover all branches. Returns a job resource immediately with status="idle". To start the actual mapping, call the startMapping REST endpoint (not yet exposed via MCP — use the REST API or wait for follow-up phases). Mapping completion typically takes 2-15 minutes depending on tree depth.

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": {
      "name": "<name>",
      "phoneNumber": "<phoneNumber>",
      "config": "<config>"
    },
    "name": "createMapping"
  }
}

Input Schema

Name	Required	Description
`name`	Yes	Job display name.
`tags`	No	Up to 10 lowercase kebab-case labels for filtering and organisation. Normalised server-side (trimmed, lowercased, de-duplicated).
`config`	Yes
`profileId`	No	Data profile used to supply scripted input values during the run.
`phoneNumber`	Yes	Target phone number in E.164 format.

Output Schema

Name	Required	Description
`id`	Yes	Unique mapping-job identifier.
`name`	Yes	Job display name.
`tags`	No	String labels for filtering and grouping. Lowercase alphanumeric + hyphens.
`error`	No	Error message if the job failed.
`stats`	No	Aggregate statistics for the current run, populated while the job executes.
`config`	Yes	Per-job configuration knobs that govern exploration shape and call orchestration. Sensible defaults are applied server-side when fields are omitted on create.
`status`	Yes	Current job status. Note: mapping jobs typically cycle `running` → `idle` after each run completes — they rarely persist `completed` state.
`userId`	Yes	User who created the job.
`createdAt`	Yes	Creation timestamp.
`runNumber`	No	Flat-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.
`startedAt`	No	Most-recent run start timestamp.
`updatedAt`	Yes	Last update timestamp.
`currentRun`	No	Nested 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`).
`completedAt`	No	Most-recent run completion timestamp.
`limitReason`	No	Reason the run stopped early (only present when `status` is `limited`).
`phoneNumber`	Yes	Target phone number in E.164 format.
`workspaceId`	Yes	Owning workspace.
`currentRunId`	No	Identifier of the most-recent run (absent if never started).
`inFlightCount`	No	Currently executing calls.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 11, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description adds genuinely non-redundant behaviour: the two-phase create-then-start lifecycle, the returned status="idle", and a 2-15 minute completion window. What it does not disclose is the cost/real-world side of dialing live phone numbers (per-call metering, minute consumption, duplicate-job effects given non-idempotency), which is the part an agent most needs when the destructive/open-world hints are already set.

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?

Four sentences, each carrying distinct information: purpose and mechanics, return shape, the blocking prerequisite, and expected duration. Purpose is front-loaded and there is no restated schema or filler.

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

Completeness4/5

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

An output schema exists and the description still usefully names the immediate return (idle job resource), plus the follow-up call required to actually run it — so an agent can execute correctly end-to-end. The remaining gap is operational context around real outbound dialing and non-idempotency, which matters given destructiveHint=true and openWorldHint=true.

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 80%, so the schema already carries most parameter meaning, and the heavy config object is documented field-by-field inline. The description only indirectly gestures at parameters ("DTMF and/or voice prompts" for mappingMode, "depending on tree depth" for maxDepth) without adding format or constraint detail beyond the schema. Baseline 3 is appropriate.

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+resource ("Create an IVR mapping job") and then spells out the full runtime behaviour — dials the number, navigates the menu via DTMF/voice, transcribes, analyses with AI to discover all branches. That is far more than a restatement of the name; an agent knows exactly what object it is producing and why.

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

Usage Guidelines4/5

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

Gives the crucial usage constraint: this tool only creates the job in status="idle", and the actual run must be triggered via the startMapping REST endpoint which is not exposed over MCP. That is explicit when/how-to-proceed guidance. It does not, however, distinguish this from any sibling (e.g. createImport) or state exclusions such as what to do for an already-running map.

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

All Nopaque TotalPath tools Inspect

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.