Uphealth Signal

get_next_cued_message

Idempotent

Submit the patient's response to the prior cue and get the next one — federally-sourced, audience-safety-checked, and re-sequenced on that feedback. REFUSES WITHOUT PRIOR-MESSAGE FEEDBACK (the moat): the engine will not advance a stream blind, returning 409 if you skip it. response_action is one of the accepted cue vocabulary (see the signal://catalog resource). Same idempotency_key + same feedback returns the cached cue; conflicting feedback under the same key returns 409.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`feedback`	Yes
`stream_id`	Yes	The stream_id returned by create_patient_stream.

Output Schema

TableJSON Schema

Name	Required	Description
`_meta`	Yes	Legal/disclosure block returned on every 2xx (A1 §6.7).
`state`	Yes
`message`	No
`next_cue`	No	A cued message plus its per-cue receptivity score and audience-safety verdict.
`stream_id`	Yes
`idempotent`	No	true when this is the cached result of a repeated idempotency_key.
`rate_limit`	No	Discovery monthly cue-cap headroom. Absent on non-Discovery tiers (no cap).
`normalized_action`	No	null when the submitted response_action was a recognized value; otherwise the acknowledge-class value the well-formed-but-unrecognized action was folded to (forward-compat tolerance). Always present on a cue result; absent on the exhausted-stream result.
`sandbox_exhausted`	No	Present + true when the sandbox subset is exhausted; no next_cue then.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

Changed3 schema fields changedJul 22, 2026

addedOutput schema / properties / next_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 / next_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"
+  ]
+}

addedOutput schema / properties / normalized_action

Added value: +{
+  "description": "null when the submitted response_action was a recognized value; otherwise the acknowledge-class value the well-formed-but-unrecognized action was folded to (forward-compat tolerance). Always present on a cue result; absent on the exhausted-stream result.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

First observedJun 16, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Description adds significant behavioral context beyond annotations: caching on same idempotency key, conflicting feedback results in 409, and that it is 'federally-sourced, audience-safety-checked'. Annotations already indicate idempotent and not read-only, so 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences front-load purpose and quickly add details. Some jargon ('moat', 'federally-sourced') but overall efficient.

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?

Given complexity of nested objects and stateful behavior, the description covers key aspects: purpose, error conditions, caching, and vocabulary reference. Output schema exists so return value details are not needed.

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 low (50%), but description compensates by explaining the meaning of response_action (cue vocabulary reference), idempotency_key behavior (caching/conflict), and stream_id usage. Adds value beyond 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?

The description clearly states the verb 'Submit the patient's response... and get the next cue' and specifies the resource (cue/stream). It is distinct from siblings like create_patient_stream or read_stream_state, but does not explicitly differentiate them.

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?

Explicitly states when to use (after prior cue) and when not to (without prior feedback, returning 409). Points to alternative resource for cue vocabulary, and explains idempotency key behavior.

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

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?