Buyer Signals

Find people asking for a service

find_buying_intent

Read-onlyIdempotent

Use this when the user sells a service and wants public posts where people ask for it, such as "who is asking for an SEO audit?", "find posts from people looking for a bookkeeper" or "which companies on Hacker News are hiring for MCP work?". Pass service, for example {"service": "SEO audit"}, and optionally keywords, sources, lookback_days (7 to 365, default 30) and limit (1 to 15, default 10). Returns Hacker News posts, company posts from the newest "Who is hiring?" thread, GitHub issues and Stack Exchange posts, each with a link, date, quote under 15 words, intent score 0 to 100, label (intent or casual_complaint), one-line reason, reply_angle and lead_source. Plain rules, no AI model. Use this, not weekly_brief, for a lookback other than 7 days or a set limit. Not for companies that raised money (use find_buyer_signals) or for finding who wrote a post. A post that reads like a buyer is a lead to read, not a sure sale. No usernames, profiles or contact details. Reddit is not searched.

Input Schema

Name	Required	Description
`limit`	No	How many posts to return (default 10)
`service`	Yes	The service you sell, not a company or person. Example call: {"service": "SEO audit"}. "alternative" alone, with no keywords, finds asks to replace any tool. Also try the person form (bookkeeper)
`sources`	No	Which public sources to read: hackernews (comments and Ask HN), hn_hiring (company posts in the newest monthly Hacker News "Who is hiring?" thread), github (open and closed issues) and stackexchange. Default is all four. Leave one out to skip it, for example stackexchange when it is rate limited
`keywords`	No	Optional extra words a post must also contain, such as "shopify" or "small business" (up to 5). Every keyword must appear in a post, so a long list returns little. Leave it out for a first look and add one word only to narrow
`lookback_days`	No	How many days of posts to read (default 30). This is 7 to 365, not the 1 to 60 of find_buyer_signals or the 30 to 365 of stack_pains

Output Schema

Name	Required	Description
`note`	Yes
`as_of`	Yes	ISO 8601 time the data was published by its source or fetched from it. A cached answer keeps the time of its fetch.
`notice`	Yes	What a score does and does not mean. Pass it on
`reddit`	Yes
`source`	Yes	Who the data comes from, to cite and to check it against.
`status`	Yes	ok: posts found. no_data: no post asked for the service; message says what to try. unavailable: no source could be read; message says whether to retry or skip stackexchange
`window`	Yes
`dropped`	Yes	Posts left out: seller posts and posts that ask for nothing
`message`	No	The next step when status is not ok or a source was skipped, such as a longer lookback_days, the person form of the service, or leaving stackexchange out of sources
`results`	Yes
`service`	Yes
`how_scored`	Yes	The scoring rules, so the user can see why a post scored as it did
`posts_read`	Yes	Posts read from all sources
`attribution`	Yes	CC BY-SA attribution for Stack Exchange text
`intent_count`	Yes	Posts labelled intent
`sources_used`	Yes	Sources read for this answer
`complaint_count`	Yes	Posts labelled casual_complaint
`untrusted_source`	Yes
`posts_about_service`	Yes	Posts that name the service
`sources_unavailable`	Yes	Sources that could not be read and are missing from the answer

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedOct 23, 2026

addedInput schema / examples

Added value: +[
+  {
+    "lookback_days": 30,
+    "service": "SEO audit"
+  }
+]

changedOutput schema / properties / as_of / description

Previous value: -"Date of this answer (UTC, YYYY-MM-DD)"New value: +"ISO 8601 time the data was published by its source or fetched from it. A cached answer keeps the time of its fetch."

addedOutput schema / properties / note
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / source

Added value: +{
+  "description": "Who the data comes from, to cite and to check it against.",
+  "properties": {
+    "name": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "name",
+    "url"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / untrusted_source
```
Added value: +{
+  "type": "boolean"
+}
```

changedOutput schema / required

Previous value: -[
-  "status",
-  "service",
-  "posts_read",
-  "posts_about_service",
-  "intent_count",
-  "complaint_count",
-  "sources_used",
-  "sources_unavailable",
-  "reddit",
-  "attribution",
-  "how_scored",
-  "as_of",
-  "notice",
-  "window",
-  "dropped",
-  "results"
-]New value: +[
+  "status",
+  "service",
+  "posts_read",
+  "posts_about_service",
+  "intent_count",
+  "complaint_count",
+  "sources_used",
+  "sources_unavailable",
+  "reddit",
+  "attribution",
+  "how_scored",
+  "as_of",
+  "notice",
+  "window",
+  "dropped",
+  "results",
+  "untrusted_source",
+  "note",
+  "source"
+]

AddedOct 11, 2026
RemovedOct 10, 2026

Changed3 schema fields changedOct 8, 2026

changedInput schema / properties / keywords / description

Previous value: -"Optional extra words a post must also contain, such as \"shopify\" or \"small business\" (up to 5). Every keyword must appear in a post, so a long list returns little"New value: +"Optional extra words a post must also contain, such as \"shopify\" or \"small business\" (up to 5). Every keyword must appear in a post, so a long list returns little. Leave it out for a first look and add one word only to narrow"

addedOutput schema / properties / results / items / properties / reply_angle

Added value: +{
+  "description": "One line on what to reply. It never names the tool or the subject, so open the link to read it. Picked by rule from the strongest cue: thanks (check the thread first), a budget, a hire, a named friction, an alternative, a recommendation, or a complaint with no ask",
+  "type": "string"
+}

changedOutput schema / properties / results / items / required

Previous value: -[
-  "rank",
-  "source",
-  "url",
-  "date",
-  "quote",
-  "intent_score",
-  "label",
-  "reason",
-  "signals"
-]New value: +[
+  "rank",
+  "source",
+  "url",
+  "date",
+  "quote",
+  "intent_score",
+  "label",
+  "reason",
+  "signals",
+  "reply_angle"
+]

Changed2 schema fields changedOct 6, 2026

addedInput schema / properties / sources

Added value: +{
+  "description": "Which public sources to read: hackernews (comments and Ask HN), github (open and closed issues) and stackexchange. Default is all three. Leave one out to skip it, for example stackexchange when it is rate limited",
+  "items": {
+    "enum": [
+      "hackernews",
+      "github",
+      "stackexchange"
+    ],
+    "type": "string"
+  },
+  "maxItems": 3,
+  "minItems": 1,
+  "type": "array"
+}

changedOutput schema / properties / results / items / properties / source / enum

Previous value: -[
-  "hackernews",
-  "stackexchange"
-]New value: +[
+  "hackernews",
+  "github",
+  "stackexchange"
+]

AddedOct 5, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only carry the safety profile (readOnly, non-destructive), and the description adds materially: it discloses which sources are read, that ranking is 'plain rules, no AI model', that no usernames or contact details are returned, that Reddit is excluded, and that an intent match is a lead rather than a confirmed sale. That is exactly the kind of accuracy and coverage context annotations cannot express.

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?

Front-loaded with the usage condition and examples, which is right, and every sentence is content-bearing apart from the duplicated parameter ranges and the enumeration of return fields when an output schema already exists. Dense but slightly long for a single paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter read tool with an output schema, the description covers trigger, alternatives, source coverage, ranking mechanism, privacy constraints and the false-positive caveat — there is nothing an agent needs to decide whether and how to call it that is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the parameter descriptions are already unusually instructive (person-form service, keyword narrowing advice, source skipping under rate limits), so the description's restatement of 'lookback_days (7 to 365, default 30)' and 'limit (1 to 15, default 10)' adds nothing. Baseline 3 applies; the description neither compensates for a gap nor expands meaning.

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?

States a specific verb and resource — returning public posts where people ask for a service the user sells — with three concrete example queries. It also explicitly separates itself from siblings (not weekly_brief, not find_buyer_signals), so an agent can route without opening any schema.

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?

Opens with an explicit trigger condition ('when the user sells a service and wants public posts where people ask for it'), then names the alternatives and the conditions that select them: use this over weekly_brief for a non-7-day lookback or a set limit, and use find_buyer_signals for funded companies. Exclusions (not for finding post authors) are stated outright.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Buyer Signals 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.