Skip to main content
Glama

List Notifications

list_notifications
Read-onlyIdempotent

List a bounded page of recent pings across approved rooms, newest first. Use page to continue while has_more is true.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_notifications"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagNoOnly pings carrying this tag (see the tags field of broadcast and live_status).
dateNoOnly pings created on this calendar date, e.g. "2026-08-25".
pageNoPage number, newest first.
typeNoNarrow to pings you received or pings you sent. Omit for both.
limitNoPings per page. Defaults to 10; maximum 25.
room_idNoOnly pings in this room (the room's id, as list_rooms and get_room return it).

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedOutput schema / properties / result / properties / notifications / items / properties / action_signing_secret
      Added value: +{
      +  "description": "broadcast with a webhook button: the secret every delivery of this ping's buttons is signed with (X-PingRoom-Signature-V2). Returned only here; keep it to verify the deliveries.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / result / properties / notifications / items / properties / actions
      Added value: +{
      +  "description": "The buttons the sender put on the ping: {id, label, type, style}, plus url and host for an open_url button. A webhook button never shows where it goes. Present only on a ping with buttons.",
      +  "items": {
      +    "type": "object"
      +  },
      +  "maxItems": 3,
      +  "type": "array"
      +}
    • addedOutput schema / properties / result / properties / notifications / items / properties / actions_expire_at
      Added value: +{
      +  "description": "When the ping's buttons stop running (24 hours after it was sent).",
      +  "type": "string"
      +}
    • addedOutput schema / properties / result / properties / notifications / items / properties / withdrawn_at
      Added value: +{
      +  "description": "When the sending agent took the ping back with withdraw_notification (null when never). The ping stays in the room's history with its text. Present on reads; on a list or the broadcast answer only once the ping has been withdrawn.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  2. Changed5 schema fields changed
    • addedInput schema / properties / room_id
      Added value: +{
      +  "description": "Only pings in this room (the room's id, as list_rooms and get_room return it).",
      +  "format": "uuid",
      +  "type": "string"
      +}
    • addedInput schema / properties / tag
      Added value: +{
      +  "description": "Only pings carrying this tag (see the tags field of broadcast and live_status).",
      +  "pattern": "^\\s*[A-Za-z0-9][A-Za-z0-9_-]{0,31}\\s*$",
      +  "type": "string"
      +}
    • addedOutput schema / properties / result / properties / notifications / items / properties / edited_at
      Added value: +{
      +  "description": "When the sender last replaced the ping's text (null when never). Present on reads; on a list or the broadcast answer only once the ping has been replaced.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / result / properties / notifications / items / properties / replaced
      Added value: +{
      +  "description": "broadcast with a replace_key: true when the send replaced your earlier ping (same id) instead of sending a new one.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / result / properties / notifications / items / properties / tags
      Added value: +{
      +  "description": "Labels the sender put on the ping, sorted alphabetically; [] when none.",
      +  "items": {
      +    "maxLength": 32,
      +    "type": "string"
      +  },
      +  "maxItems": 10,
      +  "type": "array"
      +}
  3. Changed1 schema field changed
    • addedOutput schema / properties / result / properties / notifications / items / properties / checklist_state
      Added value: +{
      +  "description": "Present once an item of data.checklist is checked: ticks[] of {index, checked_at, checked_by.display_name}. A checked item stays checked.",
      +  "type": "object"
      +}
  4. Changed1 schema field changed
    • addedOutput schema / properties / result / properties / notifications / items / properties / origin_agent
      Added value: +{
      +  "description": "Present when a connected agent originated the ping: its handle and display name.",
      +  "type": "object"
      +}
  5. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds meaningful traits: results are bounded to a page, ordered newest first, restricted to approved rooms, and continued via has_more. It does not describe what happens to filtering across pages, but the additions are solid.

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

Conciseness5/5

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

Two short sentences, zero filler, with the scoping and ordering constraints front-loaded and the pagination instruction second. Every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only paged list with a full schema, an output schema, and complete annotations, the description covers scope, ordering, and continuation, which is what an agent needs to call it correctly. Only minor gaps remain, such as how filters interact with paging.

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 coverage is 100%, so every parameter (tag, date, type, limit, room_id, page) is already documented in the schema, including the 25-item max and the received/sent enum. The description only reinforces the page/has_more relationship, which is the baseline 3 for a fully documented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ("List a bounded page of recent pings") plus scope details: approved rooms only, newest first. It does not explicitly name a sibling such as get_notification for single-item retrieval, so it stops short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real usage guidance for iteration — "Use page to continue while has_more is true" — which tells the agent how to page. It says nothing about when to prefer get_notification or replace_notification, and no exclusions are stated.

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