---
title: Writing Effective Prompts
description: What data an LLM Insights prompt can rely on, effective vs. ineffective prompt patterns, and the caveats that shape a good prompt.
---

> SmartSpectra SDK developer docs for v3.4.0, the latest stable release. Web page: https://presagetech.com/docs/smartspectra-sdk/llm-insights/writing-prompts
> Index of all pages: https://presagetech.com/docs/smartspectra-sdk/llms.txt

# LLM Insights: Writing Effective Prompts

> **Important:** LLM Insights are generated by a large language model and can be inaccurate, incomplete, or misleading — language models sometimes produce confident but false statements ("hallucinations"). Treat every insight as general wellness information, not medical advice, and confirm anything important before acting on it. The SDK metrics themselves are offered for general wellness and informational purposes only; they have not been cleared by the FDA and may not be used for medical diagnosis or treatment.

An on-demand insight request combines your **prompt** with the metrics the SDK
has buffered — the user's measured **pulse rate**, **heart-rate variability
(HRV)**, and **breathing rate**. Those three values are the only physiological
data the model receives, so the most effective prompts ask specific questions
about them. A prompt that asks the model to *measure* anything else has nothing
in the payload to ground an answer — but the prompt is free text, so you can also
supply extra context yourself (see [Add your own context](#add-your-own-context)). For the feature itself — concepts, the request/response model,
configuration, and privacy — see the [LLM Insights overview](index.md).

A good general-purpose starting point is a prompt that stays entirely within
the measured data:

> Summarize my current vital signs and flag anything unusual.

Use it as-is, or make it more specific to focus the response on a single metric.

## What works, and what doesn't

| Effective prompt | Why it works |
| --- | --- |
| ✅ "Summarize my current vital signs and flag anything unusual." | Asks only about the measured pulse, HRV, and breathing — exactly the data in the payload. |
| ✅ "Give me a plain-language summary of my heart-rate variability." | HRV is one of the three metrics sent. |
| ✅ "How do my pulse and breathing rate compare right now?" | Both metrics are in the payload, so the model can relate them. |
| ✅ "Point out any of my vital signs that stand out." | Pulse, HRV, and breathing are all sent; the model can look across them. |

| Ineffective prompt | Why it doesn't work |
| --- | --- |
| ❌ "What's my blood pressure, blood-oxygen, or temperature?" | The SDK never sends these — only pulse rate, HRV, and breathing rate leave the device. |
| ❌ "How does today compare to last week?" | Only the current session's rolling window is sent; there's no *measured* history — unless you [put the past values in the prompt](#add-your-own-context) yourself. |
| ❌ "How stressed or anxious am I?" | No emotional, mood, or activity signal is in the payload. |
| ❌ "Analyze my face" / "What do I look like?" | Raw video and facial imagery never leave the device — only the numeric metrics do. |
| ❌ "Do I have an arrhythmia? Should I see a doctor?" | Requests for medical diagnosis or advice are outside this feature's purpose — see the notice above. |

## Add your own context

The SDK only *measures* three metrics, but the prompt is free text — so you can
give the model context it has no other way to know, and it will factor that into
its answer. Recent sleep, activity, symptoms, medications, or a longer-term
baseline all work. For example:

> I only got 4 hours of sleep last night. Given that, how do my current vitals
> look?

Or, to compare against a longer-term baseline:

> My average resting pulse over the last 30 days has been about 110 bpm — is my
> pulse right now high or low for me?

The model treats whatever you add as given information: it can reason about it and
relate it to the live measurements. It can't verify it, though, and it won't turn
it into measured data — so keep the context accurate, and keep it health-related
(see [Keep in mind](#keep-in-mind)). Like the rest of the prompt, any context you
add is sent off-device to the Presage gateway — see the
[privacy notice](index.md#privacy--data-notice).

## Keep in mind

- **Wait for warm-up.** A request made before the metrics buffer has filled is
  sent **prompt-only**, with no physiology to ground it. Allow at least
  **15 seconds** of measurement (see
  [Required metrics configuration](index.md#required-metrics-configuration))
  before expecting a data-grounded answer, and up to about **60 seconds** for
  HRV to be part of it.
- **Keep prompts under the size limit.** A prompt is capped at **2048 bytes**
  (counted in bytes, so a non-ASCII character can use more than one). A prompt
  over the limit is rejected on-device, before the request is sent — shorten it,
  and trim any [context you add](#add-your-own-context) if it grows large.
- **Only three metrics are available.** Pulse rate, HRV, and breathing rate are
  the entire physiological surface a prompt can rely on.
- **Only the current session is in scope.** The buffered window covers the
  running session, not past ones — a prompt can't compare across days or
  separate measurements.
- **The assistant stays on your health data.** A server-side guardrail keeps it
  on task: it answers from the vitals and the context you provide, won't invent
  readings it wasn't given, and steers an off-topic prompt (say, "write me a
  poem") back to your health data. Keep any context you supply accurate and
  on-topic.
- **Not for medical use.** The model gives general-wellness commentary, not
  diagnosis or treatment advice; don't prompt for either.

## Getting Help

- Email: [support@presagetech.com](mailto:support@presagetech.com)
- [Submit a GitHub issue](https://github.com/Presage-Security/SmartSpectra/issues)
- [Docs and FAQ](https://smartspectra.presagetech.com)
- [Developer Admin Portal](https://physiology.presagetech.com/auth/login)