Skip to main content
Glama

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.

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": {
      "invite_code": "<invite_code>",
      "action_number": "<action_number>"
    },
    "name": "trigger_quick_action"
  }
}

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. Changed4 schema fields changed
    • addedOutput schema / properties / result / 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 / 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 / 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 / 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. Changed3 schema fields changed
    • addedOutput schema / properties / result / 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 / 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 / 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
    • 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."
  4. 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"
      +}
  5. 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"
      +}
  6. 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."
  7. 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
  8. 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"
      +}
  9. 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"
      +}
  10. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Goes well past the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing the rate limit, the ownership caveat that is_urgent/requires_ack are silently ignored in someone else's personal room, and the send-time-only nature of those flags. It also explains the optimistic-concurrency refusal (409 quick_action_layout_changed) via quick_action_id, which is behavior the schema alone cannot convey.

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 with the action and its side effect, then the prerequisite, then edge cases — good ordering with no filler. It is a single dense paragraph with heavy em-dash chaining, so it is harder to scan than a short bulleted breakdown would be, but every clause carries operational information.

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 9-parameter mutation with nested objects, this covers the prerequisite lookup, per-input_type requirements, ownership overrides, and named error codes; the presence of an output schema means return values need no explanation. The only thin spot is that "Rate-limited" gives no quota, which is minor for correct invocation.

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 cross-parameter meaning the schema cannot express — that data.location satisfies an input_type of location and data.url satisfies link, and that is_urgent/requires_ack do not alter the action's stored configuration. It does not add anything for trigger_source or ack_mode beyond what the schema already documents thoroughly.

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?

Opens with a specific verb and resource plus its effect: "Press a room quick action, notifying its members." That is immediately distinguishable from the sibling it names, list_quick_actions, and from the update_* siblings which modify the action rather than firing it.

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?

States an explicit prerequisite workflow ("Read the action's input_type first (list_quick_actions)") and maps each input_type to the exact field that must accompany the press, with the failure mode (422 quick_action_input_required) if omitted. It also carves out the owner-only trigger_source path and its 403/409 failures, so the agent knows the boundary conditions before calling.

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