Uphealth Signal

create_patient_stream

Create a Signal cued stream for one patient and get the first cue back synchronously. Every cue is federally-sourced, audience-safety-checked, and sequenced on the patient's prior response — so your agent never fabricates health content. Choose a template_id from the signal://catalog resource and pre-satisfy its required audience_tags + patient_context (clinical templates 422 without them). Display mode renders in your app: no PHI, no BAA. Each later cue MUST submit the prior message's feedback — the engine refuses to advance without it (the sequencing moat).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`attributes`	No	De-identified patient context. v1 accepts free-form jsonb; future templates will enforce schemas.
`template_id`	Yes	One of the live Signal templates. Read the signal://catalog resource for each template's required audience_tags + patient_context. On a production key a clinical template 422s if its required tags/context are missing — pre-satisfy them from the catalog. A free sandbox (Discovery) key always cues the curated sandbox corpus.
`audience_tags`	No	Subset of the 14-tag B5/B6 schema. See list_sandbox_topics for sample topic labels.
`delivery_mode`	No	v1 is Display-only; Deliver-mode unlocks at Per-Episode tier after BAA.	display
`idempotency_key`	No	Optional. Stripe-style create idempotency: a retried create with the same key returns the ORIGINAL stream instead of minting (and billing) a second one. Forwarded as the Idempotency-Key request header. UUID v4 recommended.
`feedback_timeout_days`	No

Output Schema

TableJSON Schema

Name	Required	Description
`_meta`	Yes	Legal/disclosure block returned on every 2xx (A1 §6.7).
`state`	Yes
`first_cue`	Yes	A cued message plus its per-cue receptivity score and audience-safety verdict.
`stream_id`	Yes	Persist this — every later cue/read references it.
`rate_limit`	No	Discovery monthly cue-cap headroom. Absent on non-Discovery tiers (no cap).
`next_cue_eligible_at`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedJul 22, 2026

addedOutput schema / properties / first_cue / properties / arc

Added value: +{
+  "additionalProperties": true,
+  "description": "Where this cue sits in the template's curated arc, or null when the cue is not on a spine. source is 'spine' or 'corpus_continuation'; a corpus-continuation cue (past the arc's end) carries source only, with day/phase/seq/total null.",
+  "properties": {
+    "day": {
+      "description": "The curated arc day of this message.",
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "phase": {
+      "description": "The curated arc phase, e.g. starting_dose / titrating / re_entry.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "seq": {
+      "description": "1-based position of this message in the spine.",
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "source": {
+      "description": "spine | corpus_continuation",
+      "type": "string"
+    },
+    "total": {
+      "description": "Total messages in the spine.",
+      "type": [
+        "integer",
+        "null"
+      ]
+    }
+  },
+  "type": [
+    "object",
+    "null"
+  ]
+}

addedOutput schema / properties / first_cue / properties / day_of_stream

Added value: +{
+  "description": "Advisory 1-based wall-clock day the patient is on in this stream (anchored to enrollment). Null on legacy cues issued before day-of-stream tracking.",
+  "type": [
+    "integer",
+    "null"
+  ]
+}

First observedJun 16, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations only indicate read/write and destructiveness, so the description adds meaningful behavioral context: synchronous first cue return, federal sourcing, safety checks, non-fabrication guarantee, 422 error conditions, no PHI/BAA in display mode, and the feedback requirement for subsequent cues. It does not contradict the readOnlyHint=false annotation; 'Create' aligns. Could have mentioned idempotency behavior, but schema covers that.

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?

Four sentences, front-loaded with the core action. Each sentence adds relevant operational or safety context. The last sentence about later cues is somewhat tangential to this specific call, but it usefully frames the sequence of operations. Slightly dense but acceptable given the tool's complexity.

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?

The tool has 6 parameters, an output schema, and annotations. The description covers the critical invocation aspects: template selection from catalog, required tags/context, error behavior, display mode constraints, and synchronous response. It doesn't need to restate return values because an output schema exists. Minor gaps like idempotency are handled by the schema. Overall complete for a complex create operation.

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 83%, so the baseline is 3. The description adds value by linking template_id to the signal://catalog resource and explicitly tying audience_tags and attributes/patient_context to template prerequisites. This cross-reference helps the agent select and populate parameters correctly. Minor additions beyond schema, but not all parameters (e.g., idempotency_key, feedback_timeout_days) are explained in prose.

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 specific verb and resource: 'Create a Signal cued stream for one patient and get the first cue back synchronously.' This precisely defines the tool's action and distinguishes it from sibling tools like get_next_cued_message, which is for subsequent cues. The scope ('one patient') and synchronous return are clear.

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 actionable prerequisites: choose a template_id from the signal://catalog, pre-satisfy audience_tags and patient_context, and notes that clinical templates 422 without them. It also clarifies display mode is the only current option. However, it doesn't explicitly name a sibling alternative for later cues, though the phrase 'Each later cue MUST submit the prior message's feedback' implies a different workflow.

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

All Uphealth Signal tools Inspect

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

Need Help?