Input schema (JSON)
{
"type": "object",
"properties": {
"q": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional search terms, matched case-insensitively against the story's headline, one-liner, abstract, and named actors (no article body text, no stemming). Space-separated words are ANDed, so ALWAYS quote a multi-word phrase: `layoffs OR \"workforce reduction\"` works, `layoffs OR workforce reduction` is read as a mix of AND/OR and rejected. Supports AND/OR/NOT (aliases &&, ||, !), ( ) grouping, and `*` wildcards. NEAR() and MULTIPLE() are NOT supported here — they are silently read as ordinary words instead of erroring, so never use them. Omit q entirely for a filter-only digest (\"banking news today\" needs no q at all)."
},
"sort": {
"anyOf": [
{
"enum": [
"newsrooms",
"trending",
"relevance",
"last_seen",
"first_seen",
"size",
"source_count",
"confidence"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "What \"best\" means for this call. **Omit it** unless the user asked for a specific ordering: the API then picks `relevance` when `q` or `subject` is set and `newsrooms` when neither is, which is almost always right. Forcing `newsrooms` on a keyword search ranks by story size rather than match, so `subject=\"Bank of America\"` returns \"India Now Asia's Least Preferred Stock Market\" ahead of \"Bank of America Warns of European Stock Decline\" — big stories that merely mention the words. `newsrooms`: most independently-corroborated first. `trending`: corroboration weighted by freshness on an 8-hour half-life — the one for \"what is blowing up right now\". `relevance`: best semantic match to q first, and REQUIRES q. `last_seen`: most recently active. `first_seen`: most recently started. `size`: most articles. `source_count`: most publisher domains, mirrors included. `confidence`: highest label confidence, unlabeled last regardless of order."
},
"from_": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive lower bound on when the story BEGAN (its first_seen) — NOT the publish date of any one article, so a story still running today but started last week falls outside the default window. ISO 8601 (`2026-07-01T00:00:00`) or a relative phrase (`now-6h`, `2 days ago`, `yesterday`); all dates are UTC. Default: 24 hours ago, much narrower than a general news search — widening this is the FIRST thing to try when a query that should match something returns nothing — but the lookback is capped: 7 days keyless (narrowed with a notice), and per-plan with a key (14 days on the free tier today, rejected rather than narrowed). `check_limits` reports the caller's live ceiling."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 50,
"minimum": 1,
"description": "Stories per page, 1–50, default 20, but capped for the caller: keyless 20 (softly, with a notice), and per-plan with a key (50 on the free tier today, over it is a validation error naming the maximum). `check_limits` reports the live cap. Raise it when the user asks for breadth — one call with a a flat ceiling rather than a page size: there is no paging past it, since the hourly call budget is the scarce resource (keyless 20/hour, 50/hour on the free tier)."
},
"sector": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Industry the story belongs to. Comma-separated for OR (`software_it_services,semiconductors` = \"tech and chips\"). One of: government_public_sector, media_entertainment, financial_services, healthcare_pharma, energy_utilities, retail_consumer, real_estate, agriculture_food, telecommunications, automotive, manufacturing_industrial, transport_logistics, aerospace_defense, mining_metals, construction_infrastructure, education, hospitality_travel, sports_recreation, nonprofit_ngo, legal_services, insurance, software_it_services, ecommerce, banking, defense_security, chemicals, fashion_apparel, gaming_esports, biotechnology, semiconductors, other_sector."
},
"api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional NewsMCP API key for this call; forwarded upstream as x-api-key. Keyless: 7-day `from_` lookback, 20 calls/hour (shared per network address), 20 stories per call — over-limit requests are narrowed with a notice, not rejected. With a key the ceilings come from the plan (free tier today: 14 days, 50 calls/hour, 50 stories) and over-limit requests are rejected with a validation error instead of narrowed. Those per-plan numbers change without a release — call `check_limits` for the live values and the hourly budget left; it costs nothing. A keyed caller may have only one request in flight at a time, so never call in parallel."
},
"subject": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A single company, person, place, or organisation to centre the search on — plain name, no quoting. Quoted for you, which is the difference between a phrase and a bag of words: `Bank of America` unquoted ANDs three common terms and surfaces \"Medtronic Revenue Grows\" first, while the quoted phrase surfaces Bank of America. Combines with `q` (subject AND query), so `subject=\"Tesla\", q=\"recall OR lawsuit\"` reads as expected. Setting it also widens the default window from 24 hours to 30 days (clamped to the plan), because a company can go a fortnight without news — that is the single most common reason a name search comes back empty. Pass an explicit `from_` to override."
},
"event_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Superseded by the `get_story` tool, which does this with two arguments instead of nineteen and can return every source link. Kept for compatibility. Fetch ONE story directly by the `event_id` of an earlier result (e.g. `evt_...`) — use it for \"pull that story up again\". When set, every other filter is ignored. Stories are occasionally folded into a more complete story as coverage develops: that returns 404 naming the replacement id, so fetch that id instead. An id that never existed returns a plain not-found."
},
"verbosity": {
"enum": [
"compact",
"standard",
"full"
],
"type": "string",
"default": "standard",
"description": "Controls ONLY the source-link list; headline, summary, actors, and labels are always present. `compact`: no links. `standard` (default): up to 3. `full`: every link, uncapped — use it for \"show me every source\", but it makes a large `limit` very long."
},
"event_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "What KIND of event the story is, independent of industry. Exact `family.leaf` value; a bare family (`deals`) is invalid and unknown values are rejected naming them. Comma-separated for OR (`deals.merger_acquisition,funding.venture_funding_round` = \"M&A or funding news\"). The taxonomy is 59 leaves across 21 families, plus the standalone value `unclassifiable` for a labeled-but-uncategorizable story. Families: corporate_finance, markets, deals, governance, society_environment, sports, justice_crime, security, macro_policy, research_science, religion_society, politics, legal_regulatory, culture_media, product, accidents_disasters, operations, funding, local_civic, geopolitics, corporate_comms. The complete set of accepted values: corporate_finance.earnings_report, corporate_finance.analyst_rating, corporate_finance.dividends, markets.stock_move, markets.commodity_price, markets.currency_move, deals.merger_acquisition, deals.ipo_filing, deals.asset_sale, governance.board_change, governance.shareholder_vote, governance.executive_departure, society_environment.climate_event, society_environment.public_health, society_environment.environmental_incident, sports.match_result, sports.transfer_signing, sports.championship, justice_crime.arrest_charge, justice_crime.trial_verdict, justice_crime.investigation, security.cyberattack, security.data_breach, security.physical_security_incident, macro_policy.central_bank_decision, macro_policy.trade_policy, macro_policy.fiscal_policy, research_science.scientific_discovery, research_science.clinical_trial_result, research_science.publication, religion_society.religious_event, religion_society.social_movement, politics.election, politics.policy_announcement, politics.diplomacy, legal_regulatory.regulatory_action, legal_regulatory.lawsuit_filed, legal_regulatory.compliance_ruling, culture_media.celebrity_news, culture_media.entertainment_release, culture_media.award, product.product_launch, product.product_recall, product.feature_update, accidents_disasters.natural_disaster, accidents_disasters.industrial_accident, accidents_disasters.transport_accident, operations.plant_closure, operations.layoffs, operations.supply_chain_disruption, funding.venture_funding_round, funding.grant_award, local_civic.local_government_action, local_civic.infrastructure_project, geopolitics.armed_conflict, geopolitics.sanctions, geopolitics.diplomacy_summit, corporate_comms.press_release, corporate_comms.leadership_statement, unclassifiable."
},
"content_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The FORM the reporting takes, independent of what it is about. Comma-separated for OR. One of: news_report, press_release, service_info, human_interest, explainer, commentary, analysis, opinion, interview, obituary. There is no NOT on this field, so for \"analysis, not straight news\" name the forms wanted (`analysis`) rather than the ones to exclude."
},
"min_newsrooms": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum outlets that reported INDEPENDENTLY, mirrors excluded — the strongest is-this-real signal. Reach for this over min_sources whenever the user wants to exclude a story that one outlet ran and everyone else reprinted. `3` ≈ \"well-corroborated only\"."
},
"response_format": {
"enum": [
"text",
"markdown",
"json"
],
"type": "string",
"default": "markdown",
"description": "Output shape in content[0].text. Default `markdown` (readable digest). `text` = plain lines. `json` = full API payload. Match what the user asks for."
}
},
"additionalProperties": false
}