Skip to main content
Glama
Sign In

Nopaque TotalPath

by uk.co.nopaque
OverviewDiscussionsAdmin

List Mapping Jobs

listMappings
Read-onlyIdempotent

List IVR mapping jobs in your workspace. Supports filtering and cursor pagination.

FILTERS (all optional):
- status: Filter by the latest run's status. Values: idle | running | completed | failed | limited.
  IMPORTANT: Mapping JOBS cycle between status `running` (active mapping) and `idle` (between runs)
  and NEVER reach `completed`. Only RUNS reach `completed`/`failed`/`limited`. The `status` filter
  compares against the latest run's status — so `status=completed` returns jobs whose most recent
  run finished, and `status=running` returns jobs with an in-flight run.
- tag: Filter to jobs with this tag (exact, lowercase alphanumeric + hyphens, e.g. 'compliance-eu').
- phoneNumber: Filter by exact E.164 phone number (e.g. '+441234567890').
- name: Case-insensitive substring match against the job name.
- profileId: Filter to jobs using a specific mapping profile (UUID).
- createdAfter / createdBefore: ISO-8601 datetime strings (e.g. '2026-05-01T00:00:00Z'). Efficient
  DDB range filter — both, either, or neither.
- limit: Page size, 1-100, default 50.

SORTING:
- sortDir: 'asc' or 'desc' (default 'desc' = newest first). Sort is always by createdAt.

PAGINATION:
- Pass `cursor` (from a previous response's `nextCursor`) to get the next page.
- When `nextCursor` is absent from the response, you are on the last page.
- LOSSY-PAGINATION CAVEAT: When filtering by `status`, paged results may underfill (return fewer
  than `limit` items) because the status filter is applied after the DDB query. Always follow
  `nextCursor` until it is absent to be sure you have all matches.

RESULT FIELDS:
- id: UUID — use with `getMapping` for full detail (run state, step counts) or `getMappingTree`
  for the discovered IVR tree (once the latest run has status=`completed`).
- status: The latest run's status; `idle` when the job has no active run.
- tags: String labels for grouping. Set via `createMapping` / mapping update.
- config: Includes mappingMode, maxDepth, maxCalls, probeMode.
- runNumber: The run number of the latest run, if any.

USAGE PATTERNS:
- "List my 5 most recent mappings" → { limit: 5, sortDir: 'desc' }
- "Show running mapping jobs" → { status: 'running' }
- "Mappings tagged compliance-eu" → { tag: 'compliance-eu' }
- "Mappings created this week" → { createdAfter: '<start-of-week ISO>' }
- "Find runs for +44... in detail" → call listMappings { phoneNumber: '+44...' } then getMapping(id)

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "listMappings"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagNoFilter to jobs with this tag (exact, lowercase alphanumeric + hyphens).
nameNoCase-insensitive substring match against the job name.
limitNoPage size (1–100, default 50).
cursorNoOpaque cursor from a previous response's `nextCursor` to fetch the next page.
hasRunNomapping-pages-discarded-cursor fix. When true, filter to jobs with at least one run (latest run's status != idle). When false, only idle jobs. Independent of `status` — both may be combined. Post-merge filter, same underfill caveat as `status` applies: always follow `nextCursor` until absent.
searchNomapping-pages-discarded-cursor fix. Case-insensitive OR substring match across job `name` and `phoneNumber` — server-side equivalent of the Map Results page search box. Distinct from the exact-match `name`/`phoneNumber` filters above, which remain ANDed when both given and are unchanged by this addition.
statusNoFilter by the latest run's status.
sortDirNoSort direction by createdAt (default desc = newest first).desc
profileIdNoFilter to jobs using a specific mapping profile.
phoneNumberNoFilter by exact E.164 phone number.
createdAfterNoISO-8601 datetime; return jobs created at or after this time.
createdBeforeNoISO-8601 datetime; return jobs created before this time.

Output Schema

NameRequiredDescriptionDefault
itemsYes
nextTokenNoAlias for nextCursor (frontend back-compat). Absent on the last page.
nextCursorNoOpaque base64-encoded cursor. Pass back in `cursor` query param to fetch next page. Absent on the last page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered before the description starts. The description nonetheless adds substantive behavior the annotations cannot carry: the job-vs-run status distinction and the explicit LOSSY-PAGINATION CAVEAT that paged status-filtered results may underfill and must be followed to nextCursor. Return-shape detail is largely a restatement of the existing output schema, which caps the added value at solid-but-partial.

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?

Despite its length, it is front-loaded with the purpose, then cleanly sectioned into FILTERS, SORTING, PAGINATION, RESULT FIELDS, and USAGE PATTERNS, so an agent can scan to the section it needs. The caveats are attached to the parameters they affect rather than collected at the end, which is the correct placement for warnings.

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?

With 12 optional parameters, an output schema, and a non-obvious server-side filter pipeline, this is a complex tool, and the definition covers filtering semantics, sort behavior, pagination termination, and follow-up tools. An agent could call it correctly on the first try from this definition alone.

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%, so the baseline would be 3; the description earns above that by explaining the non-obvious semantics of `status` (compared against the latest run, jobs never reach completed) and by giving format examples for tag, phoneNumber, and createdAfter/Before. It falls short of 5 because the FILTERS list is presented as exhaustive ('all optional') yet omits `search` and `hasRun`, which exist in the schema with underfill caveats of their own.

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 ('List IVR mapping jobs in your workspace') and adds scope ('Supports filtering and cursor pagination'). The RESULT FIELDS section further routes the agent ('use with getMapping for full detail ... or getMappingTree for the discovered IVR tree'), so it is distinguishable in practice from the detail-fetching siblings.

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?

The USAGE PATTERNS section gives five concrete natural-language-to-parameter mappings and explicitly chains the tool with getMapping for the detail follow-up. It also states when not to expect results from a status filter ('Mapping JOBS ... NEVER reach completed'), which is real exclusion guidance rather than implied context.

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