lookup

Spam Check

vri_spam_check

Spam/scam/robocall reputation for one North American phone number, with an explainable risk block: the verdict, a confidence band, and the individual reasons behind it (complaint volume and recency, complaint category, community reports, line type, recent porting). Live customer keys spend balance. Repeating a call can charge again; reuse a stable request_id with identical arguments for a safe retry. Use max_cost to cap the quote. Use a test key for integration tests.

Input Schema

TableJSON Schema

Name	Required	Description
`max_cost`	No	Maximum quoted cost in USD; rejected before lookup if exceeded.
`request_id`	No	Stable unique ID for this operation. Reuse with identical arguments to retrieve its receipt without another charge.
`phone_number`	Yes	US/Canada number, any common format

Output Schema

TableJSON Schema

Name	Required	Description
`data`	No
`risk`	No	Explainable spam/risk verdict: WHY the number is flagged (or not), with an honest confidence band. A clean verdict means "nothing found against it", never "verified safe".
`status`	No
`phone_number`	No
`total_charged`	No
`partial_results`	No
`products_available`	No
`products_unavailable`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedOct 6, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / max_cost

Added value: +{
+  "description": "Maximum quoted cost in USD; rejected before lookup if exceeded.",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / request_id

Added value: +{
+  "description": "Stable unique ID for this operation. Reuse with identical arguments to retrieve its receipt without another charge.",
+  "type": "string"
+}

addedOutput schema / properties / data

Added value: +{
+  "additionalProperties": true,
+  "type": "object"
+}

removedOutput schema / properties / is_spam

Removed value: -{
-  "description": "True if flagged spam/scam/robocall",
-  "type": "boolean"
-}

addedOutput schema / properties / partial_results
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / products_available

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / products_unavailable

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

removedOutput schema / properties / spam_type

Removed value: -{
-  "description": "SCAM, ROBOCALL, or null when clean",
-  "type": [
-    "string",
-    "null"
-  ]
-}

addedOutput schema / properties / status

Added value: +{
+  "enum": [
+    "success",
+    "partial",
+    "failed",
+    "pending"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / total_charged
```
Added value: +{
+  "type": "number"
+}
```

Changed1 schema field changedSep 6, 2026

addedOutput schema / properties / risk

Added value: +{
+  "additionalProperties": true,
+  "description": "Explainable spam/risk verdict: WHY the number is flagged (or not), with an honest confidence band. A clean verdict means \"nothing found against it\", never \"verified safe\".",
+  "properties": {
+    "confidence": {
+      "description": "How much weight the evidence actually carries",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "type": "string"
+    },
+    "confidence_note": {
+      "description": "One plain sentence explaining the band",
+      "type": "string"
+    },
+    "reasons": {
+      "description": "Individual pieces of evidence behind the verdict",
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "code": {
+            "description": "provider_flag, ftc_complaints, complaint_category, community_reports, line_type_voip, recently_ported, no_complaints",
+            "type": "string"
+          },
+          "signal": {
+            "enum": [
+              "negative",
+              "positive",
+              "context"
+            ],
+            "type": "string"
+          },
+          "text": {
+            "description": "Human-readable evidence",
+            "type": "string"
+          },
+          "weight": {
+            "enum": [
+              "strong",
+              "moderate",
+              "weak"
+            ],
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "verdict": {
+      "description": "unknown = no reputation data was read for this number",
+      "enum": [
+        "scam",
+        "robocall",
+        "reported",
+        "clean",
+        "unknown"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedSep 5, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Goes well beyond the annotations: annotations say idempotentHint=false and nothing about cost, while the description discloses that live keys spend balance, that repeat calls can charge again, and that reusing a request_id with identical arguments yields a safe no-charge retry. It also documents the max_cost cap and the explainable risk block.

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-loads the purpose, then packs billing/retry/cost/test-key guidance into four short sentences with no filler. Slightly telegraphic and dense, but every sentence carries actionable 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 values need no further explanation; the description nonetheless summarizes the risk block. With billing, retry, cost-cap, and test-key behavior all covered, an agent has everything needed to invoke it correctly.

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%, so the schema already documents all three parameters, including the request_id retry semantics and the max_cost rejection rule. The description largely restates that (cost cap, safe retry) rather than adding new syntax or format detail, 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 a specific verb+resource and scope: 'Spam/scam/robocall reputation for one North American phone number.' The 'one number' scoping and the named `risk` output distinguish it from bulk/other lookup siblings without needing to open a schema.

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?

Gives clear operating context — live keys spend balance, test keys for integration tests, max_cost to cap the quote — but never explicitly says when to prefer this over vri_number_lookup, vri_bulk_lookup, or vri_quote. Context is clear; alternatives are left to inference.

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

All lookup 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.