@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

list_incoming_requests

Read-only

Lists incoming verification requests where the authenticated user is the subject, helping you review and respond to pending Proof requests.

Instructions

List incoming verification requests where the authenticated user is the subject.

ACCESS: needs a Proof account. Set PROOF_API_KEY and restart this server, or sign in with start_login — a session opens this tool — then call this tool again.

Input Schema

Name	Required	Description	Default
No arguments

Output Schema

Name	Required	Description	Default
`data`	Yes
`pagination`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.7.2Nov 6, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "description": "The verification requests the account was asked to complete, newest first",
+  "properties": {
+    "data": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "action_type": {
+            "type": "string"
+          },
+          "assets": {
+            "items": {
+              "additionalProperties": {},
+              "properties": {
+                "identifier": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "status": {
+                  "type": "string"
+                },
+                "type": {
+                  "type": "string"
+                },
+                "verified_at": {
+                  "type": "string"
+                },
+                "verified_channel": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "verified_identifier": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              },
+              "required": [
+                "type",
+                "identifier",
+                "status",
+                "verified_identifier",
+                "verified_channel"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "completed_at": {
+            "type": "string"
+          },
+          "computed_state": {
+            "additionalProperties": {},
+            "properties": {
+              "is_expiring_soon": {
+                "type": "boolean"
+              },
+              "next_action": {
+                "additionalProperties": {},
+                "properties": {
+                  "code": {
+                    "type": "string"
+                  },
+                  "label": {
+                    "type": "string"
+                  },
+                  "role": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "code",
+                  "role",
+                  "label"
+                ],
+                "type": "object"
+              },
+              "status": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "status",
+              "is_expiring_soon",
+              "next_action"
+            ],
+            "type": "object"
+          },
+          "created_at": {
+            "type": "string"
+          },
+          "expires_at": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          },
+          "progress": {
+            "additionalProperties": {},
+            "properties": {
+              "completed": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "completed_required": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "optional": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "required": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "total": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              }
+            },
+            "required": [
+              "completed",
+              "completed_required",
+              "required",
+              "optional",
+              "total"
+            ],
+            "type": "object"
+          },
+          "reference_id": {
+            "type": "string"
+          },
+          "requester": {
+            "additionalProperties": {},
+            "properties": {
+              "business_name": {
+                "type": "string"
+              },
+              "logo_url": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "status": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "status",
+          "computed_state",
+          "action_type",
+          "assets",
+          "progress",
+          "expires_at",
+          "created_at"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "pagination": {
+      "additionalProperties": {},
+      "properties": {
+        "limit": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "offset": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "total": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "total",
+        "limit",
+        "offset"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "data",
+    "pagination"
+  ],
+  "type": "object"
+}

First observedv1.1.0Sep 9, 2026

TDQS

A3.8/5.0

Behavior4/5

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

readOnlyHint=true already covers the safety profile, but the description adds information the annotations cannot: authentication is required and how to satisfy it, plus the fact that the call must be repeated after a session opens. It says nothing about result volume or ordering, though an output schema exists to carry the return shape.

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?

Two short, front-loaded sentences: scope first, then access. The access sentence is slightly awkward ('a session opens this tool') but every clause carries operational value and nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless read-only list tool with an output schema, the description covers the two things an agent cannot derive from structured fields: the subject-scoped filter and the auth requirement. The remaining gap is explicit disambiguation from the near-identical list_my_requests and list_verification_requests siblings.

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 tool takes no parameters, so there is no parameter semantics to explain; the empty object schema is self-evident. The baseline for zero parameters applies, with no contradicting or misleading text.

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 gives a specific verb and resource ('List incoming verification requests') and adds a real scoping qualifier — 'where the authenticated user is the subject' — which separates it from the many other list_* verification tools. It stops short of naming the closest alternatives (list_my_requests, list_verification_requests), so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states a concrete prerequisite (a Proof account via PROOF_API_KEY or start_login) and tells the agent to retry after authenticating, which is genuine when-to-use context. However, it never says when to prefer this over list_my_requests or list_verification_requests, which is the main selection risk given the crowded sibling set.

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

Deploy Server