Skip to main content
Glama
Sign In

ActivitySmith

by com.activitysmith
OverviewDiscussionsAdmin

Set Live Activity Stream

set_live_activity_stream

Create or update a managed Live Activity stream by stable stream_key.

REMOTE DELIVERY BUDGET: Each non-noop operation can send a remote ActivityKit push. iOS applies device-dependent push-to-start and update budgets and may throttle delivery even after APNs accepts the request. Use one stable stream_key for each real-world activity and send updates when its user-visible state meaningfully changes. Event-driven transitions may be seconds apart—for example, successive steps in a short deployment—and should be sent promptly; do not delay them to satisfy a fixed minimum interval. Short bursts of genuine progress are expected. Avoid sustained polling, heartbeat updates, per-second timer ticks, unchanged values, and high-frequency churn that does not communicate a meaningful transition. Coalesce only redundant or excessively granular changes. Do not retry a successful call to force display: success means APNs accepted the push, not that the device displayed it.

First call starts the Live Activity. Later calls with the same stream_key, same content_state.type, and same target channels update it. Repeating the same payload returns operation "noop". Changing the type or target channels rotates to a new underlying Live Activity.

Keep content_state.type and target channels stable to avoid consuming another push-to-start operation. For countdowns, send timer fields once and let the device render elapsed time locally instead of sending frequent updates.

Supported content_state.type values: segmented_progress, progress, metrics, stats, alert, timer, value.

Icons work with stats, metrics, progress, segmented_progress, alert, timer, and value. Use Apple SF Symbol names for icons. Badges work with alert, progress, segmented_progress, and value. A top-level action adds the Live Activity tap/action button and can open an HTTP/HTTPS URL, run an iPhone Shortcut with shortcuts://run-shortcut?name=..., or trigger a backend webhook. A top-level secondary_action adds a second button for alert, progress, segmented_progress, and value Live Activities.

Examples: { "value": { "title": "Current revenue", "subtitle": "Today", "type": "value", "value": "$1,240", "color": "cyan", "icon": "dollarsign.circle", "badge": { "title": "Live", "color": "green" } }, "segmented_progress": { "title": "Deploying API", "subtitle": "Step 2 of 4", "type": "segmented_progress", "current_step": 2, "number_of_steps": 4 }, "progress": { "title": "Uploading build", "subtitle": "42% complete", "type": "progress", "percentage": 42 }, "metrics": { "title": "Server load", "subtitle": "Current usage", "type": "metrics", "metrics": [ { "label": "CPU", "value": 27, "unit": "%" } ] }, "stats": { "title": "Sales", "subtitle": "Last 15 minutes", "type": "stats", "metrics": [ { "label": "Revenue", "value": 12.8, "unit": "k" }, { "label": "Orders", "value": 37 }, { "label": "Avg Order", "value": "$346" } ] }, "alert": { "title": "Alert", "message": "Incident response started. Primary API is degraded across regions.", "type": "alert", "color": "magenta", "icon": { "symbol": "exclamationmark.circle", "color": "yellow" }, "badge": { "title": "Escalated", "color": "gray" } }, "timer": { "title": "Benchmark Run", "subtitle": "sampling performance", "type": "timer", "duration_seconds": 300, "color": "cyan", "counts_down": true } }

Action examples: { "open_url": { "title": "Open Runbook", "type": "open_url", "url": "https://example.com/runbook" }, "shortcut": { "title": "Chat with Jarvis", "type": "open_url", "url": "shortcuts://run-shortcut?name=Jarvis" }, "webhook": { "title": "Acknowledge", "type": "webhook", "url": "https://example.com/hooks/ack", "method": "POST", "body": { "incident_id": "inc_123" } } }

Input Schema

NameRequiredDescriptionDefault
tagsNoOptional account tags used to organize Live Activity history.
alertNoOptional APNs alert payload shown when the Live Activity starts or updates.
actionNoOptional action button/tap target. Use { title, type: "open_url", url } with an HTTP/HTTPS URL or shortcuts://run-shortcut?name=... to open a URL or run an iPhone Shortcut. Use { title, type: "webhook", url, method, body } to call an HTTPS webhook. Webhook method can be GET or POST.
metadataNoOptional app-only details with string, number, or boolean values. Omit to preserve; send {} to clear. Never sent to ActivityKit.
stream_keyYesStable Live Activity stream key. Use the same key to update the same stream. Do not create new keys for routine updates: every new stream requires another remote start and uses the device's limited iOS push-to-start budget. Use only letters, numbers, underscores, and hyphens.
content_stateYesLive Activity content state. Set type to one of: segmented_progress, progress, metrics, stats, alert, timer, value. Use segmented_progress for step-based work, progress for continuous completion, metrics or stats for multiple values, value for one prominent string or number, alert for important status, and timer for countdown or elapsed time. Icons work with all types: use icon as an SF Symbol string or { symbol, color }, plus optional icon_color and icon_style. Badges work with alert, progress, segmented_progress, and value: use badge { title, color }. Other optional presentation fields include subtitle, color, auto_dismiss_seconds, and auto_dismiss_minutes.
secondary_actionNoOptional secondary action button for alert, progress, and segmented_progress Live Activities. Uses the same object shape as action.
target_channel_slugsNoOptional channel slugs to target. Omit to target the account-wide default delivery scope.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / action / anyOf
      Added value: +[
+  {
+    "properties": {
+      "body": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Webhook only: optional JSON object sent with the request."
+      },
+      "method": {
+        "description": "Webhook only: GET or POST. Defaults to POST.",
+        "pattern": "^(GET|POST)$",
+        "type": "string"
+      },
+      "title": {
+        "description": "Button label shown on the Live Activity.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "type": {
+        "description": "open_url opens url on the iPhone. webhook makes ActivitySmith call url when the button is tapped.",
+        "enum": [
+          "open_url",
+          "webhook"
+        ],
+        "type": "string"
+      },
+      "url": {
+        "description": "For open_url: an http or https URL, or shortcuts://run-shortcut?name=... to run an iPhone Shortcut. Other app URL schemes are rejected. For webhook: an https URL.",
+        "maxLength": 2048,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "title",
+      "type",
+      "url"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / secondary_action / anyOf
      Added value: +[
+  {
+    "properties": {
+      "body": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Webhook only: optional JSON object sent with the request."
+      },
+      "method": {
+        "description": "Webhook only: GET or POST. Defaults to POST.",
+        "pattern": "^(GET|POST)$",
+        "type": "string"
+      },
+      "title": {
+        "description": "Button label shown on the Live Activity.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "type": {
+        "description": "open_url opens url on the iPhone. webhook makes ActivitySmith call url when the button is tapped.",
+        "enum": [
+          "open_url",
+          "webhook"
+        ],
+        "type": "string"
+      },
+      "url": {
+        "description": "For open_url: an http or https URL, or shortcuts://run-shortcut?name=... to run an iPhone Shortcut. Other app URL schemes are rejected. For webhook: an https URL.",
+        "maxLength": 2048,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "title",
+      "type",
+      "url"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations, the description discloses critical behavior: each non-noop operation may send a remote ActivityKit push, iOS budget and throttling can affect delivery even after APNs accepts the request, success means APNs acceptance rather than device display, and changing content_state.type or target channels rotates to a new Live Activity and consumes another push-to-start operation. These are exactly the non-obvious operational and side-effect details an agent needs before calling a mutating remote-push tool.

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?

The description is long but front-loads the highest-risk operational constraint, the remote delivery budget, before lifecycle details, supported types, presentation capabilities, actions, and examples. Most sentences earn their place because they prevent incorrect update frequency or unnecessary push-to-start consumption. It could still be tightened, especially where examples repeat details already present in the schema, but the structure is purposeful rather than bloated.

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 complex 8-parameter tool with nested content_state and action objects, the description covers lifecycle semantics, update cadence, noop behavior, type rotation, push budgets, supported content_state types, icon and badge compatibility, action and secondary_action behavior, and concrete examples. An output schema exists, so the description need not explain return values. The definition is complete enough for an agent to call the tool correctly and avoid the main failure modes.

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 description coverage is 100%, so the schema already carries substantial parameter documentation, including stream_key stability, content_state types, icons, badges, actions, metadata, and target channels. The description still adds value beyond the schema by explaining the lifecycle semantics of stream_key, noop on identical payloads, rotation when type or target channels change, and practical timer guidance to send timer fields once and let the device render locally. It adds meaningful non-schema semantics, though much of the type/icon/badge/action field guidance is repeated from the schema.

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 starts with a specific verb and resource: 'Create or update a managed Live Activity stream by stable stream_key.' It clearly distinguishes the upsert behavior from a pure create or pure update operation, and the stable-key concept is central throughout. An agent can identify this as the Live Activity stream mutation/update tool without opening the schema.

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

Usage Guidelines4/5

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

The description gives unusually concrete when-to-use guidance: one stable stream_key per real-world activity, update on meaningful user-visible state changes, send event-driven transitions promptly, and avoid polling, heartbeats, per-second ticks, unchanged values, and churn. It also explains that repeating the same payload returns 'noop' and that retrying a successful call will not force display. It does not explicitly route the agent to sibling tools such as pause_live_activity_stream, resume_live_activity_stream, or end_live_activity_stream, so it is strong on operational usage but not fully complete on alternative selection.

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

All ActivitySmith toolsInspect
Try in Browser
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources