AnalyticsProof

Save an edited journey document

replace_journey

DestructiveIdempotent

Save an edited journey document (permission: edit)

Send the GET /journeys/{id} document back, edited. Read-only keys are ignored. When the steps, the viewport and the typed values are unchanged (no value supplied), nothing is written and the baseline is kept: 200 with scan: null (a changed name is applied). Otherwise every step is replaced (the same step contract as POST /journeys), the journey starts a new baseline and is replayed right away: poll scan.pollUrl. When the replay is queued behind a running replay of this test's journeys, it starts when that one ends. When the replay cannot be scheduled the steps are still replaced: scan is null and scanError says why (journey_paused for a paused journey: saved, not replayed; resume it with PATCH). scan is non-null exactly when a scan was queued. On a type step, omit value to keep the stored one (the step must keep its index and selector; otherwise 400 value_required); a supplied value always re-records and is never echoed. A journey without a stored start page needs a url on at least one step (otherwise 400 invalid_type on steps[0].url). Every problem is reported at once in error.details[]. No consent action is added: record the banner click as a step when the journey needs it. The answer carries the new ETag. idempotencyKey (sent as the Idempotency-Key header): retrying the same call with the same value replays the original answer; the same value with different arguments is 422 idempotency_conflict, and 409 idempotent_in_progress means wait error.meta.retryAfter seconds and retry.

etag is sent as If-Match: pass the etag of your last get_journey; on precondition_failed call get_journey again and retry.

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>",
      "body": "<body>",
      "etag": "<etag>"
    },
    "name": "replace_journey"
  }
}

Input Schema

Name	Required	Description
`id`	Yes	Journey id: from GET /journeys or the POST /journeys answer.
`body`	Yes	The GET /journeys/{id} document. Read-only keys are ignored on input, except `id` (must be the path id) and a `status` change to paused/active (400 read_only: use PATCH). Unknown keys are refused.
`etag`	Yes	The `etag` returned by get_journey (or by the last write), sent as If-Match.
`idempotencyKey`	No	Optional Idempotency-Key: reuse the same value when retrying this exact call so it is applied once.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 5, 2026
- addedInput schema / properties / id / description
```
Added value: +"Journey id: from GET /journeys or the POST /journeys answer."
```
First observedNov 4, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes far past the annotations: it specifies the 200-with-scan:null no-op case, that a changed name still applies there, that 'scan is non-null exactly when a scan was queued', the queued-behind-a-running-replay behaviour, and the scanError reason 'journey_paused'. It also documents the ETag/If-Match precondition with the precondition_failed re-get-and-retry loop and the idempotencyKey outcomes (422 idempotency_conflict, 409 idempotent_in_progress with retryAfter). Nothing here contradicts destructiveHint=true or idempotentHint=true; it reinforces both.

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?

Front-loaded with the core instruction and the no-op rule before the edge cases, and every sentence carries an operational fact. It is dense to the point of being dense-but-long — the short-circuit conditions and the value_required rule also appear in the body and step schemas — so a bit of duplication keeps it out of the top band.

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 destructive full-document replace with nested step objects and no output schema, the description still covers what the call returns (new ETag, scan.pollUrl, scan:null + scanError), how errors are aggregated ('Every problem is reported at once in error.details[]'), and the consent follow-up ('No consent action is added: record the banner click as a step'). An agent has everything needed to call it and handle the responses.

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 is 3, but the description earns above it by explaining the PUT-only rules that shape the arguments: omitting 'value' keeps the stored value only if the step keeps its index and selector (else 400 value_required), a supplied value always re-records and is never echoed, and a journey with no stored start page needs a url on some step. It also explains why etag must be the one from the last get_journey or write, which is more than the schema's field note says.

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 concrete verb and resource — 'Save an edited journey document' — and immediately defines the mechanism: 'Send the GET /journeys/{id} document back, edited. Read-only keys are ignored.' That full-document PUT semantics plus the '(permission: edit)' note separates it from create_journey, patch_journey and delete_journey without needing to open 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 Guidelines4/5

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

Gives a precise rule for the no-op path (steps, viewport and typed values unchanged → nothing written, baseline kept) versus the replace path (every step replaced, new baseline, replay queued) and points at PATCH for resuming a paused journey. What it never does is name the sibling alternatives — patch_journey for metadata-only edits or create_journey for new journeys — so routing is inferable rather than explicit.

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

All AnalyticsProof 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.

Resources

Need Help?