Skip to main content
Glama
Sign In
widgetdash-mcp

widgetdash-mcp

by purian
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Push one number to iPhone widget

push_number
Idempotent

Pushes a single number or text value to an iPhone Home Screen or Lock Screen widget via WidgetDash, creating or updating the labeled metric on a source.

Instructions

Quickest way to put a single number or value on the user's iPhone Home Screen / Lock Screen widget via WidgetDash, e.g. 'Stripe MRR = $12,400' or 'Open tickets = 7'. Sets one metric (matched by label) on a source, keeping the source's other metrics, title and icon; creates the source if it does not exist. Requires WIDGETDASH_WRITE_KEY.

Input Schema

NameRequiredDescriptionDefault
iconNoSF Symbol name shown next to the title, e.g. 'dollarsign.circle.fill', 'chart.bar.fill', 'server.rack', 'heart.fill', 'cart.fill'. If omitted, keeps the existing icon (default 'circle.fill').
typeNoOptional; defaults to the existing metric's type, else inferred from the value.
colorNoOptional accent color (green/red/yellow/blue/gray/orange/purple/cyan); defaults to the existing metric's color.
labelYesShort label shown on the widget, e.g. 'MRR' or 'Users online'.
valueYesThe value to display, pre-formatted as you want it shown (e.g. '$12,400', '42', 'Healthy'). For 'progress' use 0-100; for 'timestamp' an ISO 8601 time or Unix epoch seconds.
categoryNoFree-form grouping, e.g. 'finance', 'monitoring', 'fitness'. If omitted, keeps the existing category (default 'general').
sort_orderNoPosition for a NEW source among your sources (lower first, default 0). Ignored when updating an existing source: its order is set in the WidgetDash app.
source_keyYesStable identifier for this data source, e.g. 'stripe_mrr' or 'server_health'. Lowercase letters, digits, '_' or '-'. Pushing to an existing key updates it; a new key creates a new widget source.
display_nameNoTitle shown on the widget, e.g. 'Stripe'. If omitted, keeps the existing name (or derives one from source_key for new sources).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.2.0
    • changedInput schema / properties / sort_order / description
      Previous value: -"Position among sources on the widget (lower first). If omitted, keeps the existing order (default 0)."New value: +"Position for a NEW source among your sources (lower first, default 0). Ignored when updating an existing source: its order is set in the WidgetDash app."
    • changedInput schema / properties / type / enum
      Previous value: -[
-  "number",
-  "text",
-  "status",
-  "progress",
-  "percentage"
-]New value: +[
+  "number",
+  "text",
+  "status",
+  "progress",
+  "percentage",
+  "timestamp"
+]
    • changedInput schema / properties / value / description
      Previous value: -"The value to display, pre-formatted as you want it shown (e.g. '$12,400', '42', 'Healthy'). For 'progress' use 0-100."New value: +"The value to display, pre-formatted as you want it shown (e.g. '$12,400', '42', 'Healthy'). For 'progress' use 0-100; for 'timestamp' an ISO 8601 time or Unix epoch seconds."
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond the annotations: it discloses upsert semantics (matched by label, other metrics/title/icon preserved), that a new source is created for an unknown source_key, and the required write key. The idempotentHint annotation is corroborated rather than restated; no contradiction.

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?

Three sentences, front-loaded with the use case and examples, then the merge/create behavior, then the auth requirement. Every sentence carries information an agent needs.

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 9-parameter upsert tool with annotations but no output schema, the description covers creation vs update, preservation of existing fields, and auth. It doesn't indicate what the call returns (e.g., created source ID/confirmation), which is the remaining gap.

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; the description still adds meaning by explaining that label is the matching key against existing metrics and that source_key determines update-vs-create. It adds no extra guidance on type/color/sort_order beyond the 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?

States a concrete verb+resource+scope: put a single number/value on the user's iPhone Home/Lock Screen widget via WidgetDash, with two concrete examples. It implies differentiation from the multi-metric sibling ('single number') but never names push_metrics, so sibling routing still requires inference.

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?

Gives clear context for when this applies ('Quickest way to put a single number') and states the prerequisite (WIDGETDASH_WRITE_KEY). It does not explicitly name push_metrics as the alternative for several metrics, nor state when not to use it.

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

Deploy Server

Other Tools