Skip to main content
Glama
Sign In

PingRoom

by io.pingroom
OverviewDiscussionsAdmin

Trigger Quick Action

trigger_quick_action

Press a room quick action, notifying its members. Rate-limited. Read the action's input_type first (list_quick_actions): location needs data.location, link needs data.url, file/photo/pdf need attachment_ids — a press without the matching detail is a 422 quick_action_input_required. In someone else's personal room is_urgent and requires_ack are ignored; only the owner's own setting on the action applies.

Input Schema

NameRequiredDescriptionDefault
dataNoThe detail this press carries. data.location satisfies an action whose input_type is location; data.url satisfies link. Only these two keys are accepted on a trigger.
ack_modeNoConfirmation rule for this press: any (default) resolves on the first confirmation; all waits for every original eligible recipient. Applies only when this press requires acknowledgement.
is_urgentNoDeliver this one press time-sensitive so it breaks through Focus / Do Not Disturb and reaches members who muted the room or you (a block still wins). Send-time only — the action's saved configuration is unchanged.
invite_codeYesRoom invite code.
requires_ackNoKeep this one press open until an eligible recipient acknowledges it. Send-time only and elevating only: true adds the acknowledgement to an action that has none, false never disables the action's stored ack policy.
action_numberYesQuick-action slot number (1–16). Slots 5–16 require the room owner to have Pro.
attachment_idsNoIds of up to 4 uploaded attachments (see upload_attachment). Required when the action's input_type is file, photo (jpg/png only) or pdf (pdf only); a mismatched type is a 422 quick_action_input_type.
trigger_sourceNoDefaults to "manual". Only these two are client-settable — "webhook" and "system" are stamped server-side and are rejected here. "location" is room owner only: it sends the owner's Location Ping ("Arrived at {place}", "Left {place}" or "Location update at {place}") to every member instead of this slot's quick action. A non-owner gets 403 location_trigger_owner_only; a room with no enabled location trigger gets 409 location_trigger_inactive.
quick_action_idNoOptional id of the action as read from list_quick_actions. When the slot has since moved pages the press is refused with 409 quick_action_layout_changed instead of firing the wrong Ping.

Output Schema

NameRequiredDescriptionDefault
resultYesA privacy-minimized, chainable PingRoom notification result.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / trigger_source / description
      Previous value: -"Defaults to \"manual\". Only these two are client-settable — \"webhook\" and \"system\" are stamped server-side and are rejected here."New value: +"Defaults to \"manual\". Only these two are client-settable — \"webhook\" and \"system\" are stamped server-side and are rejected here. \"location\" is room owner only: it sends the owner's Location Ping (\"Arrived at {place}\", \"Left {place}\" or \"Location update at {place}\") to every member instead of this slot's quick action. A non-owner gets 403 location_trigger_owner_only; a room with no enabled location trigger gets 409 location_trigger_inactive."
  2. Changed1 schema field changed
    • addedOutput schema / properties / result / 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"
+}
  3. Changed3 schema fields changed
    • addedInput schema / properties / attachment_ids
      Added value: +{
+  "description": "Ids of up to 4 uploaded attachments (see upload_attachment). Required when the action's input_type is file, photo (jpg/png only) or pdf (pdf only); a mismatched type is a 422 quick_action_input_type.",
+  "items": {
+    "format": "uuid",
+    "type": "string"
+  },
+  "maxItems": 4,
+  "type": "array"
+}
    • addedInput schema / properties / data
      Added value: +{
+  "additionalProperties": false,
+  "description": "The detail this press carries. data.location satisfies an action whose input_type is location; data.url satisfies link. Only these two keys are accepted on a trigger.",
+  "properties": {
+    "location": {
+      "additionalProperties": false,
+      "description": "A shareable geographic location.",
+      "properties": {
+        "address": {
+          "description": "Optional formatted street address.",
+          "maxLength": 255,
+          "type": "string"
+        },
+        "label": {
+          "description": "Optional place name shown to the recipient.",
+          "maxLength": 100,
+          "type": "string"
+        },
+        "latitude": {
+          "description": "Latitude in decimal degrees.",
+          "maximum": 90,
+          "minimum": -90,
+          "type": "number"
+        },
+        "longitude": {
+          "description": "Longitude in decimal degrees.",
+          "maximum": 180,
+          "minimum": -180,
+          "type": "number"
+        }
+      },
+      "required": [
+        "latitude",
+        "longitude"
+      ],
+      "type": "object"
+    },
+    "url": {
+      "description": "An absolute http:// or https:// URL.",
+      "format": "uri",
+      "maxLength": 2048,
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
    • addedInput schema / properties / quick_action_id
      Added value: +{
+  "description": "Optional id of the action as read from list_quick_actions. When the slot has since moved pages the press is refused with 409 quick_action_layout_changed instead of firing the wrong Ping.",
+  "format": "uuid",
+  "type": "string"
+}
  4. Changed1 schema field changed
    • changedInput schema / properties / is_urgent / description
      Previous value: -"Deliver this one press time-sensitive so it breaks through Focus / Do Not Disturb. Send-time only — the action's saved configuration is unchanged."New value: +"Deliver this one press time-sensitive so it breaks through Focus / Do Not Disturb and reaches members who muted the room or you (a block still wins). Send-time only — the action's saved configuration is unchanged."
  5. Changed2 schema fields changed
    • changedInput schema / properties / action_number / description
      Previous value: -"Quick-action slot number (1–4)."New value: +"Quick-action slot number (1–16). Slots 5–16 require the room owner to have Pro."
    • changedInput schema / properties / action_number / maximum
      Previous value: -4New value: +16
  6. Changed1 schema field changed
    • addedInput schema / properties / ack_mode
      Added value: +{
+  "description": "Confirmation rule for this press: any (default) resolves on the first confirmation; all waits for every original eligible recipient. Applies only when this press requires acknowledgement.",
+  "enum": [
+    "any",
+    "all"
+  ],
+  "type": "string"
+}
  7. Changed1 schema field changed
    • addedOutput schema / properties / result / properties / origin_agent
      Added value: +{
+  "description": "Present when a connected agent originated the ping: its handle and display name.",
+  "type": "object"
+}
  8. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations declare a non-read-only, non-idempotent, open-world, non-destructive write; the description goes well beyond that by disclosing rate limiting, the 422 quick_action_input_required and quick_action_input_type errors, the 409 quick_action_layout_changed guard, and the important caveat that is_urgent/requires_ack are ignored in someone else's personal room. The only gap is that "Rate-limited" is asserted without any limit or backoff detail.

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?

Three sentences, each carrying a distinct payload: effect, input-type contract, permission caveat. Front-loaded with the action and warning, though the middle sentence is dense and reads as a run-on rather than cleanly separated steps.

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?

This is a 9-parameter mutation with nested objects and an output schema, and the description covers the preconditions, the conditional data requirement, the owner-only location path, and the ignored-flag edge case. Return values need not be described because the output schema exists, so nothing an agent needs to fire this correctly is missing.

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 per-parameter docs are already strong; the description's added value is the cross-parameter conditional (press fails with 422 unless data/attachment_ids match the action's input_type), which the schema alone only implies. It does not restate the individual field docs, which is correct.

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?

"Press a room quick action, notifying its members" gives a specific verb (press/trigger) plus resource (room quick action) and states the side effect (notifying members). It is clearly distinguishable from the read sibling list_quick_actions and the config sibling update_quick_action, both of which are named or implied by name.

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?

It explicitly routes the agent to list_quick_actions first to read input_type, then specifies exactly which field each input_type requires (data.location, data.url, attachment_ids). It also states the when-not condition for trigger_source=location (room owner only, 403/409 errors), so the agent knows both the prerequisite sequence and the failure modes.

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

All PingRoom toolsInspect
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.

Resources