Skip to main content
Glama

skkg_search_provenance

skkg_search_provenance
Read-onlyIdempotent

Search provenance chains and SKKG acquisitions to list objects matching filters such as owner, place, date, price, or acquisition type.

Instructions

Search provenance chains and SKKG's acquisitions; lists the objects that match. Two layers: chain, the periods before SKKG that curators recorded for only a few hundred objects, and acquisition, how SKKG itself acquired about 55,000 objects (type, seller, date, price). By default both are searched; filters that belong to one layer (owner_type, certainty, holding_kind, transaction_type, source_type, owner, transaction_kind, place: chain; acquisition_type, acquired_from: acquisition) restrict the search to it. An entry matches when it meets every filter; each object lists its matching periods (matched_periods) and acquisition (matched_acquisition). Prices are compared in the currency recorded, never converted, so a price filter needs currency. Owner names are as SKKG publishes them; its anonymisation ("Unbekannte:r Eigentümer:in", "Privatperson") stays as it is: never try to identify those persons. Each object carries image_license (its primary image) and object_copyright: quote both. For the whole chain of one object, use skkg_get_object with include ["provenance", "acquisition"]; for a period, skkg_get_record with its id; for labels of the term filters, skkg_find_terms.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "skkg_search_provenance"
  }
}

Input Schema

NameRequiredDescriptionDefault
langNoLanguage of vocabulary labels. Most vocabularies, materials and object types among them, have German labels only, which are returned whatever the language; titles and texts stay as recordedde
sortNodate_asc (default: earliest matching entry first, a period open at its start before all others), date_desc (latest first, a period open at its end before all others), price_desc (highest price first; needs `currency`), or inventory_numberdate_asc
layerNochain (periods before SKKG), acquisition (SKKG's own acquisitions), or both (default)both
limitNoObjects per page. Default 5
ownerNoOwner of a chain period: an actor id ("person/…") or a name ("Stuker", "Galerie Kornfeld"). A name matches every person or institution whose name contains all its words; applied_filters lists them
placeNoPlace of a chain period, as SKKG writes it ("Zürich", "Genf", "Paris"). Each word matches the start of a word, ignoring case and accents; applied_filters lists the places matched
offsetNo
year_toNoLatest year; see year_from
currencyNoCurrency of the price: its ISO code or SKKG's label of it, e.g. "CHF", "DEM", "GBP", "DM" (SKKG's "DM" and "FF" are DEM and FRF). Alone, it keeps the entries with a price in that currency
certaintyNoCertainty of a period: "gesichert", "wahrscheinlich", "vermutlich", or "möglicherweise". A term id ("type/…") or a German label, matched exactly except for case.
price_maxNoHighest price, in `currency`; see price_min
price_minNoLowest price, in `currency`, which it needs. A batch price (is_batch_price) is the price of all objects of the batch
year_fromNoEarliest year. A chain period matches when its dates overlap the range, an acquisition when its year is in it; undated entries never match. A period open at one end ("seit 1995", "1916–o. D.", "bis 1934") reaches every year on that side; a lone date with another qualifier ("um 1900", "vor 1997", "spätestens 1907") is that year only
owner_typeNoKind of owner, e.g. "Privatbesitzer:in", "Auktionshaus", "Galerie". A term id ("type/…") or a German label, matched exactly except for case.
source_typeNoType of a period's source, e.g. "Archivquelle (SKKG)", "Archivquelle (extern)", "Kommentar (Fussnote)". A term id ("type/…") or a German label, matched exactly except for case.
holding_kindNoKind of holding, e.g. "Eigentum", "Besitz", "Kommissionsware". A term id ("type/…") or a German label, matched exactly except for case.
acquired_fromNoWho SKKG acquired the object from: an actor id or a name, as for `owner`
acquisition_typeNoHow SKKG acquired the object, e.g. "Auktion", "Freihandkauf", "Schenkung". A term id ("type/…") or a German label, matched exactly except for case.
transaction_kindNoacquisition: the owner received title; custody: the owner received custody only, as with goods on commission or in storage; activity: SKKG records no transfer for the period
transaction_typeNoHow the owner got the object, e.g. "erworben auf Auktion", "geerbt", "erworben als Kauf". A term id ("type/…") or a German label, matched exactly except for case.

Output Schema

NameRequiredDescriptionDefault
sortYes
totalYesObjects with a matching entry
layersYesThe layers searched, after the filters that belong to one layer
offsetYes
resultsYes
has_moreYes
returnedYes
warningsNo
data_as_ofNo
next_offsetNo
total_periodsYesChain periods that matched, each once, including those in unlinked_periods
applied_filtersNo
unlinked_periodsNoMatching periods that belong to no object in the database; skkg_get_record returns each by its id
total_acquisitionsYesSKKG acquisitions that matched, over all objects

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.5.0

TDQS

A4.4/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restatement. The description still adds real policy context the annotations cannot: prices are never converted so a price filter requires `currency`, SKKG's anonymised owner labels must not be de-anonymised, and image_license/object_copyright must be quoted. It does not discuss pagination limits or result ordering behavior beyond what the schema documents, keeping this from a 5.

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 purpose and the two-layer model, then constraints. It is dense and mostly earns its length, though the long parenthetical enumerating filter names duplicates what the schema already labels and could be trimmed.

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

Completeness5/5

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

For a 20-parameter search tool with an output schema and full annotations, the description covers layer semantics, filter interaction, currency/price coupling, date-range openness edge cases, anonymisation policy, and attribution requirements. An agent can call it correctly without further exploration.

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 95%, so most parameter meaning already comes from structured fields. The description nonetheless adds cross-parameter semantics the schema cannot show as cleanly: the full list of chain-only filters vs acquisition-only filters and the rule that using one restricts the search layer, plus the AND-across-filters matching rule and matched_periods/matched_acquisition output structure.

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?

Opens with a specific verb and resource ('Search provenance chains and SKKG's acquisitions; lists the objects that match') and immediately decomposes the domain into two named layers, chain and acquisition, with scale figures (a few hundred vs ~55,000 objects). An agent knows exactly what corpus this tool covers and can tell it apart from object-level siblings such as skkg_get_object.

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?

Explicitly routes the agent: for one object's full chain use skkg_get_object with include ['provenance','acquisition'], for a single period use skkg_get_record, for term filter labels use skkg_find_terms. It also states the default behavior (both layers searched) and the exclusion rule (layer-specific filters restrict the search to that layer).

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