Proof Holdings

wait_for_request

Read-only

Poll a verification request until it reaches a terminal state (completed, expired, or cancelled). Uses exponential backoff (2s initial, 1.5x, 30s max) with jitter.

ACCESS: needs a Proof account. Authenticate this client (Claude Code: /mcp → Authenticate), then call this tool again. start_login does NOT open this tool.

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

Input Schema

Name	Required	Description	Default
`id`	Yes	Verification request ID to poll
`timeout_seconds`	No	Maximum wait time in seconds (default: 50, max: 300). Keep it under your MCP client's request timeout (the SDK default is 60 s) — a longer wait is cut off by the client while the server is still polling. On timeout the tool answers status "pending"; call it again with the same identifier.

Output Schema

Name	Required	Description
`id`	No	MongoDB ObjectId
`assets`	No
`status`	No	"pending" when the wait ran out before a terminal state; otherwise the resource's own status
`message`	No	On timeout: what to do next (call the tool again with the same identifier)
`outcome`	No	`relying_party` when the request was created to wait for your outcome; null otherwise. Absent from an API that predates the field.
`progress`	No
`created_at`	No
`expires_at`	No
`partial_ok`	No
`updated_at`	No
`action_type`	No	Type of action for verification request or authorization
`last_status`	No	On timeout: the last non-terminal status observed, or null when none was
`callback_url`	No	The webhook URL set on the request, if any
`completed_at`	No
`redirect_url`	No
`reference_id`	No
`action_context`	No	The action the person is asked to authorize; null when the request carries none
`computed_state`	No	Additive machine-readable effective state: re-derives expiry from expires_at (never trusts the stored status). BOTH `is_expiring_soon` and `next_action` are role-aware — `next_action.role` says which side this envelope was computed for, and the two fields are consistent within it. Present only on authenticated owner/requester and recipient responses; absent on public/third-party surfaces.
`waited_seconds`	No	On timeout: seconds actually waited
`timeout_seconds`	No	On timeout: the wait budget this call was given
`verification_url`	No	URL for the verification flow
`validity_requirement`	No	Required proof freshness as set on the request (e.g. "7d"); null when none was set
`outcome_timeout_seconds`	No	The window set on the request, in seconds; null when it does not wait for an outcome. Absent from an API that predates the field.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 9, 2026

addedOutput schema / properties / outcome

Added value: +{
+  "description": "`relying_party` when the request was created to wait for your outcome; null otherwise. Absent from an API that predates the field."
+}

addedOutput schema / properties / outcome_timeout_seconds

Added value: +{
+  "description": "The window set on the request, in seconds; null when it does not wait for an outcome. Absent from an API that predates the field."
+}

Changed1 schema field changedNov 2, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "action_context": {
+      "description": "The action the person is asked to authorize; null when the request carries none"
+    },
+    "action_type": {
+      "description": "Type of action for verification request or authorization"
+    },
+    "assets": {},
+    "callback_url": {
+      "description": "The webhook URL set on the request, if any"
+    },
+    "completed_at": {},
+    "computed_state": {
+      "description": "Additive machine-readable effective state: re-derives expiry from expires_at (never trusts the stored status). BOTH `is_expiring_soon` and `next_action` are role-aware — `next_action.role` says which side this envelope was computed for, and the two fields are consistent within it. Present only on authenticated owner/requester and recipient responses; absent on public/third-party surfaces."
+    },
+    "created_at": {},
+    "expires_at": {},
+    "id": {
+      "description": "MongoDB ObjectId"
+    },
+    "last_status": {
+      "description": "On timeout: the last non-terminal status observed, or null when none was"
+    },
+    "message": {
+      "description": "On timeout: what to do next (call the tool again with the same identifier)"
+    },
+    "partial_ok": {},
+    "progress": {},
+    "redirect_url": {},
+    "reference_id": {},
+    "status": {
+      "description": "\"pending\" when the wait ran out before a terminal state; otherwise the resource's own status"
+    },
+    "timeout_seconds": {
+      "description": "On timeout: the wait budget this call was given"
+    },
+    "updated_at": {},
+    "validity_requirement": {
+      "description": "Required proof freshness as set on the request (e.g. \"7d\"); null when none was set"
+    },
+    "verification_url": {
+      "description": "URL for the verification flow"
+    },
+    "waited_seconds": {
+      "description": "On timeout: seconds actually waited"
+    }
+  },
+  "type": "object"
+}

Changed1 schema field changedOct 26, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
First observedSep 19, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations only declare readOnlyHint=true, and the description is consistent with that while adding real behavioral detail: exponential backoff with 2s initial, 1.5x growth, 30s cap plus jitter, and the fact that an exhausted timeout returns status "pending" rather than failing. It also discloses the auth gate and warns that start_login does not unlock this tool. The one gap is that the approximate per-attempt request count or server-side load is not spelled out, but that is minor.

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?

Two short paragraphs, purpose front-loaded in the first sentence with backoff timing immediately after, then an access prerequisite. Nothing is padded, though the phrase 'start_login does NOT open this tool' is terse to the point of being cryptic about which flow actually grants access.

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, so return values need not be re-explained, and the description covers the remaining agent-critical facts: auth requirement, polling cadence, terminal states, and timeout semantics. Only the choice between this and sibling wait/fetch tools remains unstated.

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 100% and both parameters are documented in-schema, including the default of 50 and maximum of 300 for timeout_seconds and the reasoning about client timeouts. The description only reinforces that the same id must be reused across calls, adding little beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Poll a verification request') plus the exact terminal states (completed, expired, cancelled) that end the wait, which is more precise than a generic 'wait' description. It does not, however, distinguish itself from the many sibling wait_for_* tools or from get_verification_request, so an agent must infer that this one blocks while others simply fetch.

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

Usage Guidelines3/5

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

Gives useful in-call guidance — poll with the same id after a timeout, and keep timeout_seconds under the client's request timeout — and states the prerequisite of authenticating first. What is missing is explicit routing: no sentence says when to choose this over wait_for_verification or a one-shot get_verification_request, which matters given the crowded sibling set.

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

All Proof Holdings 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.