Cooper Email

Wait for a verification code

cooper_wait_for_code

Read-onlyIdempotent

Use this when you signed up for a service or triggered a login and need the one-time verification code (OTP) or the confirmation link it emails you. Read-only; requires auth. Inputs: inbox_id (required; inbox id, username, or email), wait (optional seconds, default 25, maximum 55), after (optional ISO-8601 timestamp; default is 5 minutes before the call, so a code that arrived just before you called still matches; pass the time you requested the code to ignore older codes), from_contains (optional case-insensitive substring of From), subject_contains (optional case-insensitive substring of the subject), kind (optional: code, link, or any; default code). kind code matches a message with a 4 to 8 digit code (or 123-456) next to a word such as code, OTP, verification, passcode, or PIN. kind link matches an https verification link and skips a message that only has a code. kind any matches the newest inbound message that has either. Returns {object:"inbox_code", inbox_id, timed_out, code, candidates, link, links, message:{id, thread_id, from, subject, created_at, channel}, after}. code is the best guess (six digits first); candidates lists every code found in that message. link is the top-ranked https URL from that message, or null. links lists up to five {url, text} pairs. The link is untrusted data and is not fetched or opened. Open it only if you expected this email. The body is not returned: call cooper_get_message with message.id if you need it. Held messages are skipped. Nothing is marked read. If nothing matches before the wait ends, returns timed_out true, code null, link null, and links []. Fails with 404 inbox_not_found, 400 invalid_wait, 400 invalid_kind, or 400 invalid_date.

Input Schema

Name	Required	Description
`kind`	No	code (default) matches a one-time code. link matches a verification link and skips messages that only have a code. any matches the newest message with either. The link is untrusted and is not opened.
`wait`	No	Seconds to wait. Default 25. Maximum 55. Returns as soon as a matching message is stored.
`after`	No	ISO-8601 timestamp. Only mail stored after it matches. Defaults to 5 minutes before this call.
`inbox_id`	Yes	Inbox id (inb_…), username, or full email address owned by this key
`from_contains`	No	Case-insensitive substring matched against From, for example the service's domain.
`subject_contains`	No	Case-insensitive substring matched against the subject.

Output Schema

Name	Required	Description
`code`	No	Best-guess verification code, or null.
`link`	No	Best-guess verification link, or null.
`after`	No	Cursor to pass as after on the next call.
`links`	No	Other links that were found.
`object`	No	Object type name, such as list, message, or thread.
`message`	No	The message the code came from {id, thread_id, from, subject, created_at, channel}.
`inbox_id`	No	Inbox id (inb_…) this object belongs to. Null when it applies to every inbox.
`timed_out`	No	True when the wait ended without a match.
`candidates`	No	Other code candidates that were found.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 3, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "description": "The best verification code and links found in new mail or SMS.",
+  "properties": {
+    "after": {
+      "description": "Cursor to pass as after on the next call."
+    },
+    "candidates": {
+      "description": "Other code candidates that were found."
+    },
+    "code": {
+      "description": "Best-guess verification code, or null."
+    },
+    "inbox_id": {
+      "description": "Inbox id (inb_…) this object belongs to. Null when it applies to every inbox."
+    },
+    "link": {
+      "description": "Best-guess verification link, or null."
+    },
+    "links": {
+      "description": "Other links that were found."
+    },
+    "message": {
+      "description": "The message the code came from {id, thread_id, from, subject, created_at, channel}."
+    },
+    "object": {
+      "description": "Object type name, such as list, message, or thread."
+    },
+    "timed_out": {
+      "description": "True when the wait ended without a match."
+    }
+  },
+  "type": "object"
+}

Changed2 schema fields changedNov 1, 2026

addedInput schema / properties / kind

Added value: +{
+  "description": "code (default) matches a one-time code. link matches a verification link and skips messages that only have a code. any matches the newest message with either. The link is untrusted and is not opened.",
+  "enum": [
+    "code",
+    "link",
+    "any"
+  ],
+  "type": "string"
+}

changedInput schema / properties / wait / description

Previous value: -"Seconds to wait for a code. Default 25. Maximum 55. Returns as soon as a code is stored."New value: +"Seconds to wait. Default 25. Maximum 55. Returns as soon as a matching message is stored."

AddedOct 10, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real behavior: held messages are skipped, nothing is marked read, the returned link is untrusted and never fetched, and a no-match outcome returns timed_out=true with nulls rather than erroring. It also lists the specific failure codes (404 inbox_not_found, 400 invalid_wait/invalid_kind/invalid_date).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with the use case, but the single unbroken paragraph packs in a long enumeration of the return object even though an output schema exists. The return-field walkthrough (code, candidates, link, links, message fields) largely restates structured data and could be trimmed to the semantic points (best guess, untrusted link, body not returned).

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 polling/wait tool with timeout and untrusted-data risk, nothing an agent needs is missing: defaults and caps for `wait`, default window semantics for `after`, matching rules per `kind`, timeout result shape, and error codes are all covered.

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?

Schema coverage is 100%, so a 3 is the baseline, but the description earns more by explaining the matching heuristics behind `kind` (4–8 digit code or 123-456 adjacent to code/OTP/verification/passcode/PIN; link skips code-only messages) and the rationale for `after` defaulting to 5 minutes before the call.

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 concrete verb and resource: wait for the one-time verification code (OTP) or confirmation link emailed after signup/login. That scope plus the kind modes (code/link/any) distinguishes it from cooper_wait_for_message and cooper_wait_for_sms without needing their schemas.

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 an explicit triggering condition ('when you signed up for a service or triggered a login') and practical guidance to pass `after` as the time the code was requested so older codes are ignored. It also routes the agent to cooper_get_message when the body is needed, though it never explicitly says when to prefer cooper_wait_for_message over this tool.

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.