Cooper Email

List refused API calls

cooper_list_request_refusals

Read-onlyIdempotent

Use this when a Cooper call failed and you need to see recent refusals and their error codes. Read-only; requires auth. Inputs: status (optional HTTP 4xx code), code (optional error code), api_key_id (optional), inbox_id (optional inbox id), since (optional ISO-8601 timestamp), limit (optional, 1 to 100, default 25), cursor (optional). Returns {object:"list", data:[{object:"request_refusal", id, created_at, method, route, status, error:{type, code, param, message}, api_key_id, oauth_client_id, inbox_id, source, mcp_tool}], has_more, next_cursor}. Newest first. A full-access account key sees the account. A restricted or inbox-scoped key sees only its own key. An OAuth client sees only its own client. Only authenticated HTTP 4xx responses are stored. Unauthenticated 401 responses, HTTP 2xx, and HTTP 5xx are not stored. Request bodies, query strings, Authorization headers, API keys, tokens, email content, and recipient addresses are not stored. Each account keeps at most 1000 rows per UTC day. Rows older than 7 days are deleted.

Input Schema

Name	Required	Description
`code`	No	Error code, such as permission_denied or rate_limited.
`limit`	No	Page size from 1 to 100. Default 25.
`since`	No	ISO-8601 timestamp. Older rows are omitted.
`cursor`	No	Cursor from next_cursor. A bad cursor returns invalid_cursor.
`status`	No	HTTP status from 400 to 499.
`inbox_id`	No	Only rows whose path named this inbox id.
`api_key_id`	No	Only rows for this API key id.

Output Schema

Name	Required	Description
`data`	No	Items on this page, in the order the tool description gives.
`object`	No	Object type name, such as list, message, or thread.
`next_page_token`	No	Cursor for the next page, or null when this is the last page. Pass it back as page_token.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 3, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "description": "Requests Cooper refused, newest first.",
+  "properties": {
+    "data": {
+      "description": "Items on this page, in the order the tool description gives.",
+      "items": {
+        "properties": {
+          "created_at": {
+            "description": "ISO-8601 time the object was created."
+          },
+          "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."
+          },
+          "object": {
+            "description": "Object type name, such as list, message, or thread."
+          }
+        },
+        "type": "object"
+      }
+    },
+    "next_page_token": {
+      "description": "Cursor for the next page, or null when this is the last page. Pass it back as page_token."
+    },
+    "object": {
+      "description": "Object type name, such as list, message, or thread."
+    }
+  },
+  "type": "object"
+}

AddedNov 2, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description discloses the auth requirement, three distinct visibility scopes (full-access key, restricted or inbox-scoped key, OAuth client), exactly what is and is not stored (only authenticated HTTP 4xx; no 401s, 2xx, or 5xx; no bodies, headers, tokens, or recipient data), and retention limits of 1000 rows per UTC day with a 7-day deletion window. This is precisely the operational context annotations cannot carry.

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?

The ordering is sensible: usage trigger first, then inputs, returns, scope, and retention. However, the description inlines a full field-level return shape ({object:"list", data:[...], has_more, next_cursor}) that is already fully specified by the output schema, padding the text without adding information an agent needs before calling.

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 list tool with an output schema, the description covers everything that matters and is not in structured fields: authorization, per-key visibility scoping, storage inclusion rules, redaction guarantees, and retention. An agent can predict both what it will see and why a row might be absent.

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 every parameter is already documented with type and meaning. The description restates the parameters in a flat list and adds only light glosses ('optional HTTP 4xx code', 'ISO-8601 timestamp') that largely duplicate the schema, so the baseline 3 for high-coverage schemas 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?

The description opens with a specific verb and resource ('see recent refusals and their error codes') and anchors it to the diagnostic scenario of a failed Cooper call. No sibling tool covers stored HTTP 4xx refusals, so the tool is unambiguously distinguishable from neighbors like cooper_list_events or cooper_get_metrics.

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 a clear triggering condition: use this when a Cooper call failed and you need to inspect recent refusals and error codes. It does not explicitly state exclusions or name an alternative sibling for adjacent debugging needs, which keeps it short of a 5.

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.