get_pain_signal

Returns full context for a single pain signal. The response opens with a “Market read”: the facts (owner diversity, rarity, score, trend) and how to weigh them. You make the build/don’t-build call from that context, the evidence, and your user’s situation.

Weight market breadth (distinct owners) over raw score. Most pains are a single product’s bug, not a market.

Parameters

Name	Type	Required	Description
id	string (UUID)	yes	Pain signal UUID
include	array of enum	no	Sections to include. Valid values: stats, whyNow, adjacent. Default: all three. Omit adjacent to reduce payload.
adjacentLimit	integer	no	Number of adjacent signals to return (1-10, default: 5)

Example call

{
  "name": "get_pain_signal",
  "arguments": {
    "id": "3f9a1c2d-8b4e-4f1a-9c2d-1e5a3b7f9c2e",
    "include": ["stats", "whyNow", "adjacent"]
  }
}

Lean call (stats only)

{
  "name": "get_pain_signal",
  "arguments": {
    "id": "3f9a1c2d-8b4e-4f1a-9c2d-1e5a3b7f9c2e",
    "include": ["stats"]
  }
}

Response sections

Signal detail

Core fields from the signal record:

Field	Description
id	Signal UUID
topic	LLM-generated topic label
summary	LLM-generated description
score	Composite pain score [0-100]
volume	Total mention count
growth	Growth rate
macroArea	Area bucket (e.g. AUTH_IDENTITY)
painType	Classification: bug, feature_request, complaint, or question
uniqueOwnerCount	Distinct GitHub owners (the key market-breadth signal)
topOwnerName	GitHub owner with the most chunks
topOwnerDominancePct	Share of chunks from the top owner
firstSeenAt	First mention timestamp
lastSeenAt	Most recent mention timestamp
metricsAsOf	When the nightly recompute last stamped the canonical metrics (volume + trend windows). Null for signals created after the last recompute

Stats section

Field	Description
totalMentions	All-time mention count (same canonical counter as volume)
last7dMentions	Mentions in the last trend window (persisted nightly — the same numbers list ranking uses)
prev7dMentions	Mentions in the prior trend window
growthRate	(last7d - prev7d) / max(prev7d, 1)
sourceDistribution	Breakdown by provider (GitHub, Stack Overflow, etc.)
metricsAsOf	Freshness stamp of the canonical metrics above

Why-now section

Field	Description
growthRate	Same as stats
drivers	List of deterministic growth drivers detected

Adjacent signals

Up to adjacentLimit signals semantically nearest to this one (by cosine similarity in the same macro area). Each includes id, topic, score, volume, growth, and similarity [0-1] — the real 1 - cosine distance between cluster centroids, directly comparable with search match percentages.

Market read

The response prefaces the data with a short “Market read” paragraph: facts about owner diversity, rarity, score, and trend, and how to interpret them for a build/don’t-build call. Use this as the starting point for your reasoning.