MCP tools

All six tools are read-only and idempotent, and all return the same response envelope described in Response format.

Shared window parameters

Five of the six tools accept a bounded time window with identical rules:

Parameter	Type	Rules
from	ISO date/time string	Optional. Max 40 characters. Must parse as a date.
to	ISO date/time string	Optional. Must not be earlier than from.
limit	integer	Optional. 1–20. Defaults to 8.

The window must not exceed 90 days. Supplying from after to, or a span wider than 90 days, is a validation error. Omitting both lets the server choose the window and report it back as effectiveWindow.

Query strings, where accepted, are trimmed and must be 2–300 characters. All tool inputs are strict — unknown properties are rejected rather than ignored.

---

tnl_research_what_changed

Compares a bounded evidence window against its equal-length baseline and identifies material changes with citations.

Parameter	Type	Required	Notes
query	string	no	2–300 characters. Narrows the comparison to a topic.
from	ISO date	no	Window start.
to	ISO date	no	Window end. Max 90-day span.
limit	integer	no	1–20, default 8.

The baseline is the equal-length period immediately preceding the window, so a 7-day window is compared against the 7 days before it.

---

tnl_research_compare_sources

Compares cited publisher coverage, omissions, contradiction states, framing signals, and timing for a bounded topic.

Parameter	Type	Required	Notes
query	string	yes	2–300 characters.
from	ISO date	no	Window start.
to	ISO date	no	Window end. Max 90-day span.
limit	integer	no	1–20, default 8.

Use this to answer "who is not reporting this?" — omissions are part of the output, not just coverage.

---

tnl_research_validate_event

Finds TNL evidence for an event and returns a bounded corroboration state without claiming certainty.

Parameter	Type	Required	Notes
event	string	yes	4–500 characters. Describe the event in prose.
from	ISO date	no	Window start.
to	ISO date	no	Window end. Max 90-day span.
limit	integer	no	1–20, default 8.

The answer arrives as verificationState, not a boolean. insufficient_evidence is a legitimate and common result — treat it as "TNL cannot speak to this", not as "false".

---

tnl_research_asset_exposure

Maps documented and modeled asset or entity exposure paths, horizons, directions, and counterfactors.

Parameter	Type	Required	Notes
asset	string	yes	1–32 characters. Ticker or short identifier, e.g. NVDA.
assetName	string	no	2–120 characters. Full name, when the ticker is ambiguous.
query	string	no	2–300 characters. Narrows to a topic.
from	ISO date	no	Window start.
to	ISO date	no	Window end. Max 90-day span.
limit	integer	no	1–20, default 8.

Output separates documented exposure from modeled exposure. Check evidenceType on each claim before presenting it.

---

tnl_research_operational_risk

Builds bounded geopolitical or operational-risk scenarios from cited evidence, with assumptions and counterfactors.

Parameter	Type	Required	Notes
query	string	yes	2–300 characters.
region	string	no	2–120 characters.
category	string	no	2–120 characters.
horizon	enum	no	immediate, short_term, medium_term. Default short_term.
from	ISO date	no	Window start.
to	ISO date	no	Window end. Max 90-day span.
limit	integer	no	1–20, default 8.

Scenario output lands in scenarios with counterfactors alongside. Presenting scenarios without their counterfactors misrepresents the result.

---

tnl_research_weekly_consequential

Deduplicates and ranks consequential developments for one bounded week, with cited evidence and stated ranking limitations.

Parameter	Type	Required	Notes
weekStart	ISO date	no	Start of the target week.
query	string	no	2–300 characters.
region	string	no	2–120 characters.
category	string	no	2–120 characters.
limit	integer	no	1–20, default 10.

This tool takes weekStart instead of a from/to pair, and its limit defaults to 10 rather than 8.

---

Response format

Every tool returns this envelope:

{
  "tool": "tnl_research_what_changed",
  "summary": "…",
  "verificationState": "partially_corroborated",
  "confidence": "medium",
  "claims": [
    {
      "claim": "…",
      "evidenceType": "documented_fact",
      "confidence": "high",
      "sourceUrls": ["https://…"]
    }
  ],
  "sources": [
    {
      "title": "…",
      "url": "https://…",
      "publishedAt": "2026-07-20T09:00:00.000Z",
      "sourceType": "publisher",
      "independence": "independent",
      "snippet": "…"
    }
  ],
  "documentedFacts": ["…"],
  "inferences": ["…"],
  "scenarios": ["…"],
  "counterfactors": ["…"],
  "effectiveWindow": { "from": "2026-07-18T00:00:00.000Z", "to": "2026-07-25T00:00:00.000Z" },
  "freshness": { "lastSyncAt": "2026-07-25T07:40:00.000Z", "generatedAt": "2026-07-25T07:46:00.000Z" },
  "pagination": { "returned": 8, "truncated": false },
  "warnings": [],
  "usage": {
    "month": "2026-07",
    "calls": 412,
    "remaining": 9588,
    "monthlyLimit": 10000,
    "resetAt": "2026-08-01T00:00:00.000Z"
  }
}

Field meanings

Field	Type	Notes
tool	string	Which tool produced this.
summary	string	Prose summary of the finding.
verificationState	enum	unverified, partially_corroborated, corroborated, contested, insufficient_evidence.
confidence	enum	low, medium, high. Overall confidence.
claims[]	array	Individual claims. See below.
sources[]	array	Citations. See below.
documentedFacts[]	string[]	Statements backed by cited evidence.
inferences[]	string[]	TNL reasoning, not directly documented.
scenarios[]	string[]	Forward-looking possibilities. Not predictions.
counterfactors[]	string[]	Evidence cutting against the analysis.
effectiveWindow	object	from/to actually used, which may differ from what you asked for.
freshness	object	lastSyncAt (corpus recency, nullable) and generatedAt.
pagination	object	returned count and whether results were truncated.
warnings[]	string[]	Caveats about this specific result. Surface these.
usage	object	Your monthly position after this call.

claims[]

Field	Type	Values
claim	string	The statement.
evidenceType	enum	documented_fact, inference, scenario, counterfactor.
confidence	enum	low, medium, high.
sourceUrls	string[]	URLs supporting this specific claim.

sources[]

Field	Type	Values
title	string	Source title.
url	string	Canonical URL.
publishedAt	string | null	ISO timestamp, nullable.
sourceType	enum	publisher (external) or tnl_record (TNL's own).
independence	enum	primary, independent, tnl_analysis.
snippet	string	Relevant excerpt.

Read independence before weighting a source

primary is the actor's own statement, independent is third-party reporting, and tnl_analysis is TNL's own work. Three independent sources carry different weight from one primary source echoed three times.