Skip to main content
Glama

check_operator_replies

Read-onlyIdempotent

Check for new operator replies in a conversation.

Two distinct usage patterns:

1. **Active wait** (default): after ``send_message_to_operator``, call
   this with ``wait_seconds=60``. The server holds each call open until
   an operator reply arrives or ``wait_seconds`` elapses. On each
   return, pass back ``since=<latest_reply_at from previous response>``
   so the next call only surfaces *new* messages. Keep looping for up
   to ~5 minutes total; if still no reply, tell the tourist the
   operator will message back later and stop polling.

2. **Resumption peek**: when the tourist comes back later (new
   message in the same session, or a fresh session where they
   previously engaged this operator), call once with
   ``wait_seconds=0`` *before* responding. Omit ``since`` so the
   response carries the most recent operator messages — typically the
   reply they missed while away.

The response is bounded by ``limit`` (default 50, max 200) and always
sorted chronologically. ``latest_reply_at`` is a cursor for the next
active-wait call. When ``has_replies`` is true, surface the operator's
messages to the user; if they want to respond, call
``send_message_to_operator`` again. When ``operator_active`` is false,
the operator has ended the chat — inform the user and resume normal AI
assistance. Requires OAuth2.

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": {
      "operator_id": "<operator_id>"
    },
    "name": "check_operator_replies"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of operator messages to return. Default 50; results are the *most recent* messages, returned in chronological order. Bump higher only if you need deep conversation history.
sinceNoOptional ISO timestamp — only return operator messages created strictly after this time. Omit to fetch the most recent operator messages regardless of age (capped by ``limit``). For continuous polling, pass back the ``latest_reply_at`` value from the previous response.
operator_idYesOperator slug to check replies from.
wait_secondsNoHow long the server should long-poll for a new operator reply before returning. The call returns immediately if a reply has already arrived (or the moment one arrives during the wait). Default 60; cap 90 to stay safely under the ~300s client timeout. Set wait_seconds=0 for a non-blocking peek — use this on session resumption to surface any pending reply without holding the request open.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses the long-polling mechanic (server holds the call up to ``wait_seconds``), the cursor protocol (``since`` = ``latest_reply_at`` from the prior response), the chronological bounded response, the meaning of ``operator_active=false``, and the OAuth2 requirement.

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-loaded purpose sentence followed by two clearly labeled patterns and a response-handling paragraph — easy to scan. Slightly long, with a few details (default 50, max 200) that merely repeat the schema.

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?

Covers everything an agent needs to drive a polling loop correctly: prerequisites (after send_message_to_operator, OAuth2), the cursor handoff, timeout strategy, and how to interpret ``has_replies``/``operator_active`` — even though an output schema exists and would have carried some of that.

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 the baseline is 3, but the description adds operational intent the schema cannot: which value to pass for each parameter in each workflow (``wait_seconds=60`` during active wait, ``0`` on resumption, omit ``since`` for a peek, feed back ``latest_reply_at`` while polling). The limit/max restatement is mild duplication.

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 specific verb and resource ('Check for new operator replies in a conversation') and immediately names the counterpart tool ``send_message_to_operator``, so an agent can place it in the conversation workflow without opening either schema.

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?

Two explicit named patterns — active wait after sending a message, and a resumption peek with ``wait_seconds=0`` — each with the exact parameter values to use and a stop condition (~5 minutes, then tell the tourist the operator will follow up). It also routes onward to ``send_message_to_operator`` when the user wants to respond.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources