Skip to main content
Glama
Sign In

Webz.io Forums

by io.webz
OverviewDiscussionsAdmin

Search Webz Discussions

search_webz_discussions
Read-onlyIdempotent

Search forum posts and replies only (GET /api/forums, site type discussions).

A named site list is a q clause: custom_sites_list:ID. Example: custom_sites_list:SB_c41211dd. The field name is custom_sites_list. The list identifier is preserved exactly as supplied.

Forums do not have news category, topic, sentiment, trust, or entity filters.

Boolean query syntax is shared by news, blogs and forums. Unfielded terms match the post title, body and thread title. Spaces mean AND; AND, OR and NOT are uppercase. A leading minus means NOT. Parentheses group terms: (solar OR wind) storage. Quotes match exact phrases: "climate change". Proximity syntax "apple watch"~3 matches within 3 words, with at most 10 proximity operators. Prefix wildcards are supported (crypt*); leading wildcards are stripped. The $ suffix disables stemming (gold$) for English, Spanish, Arabic, Russian and French. Unbalanced quotes or parentheses return HTTP 400. Filters are field:value clauses within q. Values are case-insensitive; values with spaces are quoted. Unknown filter values can produce zero hits. Zero hits are a successful empty result, not an API error. Numeric and time filters support > and <, for example domain_rank:<1000 and published:>UNIX_MILLISECONDS. A language filter selects a language analyzer. Supported lowercase language names: afrikaans, albanian, amharic, arabic, armenian, azerbaijani, basque, belarusian, bengali, bulgarian, burmese, catalan, cherokee, chinese, chineset, croatian, czech, danish, dhivehi, dutch, english, estonian, finnish, french, galician, georgian, german, greek, gujarati, hebrew, hindi, hungarian, icelandic, indonesian, inuktitut, irish, italian, japanese, kannada, khmer, korean, kurdish, laothian, latvian, lithuanian, macedonian, malay, malayalam, maltese, norwegian, oriya, persian, polish, portuguese, punjabi, romanian, russian, serbian, sinhalese, slovak, slovenian, spanish, swahili, swedish, syriac, tagalog, tamil, telugu, thai, tibetan, turkish, ukrainian, urdu, vietnamese, welsh, yiddish.

Source filters inside q: site:cnn.com (domain), site_full:forums.example.com (exact host), site_suffix:co.uk, site_section:business, site_title:"morning post", section_title:sports, country:US (ISO-2; GB represents the United Kingdom), domain_rank:<1000 (1-1000000, lower is more popular), and site_category:tech (snake_case). Examples of site categories include tech, financial_news, world_soccer, travel, politics, health, music and real_estate. custom_sites_list:hot_sites matches the named site list using its supplied identifier.

Content filters, inside q: title:bitcoin, text:"supply chain", author:"jane doe", published:>UNIX_MS, crawled:>UNIX_MS, external_links:github.com.

Thread filters, inside q:

  • is_first:true returns only the opening post. is_first:false returns only replies.

  • replies_count:>10 is the number of replies on the thread.

  • participants_count:>5 is the number of distinct people on the thread.

  • rating:>4 is a 0 to 5 score on review-style posts.

Examples:

  • site:reddit.com language:english is_first:true

  • replies_count:>20 "electric vehicle" language:english

  • site:reddit.com is_first:false language:english "electric vehicle"

Separate tool arguments: size is 1-100, default 10; the API default is 100. Responses report total_results (match count) and more_results_available (unread matches). sort defaults to crawled; order defaults to asc for crawled, updated and domain_rank, and desc otherwise. crawled supports full-result pagination. days defaults to the last 3 days. ts is a Unix millisecond timestamp that overrides days and also serves as a pagination cursor. News history beyond 31 days requires allow_news_history=true and extra credits. highlight=true marks matched words in excerpts. include_syndicated=true includes syndicated copies (default false). webz_reporter=true includes Webz Reporter posts (default false); this is a separate argument, not a q filter. warning defaults to true. Subsequent pages use the returned ts, ni, ns and from_offset; ni and ns are opaque values. from_offset applies to non-crawled sorts.

The server rate limit is 3 requests per second per token and endpoint. total_results=0 with an empty posts array is a successful search with no matching content.

Reference documentation: Filters: https://docs.webz.io/docs/webz/forums-api-filters Query syntax: https://docs.webz.io/docs/webz/news-blogs-forums-query-syntax Parameters: https://docs.webz.io/docs/webz/news-blogs-forums-parameters Product: https://docs.webz.io/docs/webz/forums

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "q": "<q>"
    },
    "name": "search_webz_discussions"
  }
}

Input Schema

NameRequiredDescriptionDefault
qYesBoolean query with field:value filters. A space means AND; AND, OR and NOT are uppercase. A leading minus also means NOT (tesla -car). Quoted phrases and filter values may contain spaces, for example author:"jane doe". Examples: language:english site:cnn.com country:US. Language values are lowercase full names (hebrew); country values are ISO-2 (GB). Numeric comparisons use > or <, for example domain_rank:<1000. size, sort and days are separate tool arguments.
niNoOpaque next-page cursor returned by the preceding response.
nsNoOpaque next-page cursor returned by the preceding response.
tsNoWindow start or returned pagination timestamp in Unix milliseconds. Overrides days. Pagination uses the value returned in the preceding response.
daysNoLookback in days. The API default is 3; 7 is one week and 31 is the standard history limit. Ignored when ts is provided. Earlier news history requires allow_news_history=true and extra credits.
sizeNoPosts per page, 1-100; the tool default is 10 and the underlying API default is 100. total_results is the total match count. Returned cursors identify subsequent pages.
sortNoSort field. Default crawled supports pagination through the full result set and history. crawled, updated and domain_rank default to asc; other fields default to desc. Other values: relevancy, published, thread.published, performance_score, replies_count, participants_count, ord_in_thread, rating, social.facebook.likes, social.facebook.shares, social.facebook.comments, social.gplus.shares, social.pinterest.shares, social.linkedin.shares, social.stumbledupon.shares and social.vk.shares. Engagement and social sorts apply to news.crawled
orderNoasc or desc. When omitted, the API defaults to asc for crawled, updated and domain_rank, and desc for other sorts.
warningNoWhen true (default), the API returns query warnings without failing the search.
highlightNoWhen true, excerpts highlight the matched terms.
from_offsetNoReturned pagination offset for non-crawled sorts.
webz_reporterNoWhen true, include Webz Reporter posts. Default false. This is its own argument. webz_reporter:true inside q does not include those posts.
allow_news_historyNoEnables news history beyond 31 days with additional credit costs. News only.
include_syndicatedNoWhen true, include syndicated copies. Default false.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses a concrete server rate limit of 3 requests per second per token and endpoint, that unbalanced quotes/parentheses return HTTP 400, that unknown filter values can silently produce zero hits, and that opaque cursors (ni, ns, ts, from_offset) drive pagination. Credit-cost behavior for extended history is also stated.

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

Conciseness3/5

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

It is organized into labeled blocks (source filters, content filters, thread filters, examples) and leads with the core purpose, which is good. However, the ~70-item enumeration of language analyzer names is bulk that could have been summarized, and several sentences (news history credits, syndicated copies) are tangential to a forums-only tool, making the whole overly long relative to what an agent needs.

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 14-parameter, no-output-schema tool with a complex query DSL, it covers the query grammar, filter families, defaults and default mismatches (size 10 vs API 100), sort/order defaults, pagination mechanics, and even names the response fields total_results and more_results_available. An agent could call this correctly and paginate without further documentation.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema's q field does not carry: thread filters (is_first, replies_count, participants_count, rating), content filters (title, text, author, published, crawled, external_links), proximity/wildcard/stemming syntax, and worked examples. It also flags that webz_reporter must be a separate argument rather than a q clause, which prevents a likely misuse.

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?

Opens with a specific verb and resource plus an explicit scope limiter: "Search forum posts and replies only (GET /api/forums, site type discussions)." An agent immediately knows this targets discussion/forum content and nothing else, with the underlying endpoint named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear negative guidance — "Forums do not have news category, topic, sentiment, trust, or entity filters" — which tells an agent which filters will not work here, and it clarifies that zero hits are a valid empty result rather than an error. It never explicitly names a sibling or a "use this instead of X when..." rule (none exist), and it drifts into news-only concerns like allow_news_history, which muddies the when-to-use picture slightly.

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

All Webz.io Forums toolsInspect
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.

Resources