Proof Holdings

wait_for_login

Read-only

Poll a login session until the user completes authentication. Uses exponential backoff (2s initial, 1.5x, 30s max) with jitter.

Agent usage: Call this after start_login with the returned session ID. Terminal states: "verified" (login succeeded — this server keeps the session for this connection and signs your own account records with it: emails, phones, domains, API keys, 2FA, DNS credentials, verification requests, your public profile's username and proof list), "failed", "expired", "completed_elsewhere" (email only: the user pressed "Sign in here" on the email link's page, so the browser they clicked from is signed in and this connection never will be — tell them so, and start a new login if this connection still needs one). A result with status "pending" means the wait ran out before the user finished — call this tool again with the same id.

Before calling this for a challenge you created, make sure your reply text already shows the user what to act on — the link itself, the SMS text and number, or a note to check their inbox; a link that appeared only in a tool result is one they never saw.

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_login"
  }
}

Input Schema

Name	Required	Description	Default
`id`	Yes	Auth session ID from start_login
`timeout_seconds`	No	Maximum wait time in seconds (default: 50, max: 600). 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
`type`	No
`status`	No	"pending" when the wait ran out before a terminal state; otherwise the resource's own status
`channel`	No	Authentication channel
`message`	No	On timeout: what to do next (call the tool again with the same identifier)
`qr_code`	No	Base64-encoded QR code image
`qr_text`	No	UTF-8 text representation of the QR code for terminal/agent display
`user_id`	No
`deep_link`	No
`expires_at`	No
`last_status`	No	On timeout: the last non-terminal status observed, or null when none was
`verified_at`	No
`instructions`	No
`waited_seconds`	No	On timeout: seconds actually waited
`timeout_seconds`	No	On timeout: the wait budget this call was given

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 2, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "channel": {
+      "description": "Authentication channel"
+    },
+    "deep_link": {},
+    "expires_at": {},
+    "id": {},
+    "instructions": {},
+    "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)"
+    },
+    "qr_code": {
+      "description": "Base64-encoded QR code image"
+    },
+    "qr_text": {
+      "description": "UTF-8 text representation of the QR code for terminal/agent display"
+    },
+    "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"
+    },
+    "type": {},
+    "user_id": {},
+    "verified_at": {},
+    "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

A4.8/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=true; the description goes far beyond by disclosing the backoff schedule (2s initial, 1.5x, 30s max, jitter) and enumerating all four terminal states with consequences. The "completed_elsewhere" explanation (email-only, browser becomes signed in, this connection never will, start a new login) is exactly the kind of non-obvious behavioral context an agent cannot infer elsewhere.

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 purpose and backoff, then a labelled "Agent usage:" block that keeps the guidance scannable. The terminal-state sentence is dense and parenthetical, but every clause carries distinct information (state name, meaning, required agent action).

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?

Covers the full lifecycle an agent needs: prerequisite tool, polling/retry semantics, all terminal outcomes and what to do for each, and the user-facing side effect of showing the challenge link. With an output schema present, no return-shape explanation is required and none is missing.

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 both parameters are already documented. The description still adds value by framing the id as reusable across retries and explaining that a wait exceeding the client's request timeout surfaces as "pending" rather than a failure — reinforcing the schema's timeout note with operational intent.

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?

Opens with a specific verb+resource: "Poll a login session until the user completes authentication." It is clearly distinguishable from the many sibling waiters (wait_for_2fa, wait_for_session, wait_for_verification) because it names the login-session object and ties it to start_login's returned ID.

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?

Explicitly states the sequencing ("Call this after start_login with the returned session ID") and gives a retry rule: a "pending" result means call again with the same id. It also adds a pre-call obligation — surface the link/SMS/inbox note in the reply text before polling — which is real routing guidance, not filler.

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.