Tool reference#
All five MCP tools are read-only and return one compact JSON object as text. Every response has
status, warnings and a meta block with the cache state, the upstream request count, the
provider bytes read (raw_bytes) and the bytes returned. Responses are fitted to a byte budget
(6,000 bytes by default); when something had to be cut, meta.truncated or an omitted block
says so, and a narrower follow-up call gets the rest.
The parameter tables below are generated from the server's own tool schemas when this site is built, so they match release v0.3.0.
MCP tools#
kg_search#
Find entity candidates by name (default 3, max 5). Wikidata by default; provider='google' needs GOOGLE_KNOWLEDGE_GRAPH_API_KEY. place/type are checked locally against descriptions and never sent upstream.
read-only; returns one compact JSON object as text.
| parameter | type | default |
|---|---|---|
query |
string | required |
place |
string | optional |
type |
string | optional |
lang |
string | "en" |
limit |
integer | optional |
provider |
string | "wikidata" |
fallback |
boolean | false |
kg_entity#
Selected facts for one Wikidata QID. props: up to 12 PIDs (default: identity and location overview); evidence: up to 3 PIDs with ranks, qualifiers and references.
read-only; returns one compact JSON object as text.
| parameter | type | default |
|---|---|---|
id |
string | required |
props |
array[string] | optional |
evidence |
array[string] | optional |
lang |
string | "en" |
kg_related#
Bounded relationships of one QID: outgoing values of prop, inverse (items whose prop points to id), or the instance-of/subclass-of hierarchy (depth capped).
read-only; returns one compact JSON object as text.
| parameter | type | default |
|---|---|---|
id |
string | required |
prop |
string | optional |
inverse |
boolean | false |
hierarchy |
boolean | false |
depth |
integer | optional |
limit |
integer | optional |
lang |
string | "en" |
kg_resolve#
Resolve ONE real-world entity to Wikidata/Google KG ids with deterministic evidence codes. Pass only facts you already have (city, coordinates, official_url, address, venue + event_date, creator + year, ...). AUTO_MATCH needs a local anchor (official host, coordinates, address, creator, date + venue); HOLD, AMBIGUOUS and NO_CANDIDATE are valid answers. For many entities use the CLI wdkg resolve-batch.
read-only; returns one compact JSON object as text.
| parameter | type | default |
|---|---|---|
name |
string | required |
kind |
string | optional |
city |
string | optional |
country |
string | optional |
latitude |
number | optional |
longitude |
number | optional |
address |
string | optional |
official_url |
string | optional |
aliases |
array[string] | optional |
venue |
string | optional |
event_date |
string | optional |
organizer |
string | optional |
role |
string | optional |
occupation |
string | optional |
affiliation |
string | optional |
creator |
string | optional |
year |
integer | optional |
existing_wikidata_qid |
string | optional |
existing_google_kg_id |
string | optional |
lang |
string | "en" |
explain |
boolean | false |
kg_audit_identity#
Audit ONE existing QID against local evidence: envelope needs canonical_name, kind, existing_qid and known local facts. WRONG_IDENTITY requires a contradiction; absence remains INSUFFICIENT_EVIDENCE. Use CLI identity-batch for corpora. Candidates require downstream sameAs review. Optional Google exact-ID concordance is not local proof.
read-only; returns one compact JSON object as text.
| parameter | type | default |
|---|---|---|
envelope |
object | required |
max_candidates |
integer | 3 |
refresh |
boolean | false |
google_crosscheck |
boolean | false |
kg_discover_identity#
Discover ONE missing identity with local facts (default 3 candidates, max 5). Pass canonical_name and kind in envelope. AMBIGUOUS and INSUFFICIENT_EVIDENCE are valid answers. Provider concordance is not local proof. Candidates require sameAs review. Use CLI identity-batch JSONL for corpora, never thousands of MCP calls.
read-only; returns one compact JSON object as text.
| parameter | type | default |
|---|---|---|
envelope |
object | required |
max_candidates |
integer | 3 |
refresh |
boolean | false |
google_crosscheck |
boolean | false |
kg_lookup_entities#
Compact facts for at most 10 supplied QIDs using Wikidata batch APIs. fields narrows normalized facts. Lookup never confirms local identity. For hundreds/thousands use CLI lookup-qids --input FILE --out FILE.
read-only; returns one compact JSON object as text.
| parameter | type | default |
|---|---|---|
qids |
array[string] | required |
fields |
array[string] | optional |
lang |
string | "en" |
refresh |
boolean | false |
kg_status#
Provider configuration, credential presence (never values), cache stats and limits. No upstream calls.
read-only; returns one compact JSON object as text.
No parameters.
Reading the output#
status:ok,no_match(nothing matched the name; not a failure),invalid_request,unavailable(for example Google without a key) orerror.resolutionon search:single_supported_candidate(one candidate fits the name and your place/type hints),single_name_match(one name match, no supporting context),ambiguous,partial_matches_onlyorno_match. It describes the search result, not an identity.warnings: read them first.same_name_elsewhere,geo_unverified,ambiguousandverify_before_usemean the identity is not established.decisiononkg_resolve: see Entity resolution.- ids: QIDs and Google ids only ever come from provider responses or your input. Google
ids look like
kg:/m/...orkg:/g/...and are not QIDs.
CLI#
wdkg prints exactly one compact JSON document per call (--pretty indents it) and exits with
0 for ok or no match, 2 for an invalid request, 3 for a provider error, missing
credential or budget stop, and 4 for an invalid evidence bundle.
| command | purpose |
|---|---|
wdkg search |
find entity candidates by name (Wikidata by default) |
wdkg entity |
selected statements for one Wikidata QID |
wdkg related |
bounded relationships of one QID |
wdkg sparql |
guarded read-only SELECT/ASK with enforced LIMIT |
wdkg status |
provider, credential-presence and cache diagnostics (never prints keys) |
wdkg cache |
local cache maintenance |
wdkg resolve |
resolve one local entity to Wikidata / Google KG ids |
wdkg export-evidence |
standalone auditable bundle from resolve-batch output(s); no network |
wdkg validate-evidence |
check an exported bundle's references, pairs and required fields |
wdkg resolve-batch |
resolve a JSONL corpus to JSONL + receipt (resumable) |
wdkg audit-identity |
audit an existing QID against local facts |
wdkg discover-identity |
find missing identity candidates for downstream review |
wdkg identity-batch |
stream identity JSONL with checkpoints, explicit verdicts and summary counters |
wdkg lookup-qids |
compact batched Wikidata fact lookup; no local identity acceptance |
wdkg <command> --help lists every flag with an example. --pretty and --no-cache work
before or after the command name.
Limits#
| limit | default | ceiling |
|---|---|---|
| search candidates | 3 | 5 |
properties per kg_entity call |
identity/location overview | 12 |
| evidence properties (ranks, qualifiers, references) | none | 3 |
| response size | 6,000 bytes | 20,000 bytes |
| upstream requests per interactive call | 12 | 30 |
| hierarchy depth / related rows | 2 / 10 | 3 / 25 |
Environment variables can tighten or relax defaults but never pass the ceilings; the full
list is in the skill's
reference.md.