Connector action

list_events_needing_attention

ReadIdempotent

List events that need a look

An account-wide "is anything stuck?" check: events with a message in needs_attention, or a message still cleaning more than 30 minutes after it arrived. An empty list means nothing needs the operator.

What the client is told

The description an MCP client receives from tools/list, word for word:

Answers "is anything stuck?": your events with a message in needs-attention (failed, too short, too large or an unsupported file), or a message still cleaning more than 30 minutes after it arrived. An empty list means nothing needs you. A re-clean started on an older message can show as stuck for its first 30 minutes.

Annotations

json

{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false
}

Parameters

Parameter	Type	Required	Description
limit	integer 1 to 100default 25	No	Maximum number of rows to return.

Input schema as JSON Schema

inputSchema

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 25,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}

Example

Request

tools/call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_events_needing_attention",
    "arguments": {
      "limit": 25
    }
  }
}

With curl

bash

curl -X POST https://www.happyhearaudio.com/api/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_events_needing_attention","arguments":{"limit":25}}}'

Response

Fake data in a real shape. content[0].text is the same object as a JSON string for clients that read text only.

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"events\":[{\"id\":\"7c1f3a2e-9b4d-4e61-8f0a-2d5c6b7e8a91\",\"event_name\":\"Rivera 50th Anniversary\",\"event_date\":\"2026-11-14\",\"messages_needing_attention\":1,\"messages_stuck_cleaning\":0,\"dashboard_url\":\"https://www.happyhearaudio.com/dashboard/events/7c1f3a2e-9b4d-4e61-8f0a-2d5c6b7e8a91\"}],\"count\":1,\"truncated\":false}"
      }
    ],
    "structuredContent": {
      "events": [
        {
          "id": "7c1f3a2e-9b4d-4e61-8f0a-2d5c6b7e8a91",
          "event_name": "Rivera 50th Anniversary",
          "event_date": "2026-11-14",
          "messages_needing_attention": 1,
          "messages_stuck_cleaning": 0,
          "dashboard_url": "https://www.happyhearaudio.com/dashboard/events/7c1f3a2e-9b4d-4e61-8f0a-2d5c6b7e8a91"
        }
      ],
      "count": 1,
      "truncated": false
    }
  }
}

Errors

Each of these comes back as a normal JSON-RPC result with isError: true and the message as its single text item. Arguments the schema rejects are a JSON-RPC -32602 error instead. See Errors for the HTTP-level refusals that happen before any tool runs.

Message	When
Could not read events right now.	A database read failed. Retry after a short wait.
Could not read message states right now.	A database read failed. Retry after a short wait.

Limits

60 requests per minute per operator across all actions, answered with HTTP 429 and a Retry-After header past that.
No daily cap. Read actions are not logged and not counted.

Worth knowing

Stuck is measured from the message's arrival time, so a re-clean started on an older message reads as stuck for its first 30 minutes.
limit bounds the candidate events checked, not the rows returned; truncated is true when the candidate list filled it.
When nothing is found the result carries a note field saying so, so an assistant has something to say.