Skip to main content
Glama
NewsCatcher MCP

NewsCatcher MCP

Official

List matching articles

list_articles
Read-onlyIdempotent

Lists every article matching a boolean query over the last 12 months, newest first, with exact counts, paging, and tallies by outlet, author, country or language.

Instructions

List EVERY article that matches a boolean query over the last 12 months, newest first, with an exact total count, paged (up to 1,000 per query). Use it for completeness and counting: "how many articles mention X", "all coverage of Y since October", older news beyond 30 days, monitoring checklists, exports. tally counts matches by outlet, author, country or language (who covers a topic). Precise keyword/boolean matching, not relevance ranking: for the best answers to a question use search_news. 5 credits per call.

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": {
      "query": "<query>"
    },
    "name": "list_articles"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoEnd: ISO date/time or phrase. Default: now. When paging, pass the window end from the first page so every page covers the same articles.
fromNoStart: ISO date/time ("2026-10-01") or a phrase ("30 days ago"). Default: 7 days ago. Up to 12 months back.
pageNoPage number, from 1. page × page_size can reach the first 1,000 articles of a query.
sortNoOrder: newest (default), oldest, relevance, or source_rank (biggest publishers first).newest
queryYesBoolean query: AND, OR, NOT, parentheses, "exact phrases", +must, -mustnot, wild*cards, NEAR("a", "b", 5). Example: "Nvidia" AND (earnings OR guidance) NOT "stock split".
tallyNoInstead of listing, count the matching articles by outlet, author (bylines that are people), country and/or language, in one pass: e.g. ["source","country","language"]. Outlets and authors come with their latest article. Who covers a topic, media lists, coverage mix.
formatNotext (default, compact) or json (machine-readable).text
sourcesNoOnly these publishers: domains, e.g. ["reuters.com","ft.com"].
countriesNoOnly publishers from these countries: ISO 3166-1 alpha-2 codes, e.g. ["US","GB"].
languagesNoOnly these languages: ISO 639-1 codes, e.g. ["en","de"].
min_wordsNoOnly articles with at least this many words.
page_sizeNoArticles per page (default 20, up to 100).
search_inNoWhere the query is matched (default title_body). *_translated fields match the English translation of non-English articles.
count_onlyNoReturn only the exact number of matching articles (no list).
tally_pagesNoWith tally: pages of 100 newest articles to count (default 3; 5 credits each).
top_sourcesNoOnly the best-ranked publishers: "top <n> <country code>" or "top <n> global", e.g. "top 100 US" or "top 50 global".
exclude_sourcesNoLeave out these publishers (domains).
max_source_rankNoOnly publishers ranked at or better than this traffic rank (1 = biggest).
exclude_countriesNoLeave out publishers from these countries (ISO 3166-1 alpha-2).
exclude_languagesNoLeave out these languages (ISO 639-1).
exclude_duplicatesNoLeave out syndicated copies of an article.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already establish read-only, open-world, idempotent, so the description earns credit for adding what annotations cannot: the hard 12-month lookback limit, the 1,000-article paging ceiling per query, and explicit pricing (5 credits per call, 5 credits per tally page). Those are the operational constraints an agent needs before deciding whether this call is appropriate.

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 verb, resource, and the exhaustive/ranked distinction, and every clause carries information. Slight redundancy: the tally capability is described in the prose and then again in the tally parameter description, and the tail-end use-case list ('monitoring checklists, exports') is a little scattershot.

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

Completeness4/5

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

For a 21-parameter tool with no output schema, the description covers purpose, alternatives, cost, paging cap, and the tally/count modes, which is most of what an agent needs. It is somewhat thin on what a returned article actually contains and on how paging interacts with the total count, so completeness is good rather than exhaustive.

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; the description still adds interpretive value by framing tally as a substitute for listing ('tally counts matches by outlet, author, country or language'), tying the default sort to 'newest first', and tying the 'since October' example to the lookback window. It does not restate field syntax, which the schema already handles well.

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 (list articles matching a boolean query), plus defining scope: exhaustive matching, 12-month window, newest-first, exact total count, paged to 1,000. It explicitly distinguishes itself from the relevance-ranked sibling by name ('for the best answers to a question use search_news'), so an agent can choose it 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?

Gives concrete when-to-use conditions ('completeness and counting', 'older news beyond 30 days', monitoring checklists, exports) with sample natural-language questions, and names the alternative (search_news) with the condition that selects it. It also flags the tally mode as the right choice for 'who covers a topic' instead of listing.

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