Cooper Email

Provision phone number

cooper_provision_phone_number

Destructive

Provision a US local number for an inbox. Requires auth. Free includes no numbers (HTTP 402). Starter caps at 3. Pro includes 3 and caps at 25. Each billable number is $3/month with 100 segments. With COOPER_SMS_BILLING=stripe the number is added to the Stripe subscription, prorated, before Cooper buys it. Otherwise billing.status is stub and this call does not charge. The number can receive SMS. Send returns 409 outbound_not_registered. Inputs: inbox_id (required), area_code or phone_number, idempotency_key (optional). Returns the phone number and billing.

Input Schema

Name	Required	Description
`inbox_id`	Yes	Inbox id (inb_…) that owns the phone number. Get it from cooper_list_inboxes.
`area_code`	No	Three-digit US area code to search, for example 415. Use this or phone_number.
`phone_number`	No	A specific available number in E.164, for example +14155550100. Use this or area_code.
`idempotency_key`	No	Optional key. Retrying with the same key returns the first result and does not buy a second number.

Output Schema

Name	Required	Description
`id`	No	Stable id of the returned object. Pass it to the matching get, update, or delete tool.
`e164`	No	The phone number in E.164.
`object`	No	Object type name, such as list, message, or thread.
`status`	No	active or released.
`billing`	No	Billing result for this number, such as {status}.
`inbox_id`	No	Inbox id (inb_…) this object belongs to. Null when it applies to every inbox.
`outbound`	No	Outbound SMS registration state. Sends fail with outbound_not_registered until it is ready.
`provider`	No	Carrier provider name.
`account_id`	No	Cooper account id (acct_…) that owns this object.
`created_at`	No	ISO-8601 time the object was created.
`number_type`	No	Number type, such as local.
`released_at`	No	ISO-8601 time the number was released, or null.
`capabilities`	No	What the number supports, such as sms and voice.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedNov 3, 2026

addedInput schema / properties / area_code / description

Added value: +"Three-digit US area code to search, for example 415. Use this or phone_number."

addedInput schema / properties / idempotency_key / description

Added value: +"Optional key. Retrying with the same key returns the first result and does not buy a second number."

addedInput schema / properties / inbox_id / description

Added value: +"Inbox id (inb_…) that owns the phone number. Get it from cooper_list_inboxes."

addedInput schema / properties / phone_number / description

Added value: +"A specific available number in E.164, for example +14155550100. Use this or area_code."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "description": "The new phone number and its billing.",
+  "properties": {
+    "account_id": {
+      "description": "Cooper account id (acct_…) that owns this object."
+    },
+    "billing": {
+      "description": "Billing result for this number, such as {status}."
+    },
+    "capabilities": {
+      "description": "What the number supports, such as sms and voice."
+    },
+    "created_at": {
+      "description": "ISO-8601 time the object was created."
+    },
+    "e164": {
+      "description": "The phone number in E.164."
+    },
+    "id": {
+      "description": "Stable id of the returned object. Pass it to the matching get, update, or delete tool."
+    },
+    "inbox_id": {
+      "description": "Inbox id (inb_…) this object belongs to. Null when it applies to every inbox."
+    },
+    "number_type": {
+      "description": "Number type, such as local."
+    },
+    "object": {
+      "description": "Object type name, such as list, message, or thread."
+    },
+    "outbound": {
+      "description": "Outbound SMS registration state. Sends fail with outbound_not_registered until it is ready."
+    },
+    "provider": {
+      "description": "Carrier provider name."
+    },
+    "released_at": {
+      "description": "ISO-8601 time the number was released, or null."
+    },
+    "status": {
+      "description": "active or released."
+    }
+  },
+  "type": "object"
+}

AddedOct 17, 2026

TDQS

A4.4/5.0

Behavior5/5

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

The annotations only declare the safety profile (destructive, non-idempotent, open-world); the description goes well beyond them with cost ($3/month, 100 segments), proration timing, the stub-billing no-charge path, plan limits, and the 402 failure mode. It also discloses that the number is SMS-receive-only and that outbound sends fail with 409 outbound_not_registered, which an agent cannot get from the structured fields.

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?

Pricing and plan caps come first, followed by billing mode, then inputs and return — a sensible front-load. It is dense but each line carries operational meaning, though the line about Send returning 409 outbound_not_registered drifts into another tool's behavior and could be trimmed.

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?

For a destructive, billable provisioning call, the description covers prerequisites, cost, plan ceilings, failure modes, and billing side effects, which is everything an agent needs before committing. An output schema exists, so the one-line return note is sufficient.

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% and the schema already explains inbox_id provenance, the area_code/phone_number either-or, and the idempotency retry guarantee. The description's 'Inputs:' list restates those parameters without adding format or syntax detail, so it lands at the baseline for a fully documented 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?

The opening sentence names a specific verb and resource ('Provision a US local number for an inbox'), which alone differentiates it from sibling reads like cooper_get_phone_number and the undo path cooper_release_phone_number. Plan caps, billing behavior, and the SMS receive capability are all attached to that same operation.

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?

It gives strong context for when this call is viable: auth required, Free plan returns HTTP 402, Starter caps at 3, Pro at 25, and billing only charges under COOPER_SMS_BILLING=stripe. What's missing is explicit routing guidance — it never says to use cooper_get_phone_number to look up existing numbers or cooper_release_phone_number to undo, so the agent must infer the sibling boundary.

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

All Cooper Email 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.