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

@proof-holdings/mcp-server

Official
by ProofHoldings
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

submit_verification_code

Submit an OTP or challenge code for a pending email or domain verification where the code was delivered out-of-band. Completes the check; use trigger_verification for other channels.

Instructions

Submit an OTP/challenge code for a pending verification. Accepted ONLY where we delivered the code out-of-band to the party being verified: type "email", and type "domain" with channel "email". Any other pair answers 400 unsupported_for_type and completes elsewhere — use trigger_verification (POST /verifications/:id/verify) for a domain over dns/http/auto; a phone completes when the code reaches us FROM that number; social completes through its OAuth callback; a telegram_bot is already verified at creation.

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
idYesVerification ID
codeYesThe OTP or challenge code to submit

Output Schema

NameRequiredDescriptionDefault
idYesMongoDB ObjectId
proofNoPresent when the code was right
statusYesCurrent status of the verification
messageNoPresent when the code was wrong (`pending`) or the attempts are used up (`failed`)
attemptsYesCodes submitted so far, this one included
verified_atNoPresent when the code was right
max_attemptsYes
attempts_remainingNoPresent while `pending`

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": {},
+  "description": "Result of submitting the code we emailed",
+  "properties": {
+    "attempts": {
+      "description": "Codes submitted so far, this one included",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "attempts_remaining": {
+      "description": "Present while `pending`",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "id": {
+      "description": "MongoDB ObjectId",
+      "type": "string"
+    },
+    "max_attempts": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "message": {
+      "description": "Present when the code was wrong (`pending`) or the attempts are used up (`failed`)",
+      "type": "string"
+    },
+    "proof": {
+      "additionalProperties": {},
+      "description": "Present when the code was right",
+      "properties": {
+        "expires_at": {
+          "type": "string"
+        },
+        "token": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "token",
+        "expires_at"
+      ],
+      "type": "object"
+    },
+    "status": {
+      "description": "Current status of the verification",
+      "type": "string"
+    },
+    "verified_at": {
+      "description": "Present when the code was right",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "status",
+    "attempts",
+    "max_attempts"
+  ],
+  "type": "object"
+}
  2. First observedv1.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that: the 400 unsupported_for_type failure mode for unsupported pairs and the exact access precondition (Proof account, PROOF_API_KEY set plus server restart). It also preempts a plausible wrong assumption by noting start_login does NOT unlock this tool. Nothing contradicts the annotations.

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 eligibility constraint is front-loaded, then the routing table for excluded cases, then the access note — a sensible order with dense, non-repeating sentences. It is long for a two-parameter tool, but nearly every clause conveys a distinct constraint; the ACCESS paragraph is useful though slightly tangential to invocation.

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?

With an output schema present, return values need no explanation, and the description covers the remaining gaps an agent would hit: auth setup, unsupported-input behavior, and the alternative path for every excluded verification type. Complete for this tool's complexity.

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% for both required parameters (id, code), so the schema carries parameter meaning and the baseline of 3 applies. The description's discussion of 'type' and 'channel' pairs is routing context rather than semantics for id or code, so it adds little parameter-level detail beyond the schema.

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: 'Submit an OTP/challenge code for a pending verification.' It immediately constrains the scope to conditions where the code was delivered out-of-band, which separates it from the many other verification tools, and names trigger_verification as the different sibling.

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 explicit when-to-use ('ONLY where we delivered the code out-of-band... type "email", and type "domain" with channel "email"') and when-not, enumerating each excluded case with the mechanism that handles it instead (trigger_verification for dns/http/auto, inbound phone submission, social OAuth callback, telegram_bot already verified). No inference is left to the agent.

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