@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

wait_for_account_creation

Read-only

Polls an account-bootstrap session until the user completes verification, using exponential backoff. Call after create_account with the session ID and retry if the status is pending.

Instructions

Poll an account-bootstrap session until the user completes verification. Uses exponential backoff (2s initial, 1.5x, 30s max) with jitter.

Agent usage: Call this after create_account with the returned session id. Terminal states: "verified" (this server keeps the session for this connection; the user_id field in the terminal body identifies the authenticated user), "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. Works identically whether the underlying flow created a new User or logged in an existing one.

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.

Input Schema

Name	Required	Description	Default
`id`	Yes	Account session id from create_account
`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	Outcome of an account-session creation. `account_creation` means a new User will be written on verification. `login` indicates the submitted identity matched an existing User and the session will log them in.
`email`	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 PNG QR code for the deep link
`qr_text`	No	UTF-8 text QR for terminal/agent rendering
`user_id`	No
`sms_code`	No	Short code for SMS-channel reverse-OTP
`deep_link`	No
`created_at`	No
`email_sent`	No
`expires_at`	No
`email_error`	No
`last_status`	No	On timeout: the last non-terminal status observed, or null when none was
`sms_message`	No
`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.

Changed2 schema fields changedv1.7.2Nov 6, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "channel": {
+      "description": "Authentication channel"
+    },
+    "created_at": {},
+    "deep_link": {},
+    "email": {},
+    "email_error": {},
+    "email_sent": {},
+    "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 PNG QR code for the deep link"
+    },
+    "qr_text": {
+      "description": "UTF-8 text QR for terminal/agent rendering"
+    },
+    "sms_code": {
+      "description": "Short code for SMS-channel reverse-OTP"
+    },
+    "sms_message": {},
+    "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": {
+      "description": "Outcome of an account-session creation. `account_creation` means a new User will be written on verification. `login` indicates the submitted identity matched an existing User and the session will log them in."
+    },
+    "user_id": {},
+    "verified_at": {},
+    "waited_seconds": {
+      "description": "On timeout: seconds actually waited"
+    }
+  },
+  "type": "object"
+}

First observedv1.1.0Sep 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the readOnlyHint annotation: it discloses the polling cadence (2s initial, 1.5x growth, 30s cap, jitter), the semantic difference between the three terminal states, that the server keeps the session bound to this connection, and that the flow behaves identically for new vs. existing users. No contradiction with readOnlyHint — the tool waits and reads, it does not itself mutate.

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 verb and the backoff profile, then the agent-usage paragraph, then the caveat — a sensible ordering. The final paragraph about showing the link in reply text is slightly tangential to invocation but does earn its place as a precondition; overall it is denser than most descriptions but nearly every sentence carries information.

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?

An output schema exists so return shape needn't be re-explained, yet the description still names the terminal statuses and the `user_id` field that identifies the authenticated user. Combined with the timeout/pending retry semantics, an agent has everything needed to call this in a loop and interpret every outcome.

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 coverage is 100% and the schema already documents both `id` and `timeout_seconds`, including the 50s default, 600s max, client-timeout caveat and the "call again with the same identifier" behavior on pending. The description reinforces the reuse-the-same-id rule for retries but adds no new meaning about parameter format or values, so the baseline 3 applies.

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 the specific verb (poll), the specific resource (account-bootstrap session) and the terminating condition (user completes verification), which cleanly separates it from wait_for_login, wait_for_session and wait_for_verification. The follow-up sentence "Call this after create_account with the returned session id" pins it into the flow where an agent would otherwise hesitate between several wait_* 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?

Gives an explicit trigger (after create_account), an explicit retry rule (status "pending" means call again with the same id), and enumerated terminal states with a prescribed agent action for the tricky one ("completed_elsewhere" → tell the user the browser is signed in but this connection never will be). It also adds a precondition: surface the link/SMS/inbox note in assistant text before calling.

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

Deploy Server