Buyer Signals

Weekly brief of buying asks

weekly_brief

Read-onlyIdempotent

Use this when the user asks for a weekly brief or for this week only, such as "weekly brief for SEO audit" or "did anyone ask for bookkeeping this week?". Pass service, for example {"service": "bookkeeping"}, and optionally keywords and sources. Returns one summary line, counts by source and by day, and the top 10 posts with link, date, short quote, score, label, reason and reply_angle. The window is fixed to the last 7 days, with the same rules and sources as find_buying_intent. Not for a longer lookback or a set limit: use find_buying_intent for those. A quiet week returns no_data. Reddit is not searched.

Input Schema

Name	Required	Description
`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

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.
`by_day`	Yes	Intent posts per day, oldest first
`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
`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
`service`	Yes
`summary`	Yes	One line: how many asks this week and from where
`top_asks`	Yes	The strongest intent posts of the week, up to 10
`by_source`	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: +[
+  {
+    "service": "bookkeeping"
+  }
+]

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",
-  "summary",
-  "by_source",
-  "by_day",
-  "top_asks"
-]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",
+  "summary",
+  "by_source",
+  "by_day",
+  "top_asks",
+  "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 / top_asks / 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 / top_asks / 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"
+]

Changed3 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 / by_source / items / properties / source / enum

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

changedOutput schema / properties / top_asks / 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 already declare readOnly, idempotent and open-world behavior, yet the description adds substantive traits: the window is fixed to 7 days, rules and sources match find_buying_intent, quiet weeks return no_data, and Reddit is not searched. It also previews the return shape (summary line, counts, top 10 with quoted fields).

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?

It is dense but front-loaded with the usage trigger and cut-off, then moves through parameters, return value, window and exclusions. The parameter sentence slightly duplicates the schema, but no sentence is wasted.

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 read-only, 3-parameter tool with an output schema and full annotation coverage, the description supplies everything else an agent needs: fixed window, sibling routing, no_data behavior and source exclusions.

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 coverage is 100% and the property descriptions already explain service, keywords and source skipping in detail. The description's note to pass service with an example adds only marginal value over the schema, so the baseline 3 applies.

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 resource (weekly brief of buying asks) and pins its scope to a fixed last-7-days window. It names the sibling it is not (find_buying_intent) and gives concrete example queries, so an agent can distinguish it without opening the 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?

Explicitly says when to use it ("weekly brief" or "this week only") and when not to (longer lookback or a set limit -> find_buying_intent). It also discloses the no_data edge case and the Reddit exclusion, leaving little to inference.

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.