4ort / Docs / Knowledge tools

Knowledge tools

One contract, three doors. Every tool below is declared once in app/contracts/knowledge.py; the MCP server, the REST routes and this page are generated from it. Contract knowledge/1.2.0 · sha256 5f6a47552e29 (full manifest).

Connect

Door	Address
MCP (default profile: these 8 tools)	`https://mcp.4ort.xyz/mcp`
MCP legacy profile (the full legacy catalogue, kept for one release)	`https://mcp.4ort.xyz/mcp/legacy` or `/mcp?profile=legacy`; stdio: `4ort mcp --profile legacy`
REST	`GET https://4ort.xyz/api/v1/knowledge/<tool>?…`, list arguments repeat the key (`?entities=Q42&entities=Q7259`)
One entity's packet (ETag, free 304)	`GET https://4ort.xyz/api/v1/entities/{id}/packet?fields=P569,P570`

Every tool is read-only, idempotent and calls no LLM. Legacy tool names (kg_search, kg_entity, …) still answer on the default MCP endpoint, so existing integrations keep working. Send your key as Authorization: Bearer 4kg_…; only why_trending requires one (free tier works). A free key is POST /api/v1/register {"name": "my-agent"}.

The tools

Tool	Use it for
`get_entity_packet`	Facts about one or more known things (people, companies, places, works, products) with per-fact citation: source dataset, source record URL, edition, licence and required credit line, qualifiers (start/end dates, roles), a reference-support band, and explicit unknowns. Use it for any factual question about a named entity ('when was X born', 'who is the CEO of Y', 'population of Z'), including several entities at once to compare them. Accepts names, so you do not need resolve_entity first. Pass `fields` to get only the properties you need.
`search_knowledge`	Open-ended question or topic search. Returns the evidence packet of the entity the query is about (when there is one), web pages from the 4ort index, and the top destinations to fetch next. Use it when the question is not about one named entity you can pass to get_entity_packet, or when you also want pages. status 'no_coverage' means use another provider.
`resolve_entity`	List the entities a name could mean, with ids, descriptions and a confidence. Use it only to disambiguate ('which Mercury?', 'list entities called Paris') or to get an entity_id; for facts call get_entity_packet directly.
`find_routes`	Destinations for a task: official sites, registries, APIs and site search URLs, ranked, each with its kind and licence. Use it to answer 'where can I look up / which API / which official site'. A route is where to fetch next, not evidence of the answer.
`get_entity_changes`	Edits to one entity's source record (Wikidata), newest first, with the properties each edit touched, plus a cursor to poll for newer ones. Use it for 'what changed about X', 'was X updated since <date>', or to know when cached facts went stale.
`why_trending` key required	Entities trending right now on Wikipedia by language edition, each with its pageview spike against baseline and 3 to 5 knowledge-graph-resolved news items that explain it (status news or organic). Use it for 'what is trending', 'why is X in the news today'. Needs your 4ort.xyz API key (free tier works).
`get_attention`	Wikipedia pageviews for one entity as a time series (48 h hourly, 30 d daily or 12 months monthly), its change across the period, and views per language. Use it for 'how popular is X', 'is interest in X rising', 'monthly views of X'.
`get_source_info`	The licence, required credit line, redistribution and resale status of a dataset 4ort serves (Wikidata, GeoNames, GLEIF, SEC EDGAR, ...). Use it for 'can I reuse / redistribute facts from X', 'what licence is source Y', 'how must I credit Z'. Packets already carry the licence per fact; this explains a source.
`get_upcoming_launches`	The next scheduled orbital launches worldwide, soonest first: rocket, provider, pad and country, NET (no-earlier-than, UTC) with its precision, status, mission type and orbit. Use it for 'when is the next launch', 'upcoming SpaceX launches', 'what launches this week'. From Launch Library 2 (Apache-2.0) via the 4ort lake; `as_of` and `stale` say how fresh the capture is.
`get_galaxy_brain`	One live snapshot of the whole 4ort galaxy, one object per brain region: crawler pages fetched (eyes), news ingested and latest headlines (ears), top Wikipedia attention with why (attention), knowledge-graph size and growth today plus the Wikidata edit rate (memory), facts verified into the served tier (reasoning), the data lake's size and newest landing (deep_memory), the next rocket launch (mission_control), the trust-and-safety patrol state (immune) and what 4ort.live is playing (voice). Use it for 'what is happening across 4ort right now'. Rebuilt every minute; each region has ok and updated_at.

get_entity_packet

Facts about one or more known things (people, companies, places, works, products) with per-fact citation: source dataset, source record URL, edition, licence and required credit line, qualifiers (start/end dates, roles), a reference-support band, and explicit unknowns. Use it for any factual question about a named entity ('when was X born', 'who is the CEO of Y', 'population of Z'), including several entities at once to compare them. Accepts names, so you do not need resolve_entity first. Pass `fields` to get only the properties you need.

Argument	Type	Meaning
`entities` required	array	1 to 10 entities: an entity_id (slug), a Wikidata Q-id, a 4ort UUID, or a plain name (resolved to the best match; the resolution is reported)
`fields`	array	Only these properties: P-codes ('P569') or English property labels ('date of birth', 'population'). Omit for the entity's main facts. A field we do not hold comes back in unknowns with its reason
`max_facts`	integer = 30	Upper bound on facts per entity (size bound)

Annotations: readOnlyHint=true · destructiveHint=false · idempotentHint=true · openWorldHint=false. Output schema: manifest → tools[0].outputSchema.

GET /api/v1/knowledge/get_entity_packet?entities=Douglas%20Adams&fields=date%20of%20birth
GET /api/v1/knowledge/get_entity_packet?entities=Q312&entities=Q2283&fields=P169&fields=P1128

search_knowledge

Open-ended question or topic search. Returns the evidence packet of the entity the query is about (when there is one), web pages from the 4ort index, and the top destinations to fetch next. Use it when the question is not about one named entity you can pass to get_entity_packet, or when you also want pages. status 'no_coverage' means use another provider.

Argument	Type	Meaning
`query` required	string	A question or topic in natural language, e.g. 'who founded Anthropic'
`limit_pages`	integer = 5	Web pages from the 4ort index to include

Annotations: readOnlyHint=true · destructiveHint=false · idempotentHint=true · openWorldHint=false. Output schema: manifest → tools[1].outputSchema.

GET /api/v1/knowledge/search_knowledge?query=who%20founded%20Anthropic
GET /api/v1/knowledge/search_knowledge?query=history%20of%20the%20Antikythera%20mechanism

resolve_entity

List the entities a name could mean, with ids, descriptions and a confidence. Use it only to disambiguate ('which Mercury?', 'list entities called Paris') or to get an entity_id; for facts call get_entity_packet directly.

Argument	Type	Meaning
`name` required	string	A name or phrase to resolve, e.g. 'Mercury' or 'Apple Inc'
`limit`	integer = 5	Candidates to return

Annotations: readOnlyHint=true · destructiveHint=false · idempotentHint=true · openWorldHint=false. Output schema: manifest → tools[2].outputSchema.

GET /api/v1/knowledge/resolve_entity?name=Mercury

find_routes

Destinations for a task: official sites, registries, APIs and site search URLs, ranked, each with its kind and licence. Use it to answer 'where can I look up / which API / which official site'. A route is where to fetch next, not evidence of the answer.

Argument	Type	Meaning
`query` required	string	What you want to look up or do, e.g. 'company registry Estonia' or 'weather API'
`limit`	integer = 8

Annotations: readOnlyHint=true · destructiveHint=false · idempotentHint=true · openWorldHint=false. Output schema: manifest → tools[3].outputSchema.

GET /api/v1/knowledge/find_routes?query=company%20registry%20Estonia
GET /api/v1/knowledge/find_routes?query=earthquake%20data%20API

get_entity_changes

Edits to one entity's source record (Wikidata), newest first, with the properties each edit touched, plus a cursor to poll for newer ones. Use it for 'what changed about X', 'was X updated since <date>', or to know when cached facts went stale.

Argument	Type	Meaning
`entity` required	string	entity_id, Q-id, UUID or name of ONE entity
`since`	string	Only changes at or after this UTC date/time, e.g. '2026-10-01'
`limit`	integer = 25

Annotations: readOnlyHint=true · destructiveHint=false · idempotentHint=true · openWorldHint=false. Output schema: manifest → tools[4].outputSchema.

GET /api/v1/knowledge/get_entity_changes?entity=Q42&since=2026-10-01

why_trending

Entities trending right now on Wikipedia by language edition, each with its pageview spike against baseline and 3 to 5 knowledge-graph-resolved news items that explain it (status news or organic). Use it for 'what is trending', 'why is X in the news today'. Needs your 4ort.xyz API key (free tier works).

Argument	Type	Meaning
`limit`	integer = 10
`type`	string
`lang`	string = en	Wikipedia edition: en, de, fr, es, it, ja, ru, pt, or all
`include_unexplained`	boolean = False	Also list trending entities without at least 3 verified news items

Annotations: readOnlyHint=true · destructiveHint=false · idempotentHint=true · openWorldHint=false. Output schema: manifest → tools[5].outputSchema.

GET /api/v1/knowledge/why_trending?limit=5
GET /api/v1/knowledge/why_trending?type=person&lang=de

get_attention

Wikipedia pageviews for one entity as a time series (48 h hourly, 30 d daily or 12 months monthly), its change across the period, and views per language. Use it for 'how popular is X', 'is interest in X rising', 'monthly views of X'.

Argument	Type	Meaning
`entity` required	string	entity_id, Q-id, UUID or name of ONE entity
`period`	string = 30d	48h: hourly points; 30d: daily points; 12m: monthly points

Annotations: readOnlyHint=true · destructiveHint=false · idempotentHint=true · openWorldHint=false. Output schema: manifest → tools[6].outputSchema.

GET /api/v1/knowledge/get_attention?entity=Taylor%20Swift&period=12m

get_source_info

The licence, required credit line, redistribution and resale status of a dataset 4ort serves (Wikidata, GeoNames, GLEIF, SEC EDGAR, ...). Use it for 'can I reuse / redistribute facts from X', 'what licence is source Y', 'how must I credit Z'. Packets already carry the licence per fact; this explains a source.

Argument	Type	Meaning
`source`	string =	Source key or name, e.g. 'wikidata', 'geonames', 'GLEIF'. Empty lists every source

Annotations: readOnlyHint=true · destructiveHint=false · idempotentHint=true · openWorldHint=false. Output schema: manifest → tools[7].outputSchema.

GET /api/v1/knowledge/get_source_info?source=geonames

get_upcoming_launches

The next scheduled orbital launches worldwide, soonest first: rocket, provider, pad and country, NET (no-earlier-than, UTC) with its precision, status, mission type and orbit. Use it for 'when is the next launch', 'upcoming SpaceX launches', 'what launches this week'. From Launch Library 2 (Apache-2.0) via the 4ort lake; `as_of` and `stale` say how fresh the capture is.

Argument	Type	Meaning
`limit`	integer = 10	How many launches, soonest first

Annotations: readOnlyHint=true · destructiveHint=false · idempotentHint=true · openWorldHint=false. Output schema: manifest → tools[8].outputSchema.

GET /api/v1/knowledge/get_upcoming_launches?limit=10

get_galaxy_brain

One live snapshot of the whole 4ort galaxy, one object per brain region: crawler pages fetched (eyes), news ingested and latest headlines (ears), top Wikipedia attention with why (attention), knowledge-graph size and growth today plus the Wikidata edit rate (memory), facts verified into the served tier (reasoning), the data lake's size and newest landing (deep_memory), the next rocket launch (mission_control), the trust-and-safety patrol state (immune) and what 4ort.live is playing (voice). Use it for 'what is happening across 4ort right now'. Rebuilt every minute; each region has ok and updated_at.

Argument	Type	Meaning

Annotations: readOnlyHint=true · destructiveHint=false · idempotentHint=true · openWorldHint=false. Output schema: manifest → tools[9].outputSchema.

GET /api/v1/knowledge/get_galaxy_brain?

Evidence packets

A packet (4ort.packet/1) is one entity's facts with, on every fact:

citation: the source dataset, the record inside it that states the fact (a Wikidata statement anchor, a GeoNames record), the edition we serve and its basis, the licence, and the credit line the licence requires (null when none is owed). The source's own references (reference URL, stated in, retrieved) ride with it.
qualifiers (start and end time, role, point in time) and current = false when an end time is set.
trust: reference support with its rule named in basis. Wikidata: high = our copy shows it citing a source, medium = only imported from a Wikipedia edition, unscored = our copy holds no reference (older copies dropped them, so that is not evidence of none). It is not a probability (calibrated is false).
layer: source (stated by the cited dataset) or derived (a claim 4ort derived from cited evidence).

Beside the facts: unknowns (not_in_our_sources means we hold no statement, which is not evidence that there is none; no_value and unknown_value are only ever the source's own statements; only_deprecated; unknown_field), as_of (when our copy was written, the latest source edit our stream saw, and stale_possible), licences per source with the fields each covers, and routes (entity page, this packet over REST, Wikidata item, official website, changes, attention). A route is where to go next, not evidence.

Bounded: at most 120 facts and 48 KB per packet (default 30 facts); 5 values per property, 6 qualifiers and 2 references per fact. When anything is left out, status is truncated and omitted says how many and why. The body has no delivery timestamp, so unchanged facts keep the same ETag.

Rights in one line: facts carry their own dataset's licence; third-party pages and routes are their publisher's and are not relicensed by 4ort. Per-source terms: Data rights · /api/v1/sources.