Skip to main content
Glama

push_send

Need an alert to reach a user even when the app tab is closed? push_send sends a web push notification to one device, one app-user's devices, your developer devices, or the whole project.

Recipient targeting (exactly one; a missing, null or empty target is refused):

  • user_id: every device that signed-in app user registered.

  • subscription_id or endpoint: one device. Sending again sends another notification.

  • audience: 'developer': devices registered with push_subscribe.

  • audience: 'all': every device in the project (refused whole above 500).

payload may be a JSON object (recommended — your service worker parses it) or a string. Subscriptions that the push provider reports as gone (404/410) are auto-deleted. Inside a deployed function the equivalent call is sw.push.send({ payload, user_id }) — one object, payload nested; there is no second options argument.

Example:

{
  "project_id": "my-saas",
  "user_id": "u_alice",
  "payload": { "title": "New message", "body": "From Bob", "url": "/inbox/123" }
}
// Returns: { "sent": 1, "failed": 0, "gone": 0, "captured": 0, "recipients": 1, "history_recorded": true, "devices": [{ "subscription_id": "psub_...", "device_label": "Chrome on Android", "outcome": "sent", "http_status": 201, ... }] }

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": {
      "project_id": "<project_id>",
      "payload": "<payload>"
    },
    "name": "push_send"
  }
}

Input Schema

NameRequiredDescriptionDefault
ttlNoOptional time-to-live in seconds (default 86400). The push service holds the message at most this long if the device is offline.
contactNoOptional VAPID contact (mailto:you@example.com). Defaults to the platform contact.
payloadYesNotification body. JSON object or string. Your service worker reads this in the push event.
user_idNoSend to every device this app user registered.
audienceNoOptional: 'developer' sends only to devices registered with push_subscribe; 'all' broadcasts to every device in the project.
endpointNoOptional: send to a single subscription by its endpoint URL.
project_idYesProject ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them).
subscription_idNoOptional: send to one device by its id (from push_deliveries).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior4/5

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

Annotations only say readOnlyHint=false and openWorldHint=true; the description adds real behavioral context beyond that — repeat sends produce repeat notifications, subscriptions the provider returns 404/410 for are auto-deleted (a side effect worth knowing before calling), and broadcasts above 500 are refused whole. It omits any mention of auth/permission requirements or rate limits outside the 500 cap, which keeps it short of a 5.

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?

Information is front-loaded: the purpose question, then a bulleted targeting list, then payload semantics, then an example. It is dense rather than padded, though the rhetorical opening question and the inline return-value sample make it longer than strictly necessary for a tool whose annotations are simple.

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?

There is no output schema, and the description compensates by inlining a realistic response object (`sent`, `failed`, `gone`, `captured`, `devices` with per-device outcome and http_status). Combined with the worked request example and the target-selection rules, an agent has everything needed to call this correctly on the first attempt.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description adds meaning the schema does not: the exactly-one targeting constraint, the fact that resending to the same target sends another notification, the JSON-object-vs-string payload tradeoff for service workers, and a worked example binding `project_id`, `user_id`, and a structured `payload`. It also clarifies the function-call signature difference (payload nested, no second options argument).

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?

The description opens with a concrete verb+resource sentence: "`push_send` sends a web push notification" and immediately scopes the recipient modes (one device, one app-user's devices, developer devices, or the whole project). The channel is disambiguated as web push, which separates it from the email/inbox send siblings an agent might otherwise pick.

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 gives an explicit trigger ("Need an alert to reach a user even when the app tab is closed?"), enumerates the mutually exclusive targeting options with the rule that exactly one must be supplied and that a missing/null/empty target is refused, and points at `push_deliveries` as the source of `subscription_id` and `push_subscribe` as the source of developer devices. The deployed-function alternative (`sw.push.send`) is also distinguished from this tool.

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