Skip to main content
Glama

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. Free, no key: 4 lookups a day per network, shared with find_buying_intent, reset at 00:00 UTC; a repeat within 6 hours comes from the cache and counts nothing.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "service": "bookkeeping"
    },
    "name": "weekly_brief"
  }
}

Input Schema

NameRequiredDescriptionDefault
serviceYesThe 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)
sourcesNoWhich 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
keywordsNoOptional 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

NameRequiredDescriptionDefault
noteYes
as_ofYesISO 8601 time the data was published by its source or fetched from it. A cached answer keeps the time of its fetch.
by_dayYesIntent posts per day, oldest first
noticeYesWhat a score does and does not mean. Pass it on
redditYes
sourceYesWho the data comes from, to cite and to check it against.
statusYesok: 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
windowYes
messageNoThe next step when status is not ok, a source was skipped or there are fewer than 3 results: the sources searched, then a longer lookback_days, the person form of the service, a source that fits and was not read, or leaving stackexchange out of sources
serviceYes
summaryYesOne line: how many asks this week and from where
top_asksYesThe strongest intent posts of the week, up to 10
by_sourceYes
how_scoredYesThe scoring rules, so the user can see why a post scored as it did
posts_readYesPosts read from all sources
attributionYesCC BY-SA attribution for Stack Exchange text, or a line saying the answer holds none
intent_countYesPosts labelled intent
sources_usedYesSources read for this answer
company_leadsNoFilings and listings found by job_changes and partners; they are companies, not posts, so posts_read leaves them out
complaint_countYesPosts labelled casual_complaint
untrusted_sourceYes
posts_about_serviceYesPosts that name the service
sources_unavailableYesSources that could not be read and are missing from the answer

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changed
    • changedOutput schema / properties / attribution / description
      Previous value: -"CC BY-SA attribution for Stack Exchange text"New value: +"CC BY-SA attribution for Stack Exchange text, or a line saying the answer holds none"
    • addedOutput schema / properties / company_leads
      Added value: +{
      +  "description": "Filings and listings found by job_changes and partners; they are companies, not posts, so posts_read leaves them out",
      +  "type": "integer"
      +}
    • changedOutput schema / properties / message / description
      Previous value: -"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"New value: +"The next step when status is not ok, a source was skipped or there are fewer than 3 results: the sources searched, then a longer lookback_days, the person form of the service, a source that fits and was not read, or leaving stackexchange out of sources"
    • addedOutput schema / properties / top_asks / items / properties / company
      Added value: +{
      +  "description": "The company: for hn_hiring the one the post names in its first line, for job_changes the filer, for partners the plugin",
      +  "type": "string"
      +}
    • changedOutput schema / properties / top_asks / items / properties / quote / description
      Previous value: -"A quote of the ask under 15 words; for job_changes the filer and the former customer it names, for partners the listing's own summary"New value: +"A quote of the ask under 15 words; for hn_hiring the first whole sentence that names the service, else the clauses that name it with … where cut, else the post's first line; for job_changes the filer and the former customer it names, for partners the listing's own summary"
    • addedOutput schema / properties / top_asks / items / properties / role
      Added value: +{
      +  "description": "hn_hiring: the role the post names in its first line, when it names one",
      +  "type": "string"
      +}
    • addedOutput schema / properties / top_asks / items / properties / stack
      Added value: +{
      +  "description": "hn_hiring: products and languages the post names, such as Python or AWS, in the order named",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
  2. Changed9 schema fields changed
    • changedOutput schema / properties / top_asks / items / properties / date / description
      Previous value: -"Day the post was made (YYYY-MM-DD)"New value: +"Day the post or filing was made, or the listing last updated (YYYY-MM-DD)"
    • addedOutput schema / properties / top_asks / items / properties / label / description
      Added value: +"intent or casual_complaint for a post; job_change for an officer change naming a former customer; partner_fit for a partner listing"
    • changedOutput schema / properties / top_asks / items / properties / label / enum
      Previous value: -[
      -  "intent",
      -  "casual_complaint"
      -]New value: +[
      +  "intent",
      +  "casual_complaint",
      +  "job_change",
      +  "partner_fit"
      +]
    • changedOutput schema / properties / top_asks / items / properties / lead_source / description
      Previous value: -"Which buying-signal source this lead is, to store with the lead: hiring-for-supported-roles (a company job post), tool-recommendation-asks (asks for a pick or an alternative), solution-complaints (only complains), community-questions (any other ask)"New value: +"Which buying-signal source this lead is, to store with the lead: hiring-for-supported-roles (a company job post), tool-recommendation-asks (asks for a pick or an alternative), solution-complaints (only complains), community-questions (any other ask), former-customers-moved (job_changes) or partnerships (partners)"
    • changedOutput schema / properties / top_asks / items / properties / lead_source / enum
      Previous value: -[
      -  "tool-recommendation-asks",
      -  "solution-complaints",
      -  "hiring-for-supported-roles",
      -  "community-questions"
      -]New value: +[
      +  "tool-recommendation-asks",
      +  "solution-complaints",
      +  "hiring-for-supported-roles",
      +  "community-questions",
      +  "former-customers-moved",
      +  "partnerships"
      +]
    • changedOutput schema / properties / top_asks / items / properties / quote / description
      Previous value: -"A quote of the ask, under 15 words"New value: +"A quote of the ask under 15 words; for job_changes the filer and the former customer it names, for partners the listing's own summary"
    • changedOutput schema / properties / top_asks / items / properties / source / description
      Previous value: -"Where the post is: hackernews, hn_hiring (the monthly hiring thread), github or stackexchange"New value: +"Where the lead is: hackernews, hn_hiring (the monthly hiring thread), github, stackexchange, job_changes (an SEC 8-K) or partners (a WordPress.org listing)"
    • changedOutput schema / properties / top_asks / items / properties / source / enum
      Previous value: -[
      -  "hackernews",
      -  "hn_hiring",
      -  "github",
      -  "stackexchange"
      -]New value: +[
      +  "hackernews",
      +  "hn_hiring",
      +  "github",
      +  "stackexchange",
      +  "job_changes",
      +  "partners"
      +]
    • changedOutput schema / properties / top_asks / items / properties / url / description
      Previous value: -"Link to the post. For Stack Exchange this link is also the CC BY-SA attribution"New value: +"Link to the post, filing or listing. For Stack Exchange this link is also the CC BY-SA attribution"
  3. Changed6 schema fields changed
    • 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"
      +]
  4. Added
  5. Removed
  6. Changed3 schema fields changed
    • 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"
      +]
  7. Changed3 schema fields changed
    • 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"
      +]
  8. Added

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open world), and the description adds substantial behavior beyond them: a fixed 7-day window, the no_data outcome for a quiet week, that Reddit is not searched, the rate limit (4 lookups/day per network, shared with find_buying_intent, reset at 00:00 UTC) and the 6-hour cache that consumes no quota. This is exactly the context an agent needs before promising results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the trigger condition, then the call shape, then the return payload, then exclusions, then edge cases and limits. The final sentence is dense but every clause (quota, shared limit, reset time, cache) is operationally relevant, so nothing 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?

An output schema exists, yet the description still summarizes the return payload in agent-usable terms (summary line, counts by source/day, top 10 with link, quote, score, label, reason, reply_angle), plus the empty-result case. Combined with the quota and window constraints, nothing an agent needs to call this correctly 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%, so service, sources and keywords are already fully documented in the schema, including the conjunctive keyword behavior and the enum values. The description adds only the call shape ('Pass service ... optionally keywords and sources'), which is marginal value over structured data. Baseline 3 is appropriate.

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?

The description states a specific verb and resource ('weekly brief' over the last 7 days of buying asks) and immediately contrasts it with the sibling that covers other cases ('Not for a longer lookback or a set limit: use find_buying_intent'). An agent can distinguish weekly_brief from find_buying_intent without opening either 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?

It gives concrete trigger phrasing ('weekly brief for SEO audit', 'did anyone ask for bookkeeping this week?'), states the negative condition (longer lookback, set limit) and names the alternative tool for those cases. That is explicit when/when-not/alternative coverage.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.