Skip to main content
Glama
Sign In
@proof-holdings/mcp-server

@proof-holdings/mcp-server

Official
by ProofHoldings
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

wait_for_chat_id_discovery

Read-only

Polls a Telegram discovery token until the user opens the bot link, returning when the chat ID is found or the token expires so you can configure human-in-the-loop approval.

Instructions

Poll a chat ID discovery token until the user interacts with the Telegram bot. Uses exponential backoff (2s initial, 1.5x, 30s max) with jitter.

Agent usage: Call this after create_chat_id_discovery. Present the discovery response's deep_link with render_auth_link first, then poll with the returned token. Terminal states: "completed" (chat_id discovered — use it when creating a HITL config with a Telegram channel), "expired". While "pending", the user has not yet opened the Telegram link.

The user does not see tool results — most clients fold them away, render_auth_link's output included. Before you wait or poll, put what the user must act on into your own reply text: the link itself (not a sentence announcing it), the SMS text and number, or a note to check their inbox.

ACCESS: needs a Proof account. Set PROOF_API_KEY and restart this server, then call this tool again. start_login does NOT open this tool.

Input Schema

NameRequiredDescriptionDefault
tokenYesDiscovery token from create_chat_id_discovery
timeout_secondsNoMaximum 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

NameRequiredDescriptionDefault
statusNo"pending" when the wait ran out before a terminal state; otherwise the resource's own status
chat_idNo
messageNoOn timeout: what to do next (call the tool again with the same identifier)
last_statusNoOn timeout: the last non-terminal status observed, or null when none was
waited_secondsNoOn timeout: seconds actually waited
timeout_secondsNoOn timeout: the wait budget this call was given

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.7.2
    • removedInput schema / additionalProperties
      Removed value: -false
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "chat_id": {},
+    "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)"
+    },
+    "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"
+    },
+    "waited_seconds": {
+      "description": "On timeout: seconds actually waited"
+    }
+  },
+  "type": "object"
+}
  2. First observedv1.1.0

TDQS

A4.1/5.0
Behavior5/5

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

Beyond the readOnlyHint annotation, it discloses the backoff profile (2s, 1.5x, 30s max, jitter), the pending-on-timeout behavior, and the fact that clients fold away tool output so the agent must surface the link or code in its own reply. That is exactly the operational context annotations cannot carry.

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?

The purpose and polling behavior come first, followed by the usage recipe and terminal states. The ACCESS paragraph is somewhat dense and its 'start_login does NOT open this tool' line is tangential, but overall every section carries actionable content.

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 two-parameter polling tool with an output schema, the description covers prerequisites, sequencing, terminal states, timeout retry behavior and the proof-account requirement — nothing an agent needs to call it correctly is missing.

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 both parameters are already documented in the schema, including the timeout rationale. The description only adds token provenance ('returned token' from the create call), which is largely duplicative, so baseline 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?

The description states a specific verb and resource — polling a chat ID discovery token until the Telegram user interacts — and names the creating sibling create_chat_id_discovery. It does not distinguish itself from the close sibling poll_chat_id_discovery, so the agent must infer which of the two to call.

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?

It gives an explicit sequence (create_chat_id_discovery, then render_auth_link with the deep_link, then poll with the returned token) and names the terminal states completed/expired and the pending meaning. The only gap is no guidance on when to use this versus poll_chat_id_discovery.

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

Deploy Server

Other Tools