Skip to main content
Glama

skkg_search_actors

skkg_search_actors
Read-onlyIdempotent

Find SKKG records for persons and groups by name, dates, places, roles, gender, nationality, and collection link; results show each actor's role counts.

Instructions

Search the persons and groups SKKG records, by name, dates, places and roles. Groups are firms, institutions, and families. Filters: query (names, including alternative names and GND names), kind, years of birth and death (for a group: formation and dissolution), the place or country of those events, gender, nationality, how the actor is linked to the collection (role_in_collection), and whether a GND or Wikidata id is recorded. Each result lists its roles with their counts. SKKG's anonymisation ("Privatperson", "Unbekannte:r Eigentümer:in") is never a result: never try to identify those persons. Actors SKKG records only by name, most of them authors, editors, and publishers of literature, are not listed; name_only counts those that match and names a few, each with the skkg_search_literature calls that list their publications (publisher for what it published, author for what it wrote or edited; one call each). For one actor's full record, with their objects and literature, use skkg_get_record with its id; for the objects of a creator, skkg_search_objects with creator; for labels of gender and the country codes, 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_actors"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNoperson, or group (a firm, institution, or family)
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
sortNorelevance (the default with `query`), name (the default without), born_asc or born_desc (by the year of birth or formation; actors without it last)
limitNoActors per page. Default 10
placeNoPlace of birth, death, formation, or dissolution, as SKKG writes it, e.g. "Zürich", "Genf", "Paris". Each word matches the start of a word, ignoring case and accents; applied_filters lists the places matched
queryNoName: matched against all of the actor's names at once, so the words may come from different ones, e.g. "Anker", "Albert Anker", "Koll*". Every word must occur; "a phrase" matches in order; a trailing * matches a prefix; OR between two words matches either; NOT before a word excludes it. Umlauts may be written ä or ae
genderNoGender, as SKKG records it, e.g. "männlich", "weiblich", or "unbekannt". A term id ("type/…") or a German label, matched exactly except for case.
offsetNo
born_toNoLatest year of birth or formation; see born_from
died_toNoLatest year of death or dissolution; see died_from
born_fromNoEarliest year of birth, or of a group's formation. Actors without that year never match
died_fromNoEarliest year of death, or of a group's dissolution. Actors without that year never match
nationalityNoNationality, as an ISO country code, e.g. "CH", "DE", "FR", "IT". SKKG records a dual nationality as a term of its own, e.g. "CH/DE", which "CH" does not match. A term id ("type/…") or a German label, matched exactly except for case.
has_authorityNotrue: SKKG records a GND or Wikidata id for the actor; false: neither
place_countryNoCountry of the place of birth, death, formation, or dissolution, as SKKG records it: an ISO country code, e.g. "CH", "DE", "FR". A term id ("type/…") or a German label, matched exactly except for case.
role_in_collectionNoHow the actor is linked to the collection: creator (made objects), influence (objects were made after them or under their influence), acquired_from (SKKG acquired objects from them), provenance_owner (owned objects before SKKG), photographer or photo_right_holder (of published images), author, editor, or publisher (of literature), subject_of_literature

Output Schema

NameRequiredDescriptionDefault
sortYes
totalYesPersons and groups that match
offsetYes
resultsYes
has_moreYes
returnedYes
warningsNo
name_onlyNoActors SKKG records only by name that meet the same filters; they are not listed. examples gives up to five distinct names, each with one id for skkg_get_record and, for authors, editors, and publishers, its literature_filters
data_as_ofNo
next_offsetNo
applied_filtersNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.5.0

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the read-only annotations, the description discloses critical domain behavior: SKKG anonymisation labels are never results and must not be used to identify persons, name-only actors are excluded from the result list but represented via `name_only`, and each result includes role counts. These are substantive behavioral constraints an agent could not infer from annotations alone.

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?

The description is dense but front-loaded with purpose, followed by filters, exclusions, and alternatives in a logical order. It is long because the tool has 16 optional parameters, and every sentence is relevant, though the single-paragraph density makes it slightly harder to scan than a bulleted structure would.

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?

Given 16 optional parameters, high schema coverage, read-only annotations, and an output schema, the description is complete enough to call the tool correctly. It covers the special anonymisation rule, the name-only actor behavior, role semantics, and the main alternatives for adjacent tasks.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is already 94%, so the schema carries most parameter meaning. The description usefully mentions that `query` spans alternative and GND names, that birth/death years mean formation/dissolution for groups, and that `role_in_collection` captures collection relationships, but most of this is already in the schema rather than adding syntax or edge-case detail beyond it.

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?

The description opens with a specific verb and resource: "Search the persons and groups SKKG records", then defines groups as firms, institutions, and families. It clearly distinguishes this actor search from object, literature, term, and record retrieval siblings.

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?

It explicitly routes the agent to alternatives: skkg_get_record for one actor's full record, skkg_search_objects with `creator` for an actor's objects, and skkg_find_terms for labels and country codes. It also states important exclusions: anonymised entries are never returned, and name-only actors are not listed but are counted and summarized.

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