Proof Holdings

start_add_phone

Start adding a new phone number by reverse OTP: the user starts the exchange themselves and nothing is sent before they do; the response's instructions field says what they do (on telegram the bot then asks them to tap a button that shares their number). Returns a session ID; on telegram/whatsapp also deep_link, qr_code (base64 PNG) and qr_text (UTF-8 text QR), and on sms sms_message and sms_dids (one entry per region; a region with no number configured has an empty did) with no deep_link.

Agent usage: on telegram/whatsapp pass deep_link to render_auth_link for the link and a QR code. On sms there is no deep_link — show sms_message and a number from an sms_dids entry whose did is non-empty. Never hand a qr_text to a link renderer — it is a link already rendered as QR art. Then poll get_add_phone_status with the session ID.

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. Authenticate this client (Claude Code: /mcp → Authenticate), or sign in with start_login — a session opens this tool — then call this tool again.

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": {
      "channel": "<channel>"
    },
    "name": "start_add_phone"
  }
}

Input Schema

Name	Required	Description	Default
`channel`	Yes	Channel for phone verification

Output Schema

Name	Required	Description
`status`	Yes
`channel`	Yes
`qr_code`	No	Base64-encoded PNG QR code for `deep_link`
`qr_text`	No	UTF-8 text QR for `deep_link`, for terminal/agent rendering
`sms_code`	No	The short code the person texts (`sms` only)
`sms_dids`	No	Our SMS numbers, one entry per region and always all three. A region with no number configured carries an empty `did` and no QR code.
`deep_link`	No	Opens Telegram or WhatsApp with what the person sends (`telegram`, `whatsapp`)
`expires_at`	Yes
`session_id`	Yes
`sms_message`	No	The message to send (`sms` only)
`instructions`	Yes	One line telling the person what to do

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": {},
+  "description": "A phone-add session: the person proves the number by sending from it over `channel`",
+  "properties": {
+    "channel": {
+      "type": "string"
+    },
+    "deep_link": {
+      "description": "Opens Telegram or WhatsApp with what the person sends (`telegram`, `whatsapp`)",
+      "type": "string"
+    },
+    "expires_at": {
+      "type": "string"
+    },
+    "instructions": {
+      "description": "One line telling the person what to do",
+      "type": "string"
+    },
+    "qr_code": {
+      "description": "Base64-encoded PNG QR code for `deep_link`",
+      "type": "string"
+    },
+    "qr_text": {
+      "description": "UTF-8 text QR for `deep_link`, for terminal/agent rendering",
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "sms_code": {
+      "description": "The short code the person texts (`sms` only)",
+      "type": "string"
+    },
+    "sms_dids": {
+      "additionalProperties": {},
+      "description": "Our SMS numbers, one entry per region and always all three. A region with no number configured carries an empty `did` and no QR code.",
+      "properties": {
+        "americas": {
+          "additionalProperties": {},
+          "properties": {
+            "did": {
+              "type": "string"
+            },
+            "flag": {
+              "type": "string"
+            },
+            "label": {
+              "type": "string"
+            },
+            "qr_code": {
+              "type": "string"
+            },
+            "qr_text": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "did",
+            "label",
+            "flag"
+          ],
+          "type": "object"
+        },
+        "europe": {
+          "additionalProperties": {},
+          "properties": {
+            "did": {
+              "type": "string"
+            },
+            "flag": {
+              "type": "string"
+            },
+            "label": {
+              "type": "string"
+            },
+            "qr_code": {
+              "type": "string"
+            },
+            "qr_text": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "did",
+            "label",
+            "flag"
+          ],
+          "type": "object"
+        },
+        "israel": {
+          "additionalProperties": {},
+          "properties": {
+            "did": {
+              "type": "string"
+            },
+            "flag": {
+              "type": "string"
+            },
+            "label": {
+              "type": "string"
+            },
+            "qr_code": {
+              "type": "string"
+            },
+            "qr_text": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "did",
+            "label",
+            "flag"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "americas",
+        "europe",
+        "israel"
+      ],
+      "type": "object"
+    },
+    "sms_message": {
+      "description": "The message to send (`sms` only)",
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "session_id",
+    "channel",
+    "status",
+    "expires_at",
+    "instructions"
+  ],
+  "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 say readOnlyHint=false / destructiveHint=false; the description adds far more — the exchange is user-initiated with nothing sent first, the exact response fields per channel (deep_link, qr_code base64 PNG, qr_text, sms_message, sms_dids with possibly empty did), auth requirements and the start_login fallback, and the fact that clients fold tool results away from the user.

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 mechanism, then agent usage, then access — a sensible ordering with no filler sentences. It is long for a one-parameter tool and repeats the channel-return mapping in both the return-value paragraph and the usage paragraph, which costs some tightness.

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?

Despite an output schema existing, the description still tells the agent what to do with each field, what precondition auth is needed, and the required next call (get_add_phone_status). The added warning that users never see tool output closes the one gap that would otherwise cause a silent dead-end flow.

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?

The single channel parameter already has 100% schema coverage and an enum, so the baseline is 3; the description goes further by explaining what each enum value changes in the response (deep_link/qr on telegram/whatsapp vs sms_message/sms_dids on sms). It does not, however, discuss whether channel choice has any downstream constraint beyond output shape.

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 specific verb and resource ("Start adding a new phone number") and immediately defines the reverse-OTP mechanism, which distinguishes it from siblings like start_add_email or request-based verification flows. It also spells out what the call does NOT do ("nothing is sent before they do").

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?

Explicit per-channel routing: pass deep_link to render_auth_link on telegram/whatsapp, show sms_message plus a non-empty did on sms, then poll get_add_phone_status with the session ID. It even names an anti-pattern ("Never hand a qr_text to a link renderer") and gives the pre-poll UX requirement.

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.