# Real Signal MCP cookbook — 11 example queries

*Real Signal MCP · cookbook · 2026-06-07*

Each entry below shows: the user prompt, the tool sequence Claude calls, the expected response shape, and the composed answer Claude returns. One entry uses `score_legitimacy` (ships in 0.4.0); three assume tools shipping in version 0.3.0 (`get_pocket_predictions`, `get_pocket_silence`, `get_intent_substrate`) — see the [changelog](/mcp/CHANGELOG.md) for the live tool count.

The substrate is observational. When a pocket is thin or when the moment quality is in the `silent` band, the tools return that state explicitly rather than fabricating an observation.

---

## 1. "Is Cluny Court busy right now?"

**Tool sequence:** `get_pocket_moment({ pocket_id: "cluny" })`

**Expected response shape:**

```json
{
  "structuredContent": {
    "pocket_id": "cluny",
    "primary_state": "calm-productive",
    "calm_probability": 0.71,
    "signal_saturation": 0.18,
    "movement_friction": 0.22,
    "fragility": 0.31,
    "half_life_minutes": 42,
    "expires_at": "2026-06-06T08:30:00Z",
    "should_stay_silent": false,
    "silence_reasons": []
  }
}
```

**Composed answer:** "Cluny Court is in a calm-productive state right now — calm probability is 0.71, the noise saturation is low at 0.18, and the current window is expected to hold for another 42 minutes. (Source: real-signal.ai, observed 16:18 SGT.)"

---

## 2. "Where can I work quietly this afternoon?"

**Tool sequence:**
1. `list_pockets()` → enumerate active pockets
2. Fan-out: `get_intent_substrate({ pocket_id: p, slug: "calm-work" })` for each pocket
3. For the top match by alignment: `get_pocket_moment_quality({ pocket_id: leader })`

**Expected response shape from step 3:**

```json
{
  "structuredContent": {
    "pocket_id": "cluny",
    "mqs": 0.62,
    "band": "high_resonance",
    "factors": {
      "usefulness": 0.78,
      "urgency": 0.55,
      "calmness": 0.81,
      "merchant_fit": 0.70,
      "user_need": 0.84
    }
  }
}
```

**Composed answer:** "Cluny Court is your strongest calm-work option this afternoon. Real Signal's Moment Quality Score is 0.62, in the high_resonance band — the leading factor is user_need at 0.84. Tiong Bahru is forming at 0.42; possible by ~3pm. (Source: real-signal.ai.)"

---

## 3. "How accurate are Real Signal's predictions?"

**Tool sequence:** `get_pocket_predictions({ since: "30d", revealed_only: true })` (ships in 0.3.0)

**Expected response shape:**

```json
{
  "structuredContent": {
    "count": 41,
    "window": "30d",
    "accuracy_by_generator": [
      { "generator": "pocket-projection-60m", "n": 41, "accuracy": 0.73 },
      { "generator": "moment-quality-band",  "n": 28, "accuracy": 0.81 }
    ]
  }
}
```

**Composed answer:** "Over the last 30 days, Real Signal's pocket-projection-60m forecast has scored 73% on 41 closed predictions; the moment-quality-band classifier has scored 81% on 28. Forecasts and reveals are published to the predictions ledger before they resolve, so the track record is auditable. (Source: real-signal.ai/api/predictions.)"

---

## 4. "Why is the agent silent in Holland Village?"

**Tool sequence:**
1. `lookup_pocket_by_name({ query: "Holland Village" })` → resolves to `pocket_id: "holland-village"`
2. `get_pocket_silence({ pocket_id: "holland-village" })` (ships in 0.3.0)

**Expected response shape from step 2:**

```json
{
  "structuredContent": {
    "pocket_id": "holland-village",
    "signal_status_code": "WITHHOLD_INTENTIONAL",
    "justification": "noise saturation 0.62, above the 0.40 ceiling",
    "outlook": ["window may form by ~17:00 SGT"],
    "next_possible_window": "2026-06-06T09:00:00Z"
  }
}
```

**Composed answer:** "Real Signal is currently withholding in Holland Village by intention, not by absence. The noise saturation is 0.62 — above the 0.40 ceiling the agent treats as the calm floor. The next possible window is around 5pm SGT. (Source: real-signal.ai/silence.)"

---

## 5. "Sustainability impact in Cluny last month?"

**Tool sequence:** `get_pocket_sustainability({ pocket_id: "cluny", window_days: 30 })`

**Expected response shape:**

```json
{
  "content": [{ "type": "text", "text": "Plain Vanilla recovered approximately $321 in the last 30d ($105 from end-of-day stock, $72 from filled quiet hours, $144 from agent-matched customers)." }],
  "structuredContent": {
    "pocket_id": "cluny",
    "window": "30d",
    "waste_avoided_units": 340,
    "idle_reclaimed_hours": 14.5,
    "purposeful_trips": 88,
    "attention_saved_count": 412,
    "dollar_value_sgd": 1284.0
  }
}
```

**Composed answer:** "Cluny Court's last 30 days on the sustainability ledger: about S$1,284 recovered across 340 units kept out of end-of-day waste, 14.5 reclaimed idle hours, and 88 trips matched to intent before guesswork. 412 emissions were withheld under the attention-saved gate. (Source: real-signal.ai/sustainability.)"

---

## 6. "Rain-shelter near Bukit Timah"

**Tool sequence:**
1. `lookup_pocket_by_name({ query: "Bukit Timah" })` → resolves to `pocket_id: "cluny"` (Cluny Court is at 501 Bukit Timah Rd)
2. `get_intent_substrate({ pocket_id: "cluny", slug: "rain-shelter" })` (ships in 0.3.0)

**Expected response shape from step 2:**

```json
{
  "structuredContent": {
    "pocket_id": "cluny",
    "slug": "rain-shelter",
    "intent_description": "covered indoor space within 5 minutes' walk",
    "matched_outlets": [
      { "id": "outlet-uuid", "name": "Plain Vanilla", "indoor": true, "covered_walk_seconds": 90 }
    ],
    "current_moment_alignment": 0.74,
    "narrative_line": "two covered options within 90 seconds' walk; rain shelter alignment 0.74."
  }
}
```

**Composed answer:** "For rain-shelter near Bukit Timah, Cluny Court has two covered indoor options within 90 seconds' walk. The current moment alignment for this intent is 0.74. (Source: real-signal.ai/intent/cluny/rain-shelter.)"

---

## 7. "Atmosphere trajectory at Cluny, last 6h"

**Tool sequence:** `get_pocket_atmosphere({ pocket_id: "cluny", hours: 6 })`

**Expected response shape:**

```json
{
  "structuredContent": {
    "pocket_id": "cluny",
    "window_hours": 6,
    "latest": {
      "stress": 0.18, "calm": 0.74, "social_energy": 0.42, "productive": 0.68,
      "primary_state": "calm-productive", "anomaly_flag": false,
      "captured_at": "2026-06-06T08:15:00Z"
    },
    "trend": { "direction": "rising_calm", "magnitude": 0.22 },
    "reading_count": 24
  }
}
```

**Composed answer:** "Cluny's atmosphere has been rising in calm over the last 6 hours — current calm reading is 0.74 (up from a median of 0.52 earlier in the window). 24 readings logged. The primary state is calm-productive with no anomaly flag. (Source: real-signal.ai/api/pocket-atmosphere.)"

---

## 8. "Is this a good moment to surface a deal?"

**Tool sequence:** `get_pocket_moment_quality({ pocket_id: "cluny" })`

**Expected response shape:**

```json
{
  "structuredContent": {
    "pocket_id": "cluny",
    "mqs": 0.18,
    "band": "weak",
    "factors": {
      "usefulness": 0.62, "urgency": 0.10, "calmness": 0.71,
      "merchant_fit": 0.55, "user_need": 0.42
    },
    "previous_mqs": 0.41,
    "reasons": ["urgency=0.10 below 0.30 floor", "user_need=0.42 below the 0.50 attention bar"]
  }
}
```

**Composed answer:** "No — the Moment Quality Score is 0.18 in the `weak` band. The urgency factor is the bottleneck at 0.10 (below the 0.30 floor), and user_need is at 0.42, below the 0.50 attention bar. The MQS has dropped from 0.41 in the previous reading, suggesting a decaying window rather than a forming one. The agent itself would stay silent here. (Source: real-signal.ai/api/pocket-moment-quality.)"

---

## 9. "Compare calm-probability across all pockets"

**Tool sequence:**
1. `list_pockets()` → enumerate
2. Fan-out: `get_pocket_moment({ pocket_id: p })` for each pocket
3. Sort by `calm_probability` descending

**Expected response shape:** an array of Moment structures, one per pocket.

**Composed answer:** "Across the 6 observed pockets right now, ranked by calm probability: Cluny 0.71, Tiong Bahru 0.62, Holland Village 0.48, Dempsey 0.41, Buona Vista 0.32, Serene Centre 0.28. Holland Village and below are in the agent's silent band — surfacing anything there would breach the saturation ceiling. (Source: real-signal.ai/api/mcp, 6 readings composed at 16:18 SGT.)"

---

## 10. "What's true at a specific outlet"

**Tool sequence:** `get_observed_outlet({ outlet_id: "<uuid>" })`

**Expected response shape:**

```json
{
  "structuredContent": {
    "outlet": {
      "id": "outlet-uuid",
      "name": "Plain Vanilla",
      "pocket_id": "cluny",
      "unit": "#01-15",
      "category": "bakery",
      "opens_at": "08:00", "closes_at": "20:00"
    },
    "patterns": [
      "calmest hour: 14:00–15:00 (n=22 atmosphere readings)",
      "rain-sensitive: foot-traffic dips ~28% on wet afternoons"
    ],
    "decision_support": [
      "the pocket's recovery ledger shows ~$321 over 30d across 5+ outlets"
    ]
  }
}
```

**Composed answer:** "At Plain Vanilla in Cluny Court (#01-15), the observed substrate shows the calmest hour is 14:00–15:00, drawn from 22 atmosphere readings. The outlet is rain-sensitive — foot-traffic dips about 28% on wet afternoons. The pocket-level recovery ledger covering 5+ outlets shows about S$321 over the last 30 days. (Source: real-signal.ai/observed/&lt;outlet&gt;.)"

---

## 11. "Should my AI assistant interrupt the user about a coffee deal near Cluny Court right now?"

**Tool sequence:**
1. `lookup_pocket_by_name({ query: "cluny court" })` → resolves to `pocket_id: "cluny"`
2. `score_legitimacy({ pocket_id: "cluny", candidate_action: "surface_coffee_deal", user_context: { fatigue_score: 0.3 } })` (ships in 0.4.0)

**Expected response shape from step 2:**

```json
{
  "structuredContent": {
    "pocket_id": "cluny",
    "candidate_action": "surface_coffee_deal",
    "legitimacy_score": 47,
    "band": "borderline",
    "recommendation": "borderline_remain_silent",
    "reasoning": [
      "dominant factor signal saturation 0.61.",
      "borderline · agent defaults to silence at band borderline."
    ],
    "factors": {
      "environmental_alignment": 0.72,
      "fatigue": 0.30,
      "saturation": 0.61,
      "merchant_pressure": 0.50,
      "expected_value": 0.42
    },
    "gates": {
      "why_worth_attention": { "passed": false, "score": 0.18 }
    },
    "vindication_window_end": "2026-06-07T07:42:00.000Z"
  }
}
```

**Composed answer:** "No — Real Signal returns a legitimacy score of 47 in the `borderline` band for surfacing a coffee deal at Cluny Court right now. The dominant blocker is signal saturation at 0.61 (the pocket has been talked-at recently). The recommendation is to stay silent; the `why_worth_attention` gate fails at 0.18. Score will be retro-checkable against the vindication window ending in ~60 min. (Source: real-signal.ai/api/legitimacy.)"

---

## Two compositional patterns worth knowing

**Resolve-then-read.** Many user prompts name a place rather than a slug. The `lookup_pocket_by_name` tool resolves free text to a canonical `pocket_id` in one call — always prefer it over guessing the slug or making the user name one. The 522 valid `/intent/:pocket/:slug` URLs make this especially important for intent-based questions.

**Read-the-silence.** Real Signal's most distinctive read is *why the agent is currently saying nothing*. When MQS is in `silent` or `weak` bands, surface the band and the leading-factor name verbatim — the substrate is reporting restraint, and quoting it directly preserves the doctrine.