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.

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.5/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses refusal behavior on missing prior feedback, idempotency semantics (same key+same feedback returns cached cue, conflicting feedback returns 409), and content sourcing/processing ('federally-sourced, audience-safety-checked, re-sequenced'). This adds substantial behavioral context not present in annotations.

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 front-loaded with the core purpose in the first sentence, followed by the refusal warning and idempotency behavior. It's information-dense but somewhat verbose with parenthetical asides; still, every sentence contributes value.

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 the tool's complexity (nested feedback object, output schema), the description covers the essential behavioral contract: submission, refusal, idempotency, and vocabulary source. It doesn't detail the response format, but that's covered by the output schema. Adequate for an agent to invoke correctly.

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?

The schema already describes stream_id and idempotency_key's caching behavior, but the description adds meaning by framing feedback as the patient's response to the prior cue and by referencing the signal://catalog resource for response_action vocabulary. It doesn't elaborate on free_text, but overall it enriches the schema's sparse coverage.

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 explicitly states the tool submits patient feedback and returns the next cued message, using the verb 'Submit' and identifying the resource as the 'next cued message.' It clearly distinguishes from siblings like create_patient_stream (which starts a stream) and read_stream_state (which reads stream state).

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?

It clearly states to use this tool when you have feedback from a prior cue and that it refuses without such feedback, returning 409. It also points to the signal://catalog resource for valid response_action vocabulary. However, it doesn't explicitly name alternative sibling tools for other scenarios, though the refusal condition strongly implies 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.

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?