Skip to main content
Glama

Reuse a verification number

reuse_number
Destructive

Reuse an earlier verification number to receive a new SMS code. Free when permitted; paid reuse requires price approval and auto-refunds if the number is unavailable.

Instructions

Receive another SMS on the number of an earlier verification (ver_...). Free reuse: when allow_reuse is true. Paid reuse (paid=true): when allow_paid_reuse is true; charges paid_reuse_price_cents, refunded automatically if the number is no longer available, and requires max_price_cents (that price, shown to and approved by the user) and Buy access. Check both flags and the price with get_rental first, then call get_rental with wait_seconds for the new code.

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": {
      "rental_id": "<rental_id>"
    },
    "name": "reuse_number"
  }
}

Input Schema

NameRequiredDescriptionDefault
paidNo
rental_idYesver_... id of an earlier verification
max_price_centsNoRequired when paid=true: the paid_reuse_price_cents you showed the user and they approved, in US cents. Refused uncharged if the price is higher.

Output Schema

NameRequiredDescriptionDefault
verificationYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.0.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. Changed2 schema fields changedv1.2.1
    • addedInput schema / properties / max_price_cents
      Added value: +{
      +  "description": "Required when paid=true: the paid_reuse_price_cents you showed the user and they approved, in US cents. Refused uncharged if the price is higher.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 1000000,
      +  "type": "integer"
      +}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": {},
      +  "properties": {
      +    "verification": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "allow_paid_reuse": {
      +          "type": "boolean"
      +        },
      +        "allow_reuse": {
      +          "type": "boolean"
      +        },
      +        "can_cancel": {
      +          "type": "boolean"
      +        },
      +        "charged_price_cents": {
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        "charged_reuse_cents": {
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        "code": {
      +          "type": "string"
      +        },
      +        "code_received_at": {
      +          "type": "string"
      +        },
      +        "created_at": {
      +          "type": "string"
      +        },
      +        "display_id": {
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "expires_at": {
      +          "type": "string"
      +        },
      +        "id": {
      +          "type": "string"
      +        },
      +        "paid_reuse_price_cents": {
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        "phone_number": {
      +          "type": "string"
      +        },
      +        "refunded_cents": {
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        "reuse_counter": {
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        "service_id": {
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "service_name": {
      +          "type": "string"
      +        },
      +        "status": {
      +          "enum": [
      +            "waiting_for_code",
      +            "code_received",
      +            "cancelled",
      +            "expired",
      +            "failed"
      +          ],
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "id",
      +        "status",
      +        "phone_number",
      +        "service_id",
      +        "service_name",
      +        "charged_price_cents",
      +        "expires_at",
      +        "can_cancel",
      +        "created_at",
      +        "reuse_counter",
      +        "allow_reuse",
      +        "allow_paid_reuse",
      +        "paid_reuse_price_cents"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "verification"
      +  ],
      +  "type": "object"
      +}
  3. Changed2 schema fields changedv1.1.8
    • changedInput schema / properties / rental_id / description
      Previous value: -"ver_xxx from a verification"New value: +"ver_... id of an earlier verification"
    • addedInput schema / properties / rental_id / pattern
      Added value: +"^(?:ver_[A-Za-z0-9_-]{1,64})$"
  4. First observedv1.1.3

TDQS

A4.2/5.0
Behavior4/5

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

Adds real behavior beyond the annotations: money is charged via paid_reuse_price_cents, auto-refunded if the number is unavailable, and max_price_cents must be a user-approved price with over-cap requests refused uncharged. That said, it never says what happens to the existing rental state or prior messages, which matters given destructiveHint=true and idempotentHint=false.

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 core action, then organizes the free path, the paid path, and the recommended call sequence in a compact sequence. The paid clause is a long run-on with several stacked requirements, mildly taxing on first read.

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?

Covers the prerequisite checks, the billing guardrails, and the follow-up step needed to actually obtain the code, and an output schema exists so return values need no explanation. Only the effect on the existing rental and its prior messages is left unstated.

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 schema documents rental_id and max_price_cents but leaves the `paid` boolean undocumented; the description compensates by explaining that paid=true triggers the priced path gated on allow_paid_reuse. It reinforces the 'approved price' semantics of max_price_cents rather than adding new detail there.

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?

Names a specific verb and resource: receiving another SMS on the number of an earlier verification (ver_...), which pins the input domain to a prior verification id. It does not explicitly contrast with the closer sibling re_rent_rental, so an agent must infer the boundary between reusing a verification number and re-renting a rental.

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?

States the exact gating conditions: free reuse requires allow_reuse=true, paid reuse requires allow_paid_reuse=true plus Buy access, and it directs the agent to check both flags and the price via get_rental first. It also closes the loop with the follow-up call (get_rental with wait_seconds) to fetch the new code.

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