Pangur docsMCP tools
This page lists every tool that Pangur's MCP server offers a connected assistant, with what each one does, whether it reads or adds, and its main parameters.
Pangur's MCP server offers a connected assistant 132 tools. You do not normally call them yourself. The assistant chooses which tools to call from their names and descriptions, and this page is for seeing what it can do in your library and for looking up a tool it has used. For how an assistant connects, and the rules it works under, see Assistants and Pangur.
Reading the tables
Each table lists one group of tools. The Kind column says what a tool may do:
- Reads tools only read. Your MCP client sees them marked read-only.
- Writes tools add something to your library, such as a reference, a note, a document version or a mark. None of them deletes or overwrites an item, note, file, document or transcription. When a tool revises one of these, the earlier state is kept. A few of them record a choice in Pangur's own structures, such as a value on an arrangement node, a node's position or which copy is the reading copy. Viewers in an organisation project cannot use these tools.
- Writes, viewers too tools add something of your own, such as a document, and remain open to viewers in an organisation project, as the same actions are in the web app.
In the Main parameters column, an asterisk marks a required parameter. Optional paging parameters such as limit, offset and start are listed where a tool has them.
No tool runs Pangur's own language or vision model. Wherever the web app would use a model, the tool instead returns the material and instructions, and the assistant's own model does the work. Text that a tool returns from your library is data for the assistant to quote and cite, not instructions for it to follow.
The project argument
Every tool works in your default project, the one you opened last, unless its optional project argument names another project by the id or address that list_projects returns. Every tool takes project except list_projects and reference_template. The project argument is left out of the tables below.
If the project is scoped to one collection, every tool works inside that collection: reads outside it are refused and new items are filed into it.
Finding and reading sources
search and fetch are the two tools ChatGPT's deep research expects, under those exact names. The other tools read items, attachments and their text in more detail.
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
search | Reads | Searches the library's titles, creators and years and returns ids to pass to fetch. Every word must match. | query* |
fetch | Reads | Returns a search result's bibliographic details and text: the first window of its main file's text, or its abstract. For a long document it says how to read the rest with get_attachment_text. | id* |
search_items | Reads | Searches or browses top-level items, filtered by item type or tag and sorted by title, creator, type, date or when they were added or changed. Each result says which attachments it has. | query, item_type, tag, collection_key, sort, direction, limit, start |
get_item | Reads | Returns one item's full details, optionally with its formatted citation or bibliography entry. | item_key*, include |
get_item_children | Reads | Lists an item's notes and attachments, and says which text the item is read from (a TEI edition, a transcription or a file's text) and whether it has page images to transcribe. | item_key* |
get_item_attachments | Reads | Lists an item's attachments and says which can be downloaded or read as text. | item_key* |
get_attachment_text | Reads | Returns a window of an attachment's readable text. A long document is read by calling again from the next offset until nothing is left. | attachment_key*, offset, max_chars |
download_attachment | Reads | Returns an attachment as text, or as the whole file encoded in base64. Suited to small files. | attachment_key*, as_ |
get_transcript | Reads | Returns a recording's transcript as timed segments with speakers where they were identified. It never starts a transcription; a recording has one only after someone asked for it in the reader. | attachment_key*, start_seconds, end_seconds |
query_dataset | Reads | Describes a dataset attachment (CSV, spreadsheet, Parquet, JSON or JSON Lines) that Pangur has read, or runs one SQL SELECT against one of its sheets. Nothing can be written. | attachment_key*, sql, sheet, max_rows |
list_projects | Reads | Lists your projects with their ids, addresses and your role in each, and says which one the tools are working in. | — |
list_collections | Reads | Lists the library's collections, or the sub-collections of the collection the project is scoped to. | — |
list_collection_items | Reads | Lists the items in one collection. | collection_key*, limit, start |
list_collection_sources | Reads | Lists every top-level item in a collection with its details and whether its full text is available, for working through a whole collection. | collection_key |
list_tags | Reads | Lists the tags on the library's items, optionally only those containing a word. These are item tags, not research tags. | query, limit, start |
Citations and references
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
get_bibliography | Reads | Formats citations and bibliography entries for items in any CSL style, such as apa, chicago-author-date, mla, vancouver or ieee. | item_keys*, style, locale |
get_csl_json | Reads | Returns items as CSL-JSON. | item_keys* |
export_references | Reads | Returns references as the text of a BibTeX, BibLaTeX, RIS or CSL-JSON file: a selection, one collection, or the whole library. | format, item_keys, collection_key |
get_references | Reads | Lists the works a stored PDF cites, combining OpenAlex's citation data with the printed bibliography or footnotes. Each work is marked as in the library, importable, a primary source (an archival manuscript) or unresolved. | attachment_key, item_key, refresh |
scan_references | Reads | Lists the works any other document cites: pasted text, a reference file's text, or a public web page or PDF, with the same statuses as get_references. Nothing is added. | text or url, refresh |
Adding references, notes and collections
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
reference_template | Reads | Returns the fields and creator types an item type accepts, as a blank to fill in before create_reference. | item_type* |
create_reference | Writes | Creates a reference from the fields given. | item_type*, fields, creators, tags, collection_keys |
upload_attachment | Writes | Stores a small file, sent in base64, as an attachment, under an item or on its own. For larger files use request_upload_url. | filename, content_base64, parent_item_key, title, content_type |
attach_link | Writes | Attaches a web link to an item, or adds it on its own. | url*, title, parent_item_key |
create_note | Writes | Creates a note, under an item or on its own. A repeated call with the same key returns the note already made. | html*, parent_item_key, tags, key |
create_collection | Writes | Creates a collection, at the top level or under another. | name*, parent_collection_key |
add_to_collection | Writes | Adds items to a collection. They stay in their other collections. | item_keys, collection_key |
find_book_chapters | Reads | Looks up a book's chapters in OpenAlex, with a page map when the book has a PDF. Creates nothing. | book_key* |
split_book_into_sections | Writes | Creates a book section for each confirmed chapter and, if asked, attaches the matching pages of the book's PDF to each. | book_key, sections, attachment_key, slice_pdf |
create_book_from_section | Writes | Creates a book item from a book section's book title, editors, publisher and related fields. The section is unchanged. | section_key* |
Importing works and files
These tools bring new works into the library from outside catalogues and from files you hold. After a save, Pangur looks for a PDF, trying open-access copies first and then your institutional access (the order and the outcomes are in Where PDFs come from).
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
import_search | Reads | Searches OpenAlex and the book catalogues (Open Library, the Library of Congress and K10plus) for works to add. provider="estc" searches the English Short Title Catalogue for books printed before 1801. | query*, limit, provider |
import_lookup | Reads | Resolves a DOI, ISBN, PMID, arXiv id or ESTC number to a catalogue record ready to save. | identifier* |
import_grab | Reads | Works out which work a web page describes and whether it offers a PDF, and says if the library already has it. | url* |
import_save | Writes | Saves a work found by search or lookup, or given by DOI or ISBN, and by default looks for its PDF. If the work is already in the library, nothing is created unless a duplicate is asked for. | candidate_token or identifier, collection_key, resolve_pdf, allow_duplicate |
import_status | Reads | Shows recent saves, or one, with whether a PDF was attached and where it came from. | job_id, item_key, limit |
import_references | Writes | Imports many references as one background batch, for example the importable works get_references found. | refs*, source, collection_key, fetch_pdfs |
import_batch_status | Reads | Shows the progress of bulk imports, or one batch with the outcome of each entry. | batch_id, limit |
find_import_pdfs | Writes | Looks for open-access PDFs for the references a finished bulk import saved without looking. | batch_id* |
request_ingest_urls | Writes | Starts bringing in your own files, up to 50 at a time. Returns an upload address for each file, valid for an hour; Pangur then identifies each uploaded file and creates or matches its reference. | files*, collection_key |
ingest_status | Reads | Shows what happened to ingested files, including what Pangur could see of a file it could not identify. | group_id, ingest_id, limit |
ingest_resolve | Writes | Gives an unidentified file its reference, or files it under an item already in the library. | ingest_id*, candidate_token, identifier, item_key, reference, allow_duplicate |
request_upload_url | Writes | Returns an address, valid for 15 minutes, where you can upload a file to attach to an existing item, such as a PDF downloaded through your library. Large files go up in parts. | item_key, filename, content_type, shrink |
request_upload_urls | Writes | Does the same for up to 50 files at once. | files* |
Background work
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
list_tasks | Reads | Lists background work in the project, such as PDF searches, imports, exports, summaries, analyses and transcriptions, with each task's state and a link to its result. | active_only, limit |
get_task | Reads | Returns one task's progress, or its summary and link once it has finished. | task_id* |
Ask, the library map and summaries
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
ask_library | Reads | Returns ranked passages that bear on a question, with the library map, for the assistant to write the answer from. With thread_id, it also returns the conversation's recent turns. | question*, thread_id |
library_map | Reads | Returns the library map: one line per work saying what it covers, or the full entries for the works named. | item_keys |
summarise_item | Writes, viewers too | Returns instructions for the assistant to read a work and write its summary itself. The long summary with checked quotations is made in Pangur, where it counts against your plan. | item_key*, depth, attachment_key |
list_ask_threads | Reads | Lists your Ask conversations, newest first. | limit |
get_ask_thread | Reads | Returns one conversation's questions and answers, the sources each answer cited, and the passages assistants marked in it. | thread_id* |
record_ask_turn | Writes | Adds the assistant's answer to an Ask conversation, or starts a new one. The answer appears in Ask labelled as the assistant's and does not count against your plan. | question, answer_markdown, sources, thread_id, tags |
Marks and research tags
Research tags say what a highlight, mark, analysis unit or answer is about, as a dimension and a name: person:John Milton, date:January 1649, place:Whitehall. The writing desk uses them to bring material back when you write about the same subject.
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
list_annotations | Reads | Lists your highlights on a file, with your comments, and the passages assistants have marked on it. | attachment_key*, query |
mark_passage | Writes | Marks a passage, found by quoting it exactly, for you to see in the reader. The mark sits beside your highlights, labelled as the assistant's, until you keep or dismiss it. | attachment_key, quote, comment, page, thread_id, tags |
list_research_tags | Reads | Lists the project's research tags, most used first. | query, dimension, limit |
tag_passage | Writes | Adds research tags to a highlight, an assistant's mark, an analysis unit or an Ask answer. Tags can be added but not removed. | target_kind, target_id, tags* |
Manuscripts, facsimiles and transcription
These tools find a manuscript's digitised leaves, show them to the assistant, and save transcriptions. The division of labour is that Pangur detects the lines on a leaf and the assistant's own model reads them, which is the same two steps a person takes on the transcription desk.
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
manuscript_facsimile | Reads | Says whether the library has a facsimile for a manuscript, given an item or a repository and shelfmark as a footnote writes them, and lists its sources: repository IIIF images, your photographs or uploaded files. | item_key, repository, shelfmark |
manuscript_leaves | Reads | Pages through a facsimile's leaves, optionally finding one by its folio label. | item_key, repository, shelfmark, query, source_key, offset, limit |
manuscript_leaf | Reads | Returns one leaf, or a region of it, as an image, optionally with the ink enhanced. | canvas_index*, item_key, repository, shelfmark, region, enhance, source_key |
manuscript_leaf_tiles | Reads | Returns the regions that divide a leaf into full-resolution tiles in reading order, for reading dense script tile by tile. | canvas_index*, item_key, repository, shelfmark, region, tile_px, source_key |
link_manuscript_facsimile | Writes | Links a digital library's viewer or IIIF manifest to a manuscript's shelfmark, so every citation of that volume can reach it. | url*, item_key, repository, shelfmark, create_item |
transcribe_manuscript_leaf | Writes | Detects the lines on one leaf and returns each line's region with the reading conventions, for the assistant to read. | item_key, canvas_index, source_key |
save_manuscript_leaf_reading | Writes | Saves the assistant's reading onto a leaf's detected lines. Existing text is first saved as a version, lines an editor corrected keep the editor's reading, and the new lines are marked as a model's reading. | item_key, canvas_index, reading*, source_key |
get_manuscript_transcription | Reads | Returns the saved transcription for one facsimile source, line by line. | item_key*, source_key |
list_manuscript_transcription_versions | Reads | Lists the named versions of a transcription. | item_key*, source_key |
get_manuscript_transcription_version | Reads | Returns one named version with its pages and lines. | item_key, version_id, source_key |
create_manuscript_transcription_version | Writes | Saves the current transcription as a new named version that cannot be changed. | item_key, label, source_key |
export_transcription | Reads | Exports a transcription as TEI P5, PAGE XML, ALTO or plain text, without the page images. | item_key*, format, reading, source_key, version_id, pages |
temporary_page_link | Writes, viewers too | Returns a link to one page image that works for 30 minutes, for correcting a text in ESTC. Pangur checks permission again when the link is used. | item_key, source_key, canvas* |
ESTC and TEI texts
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
import_estc_collection | Writes | Imports an ESTC collection, with its TEI texts, into a library collection and an analysis corpus, as a background task. | manifest* |
import_tei_text | Writes | Imports an ESTC TEI bundle into an item and records which source revision it came from. | item_key, bundle |
list_tei_texts | Reads | Lists an item's TEI texts with their source revisions and latest revision numbers. | item_key* |
read_tei_text | Reads | Returns one TEI revision with its links between pages and images. | item_key, text_id, revision |
revise_tei_text | Writes | Adds a corrected revision of a TEI text, keeping the original and every earlier revision. | item_key, text_id, expected_revision, tei, page_map |
align_tei_page | Reads | Proposes which TEI words match the lines detected on a page image, and lists the words it could not match. Changes nothing. | item_key, text_id, revision, ordinal, source_key, canvas |
export_tei_text | Reads | Exports one corrected revision for import into ESTC. | item_key, text_id, revision |
Reading texts in order
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
reading_sequence | Reads | Lists what to read and in which order: chosen items, a corpus's sources or records, or an arrangement in its editors' order. | item_keys, corpus_id, perspective_id, node_id, grain, view, at, entity_id, role, start, end, order |
read_text | Reads | Returns an item's text as blocks (headings, paragraphs, verse lines) with the page each starts on, from its TEI edition, transcription, record or file. | item_key*, unit, style, offset, limit, corpus_id, record_id, reading_id, manifest_id, attestation_id, node_id |
find_in_text | Reads | Finds every occurrence of a word or phrase in an item's text, ignoring case and accents, with the page and the words around it. | item_key, query, offset, limit, unit, style, corpus_id, record_id, reading_id, manifest_id, attestation_id, node_id |
Analysis and corpora
A corpus is a named set of sources that are analysed together for people, places, dates and events (How analysis works). The assistant can read a corpus's results, or it can analyse a source with its own model and submit what it found, which is described in Source inventories and assistant-submitted analysis.
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
list_corpora | Reads | Lists the project's corpora with how many sources each holds and how many have been analysed. | — |
corpus_events | Reads | Lists the events a corpus's sources describe, in date order, each with its quotation. | corpus_id*, start, end, entity_id |
item_events | Reads | Lists the events one analysed source describes, in the order of its text, including those a reader rejected. | item_key*, unit |
corpus_records | Reads | Queries a corpus's records (letters, books, sermons, events) by who wrote or spoke and to whom, places, record type and date. | corpus_id*, filters, offset, limit |
corpus_network | Reads | Returns the network of who wrote or spoke to whom, with a link to the graph in Pangur. | corpus_id*, filters |
corpus_timeline | Reads | Returns records on a time axis, with their original dates and uncertain intervals. | corpus_id*, filters, offset, limit |
corpus_geography | Reads | Returns the places of a corpus's records and events, filtered by dates, with the evidence for each. | corpus_id*, start, end, layer |
corpus_series | Reads | Counts records or attestations by person, place, activity or source over days, months or years. The counts are of the corpus, not of a population. | corpus_id*, filters, interval, grouping, measure |
corpus_concepts | Reads | Lists what a corpus is about, by where each concept came from, with its evidence and the verdict of any test. | corpus_id* |
corpus_dating | Reads | Returns the corpus's dating assertions, their alternatives and the current revision. | corpus_id* |
get_analysis_evidence | Reads | Returns one record in full: all its parts, witnesses and evidence. | corpus_id, record_id, reading_id, manifest_id |
source_inventories | Reads | Returns a corpus's source inventories and import receipts, for resuming an import or exporting exact source revisions. | corpus_id*, import_key, with_payload |
update_analysis_context | Writes | Sets the historical period, regions and other context for a corpus before analysis and place matching. | corpus_id, guidance |
analysis_materials | Reads | Returns the exact units of a source's text for the assistant to analyse with its own model, with the values to pass back to submit_analysis. | item_key*, marker, offset, limit, corpus_id, boundaries |
plan_analysis_records | Reads | Checks proposed record boundaries against the source's text before analysis. Changes nothing. | item_key, source_hash, boundaries*, corpus_id |
submit_analysis | Writes | Saves the assistant's analysis of a source into Pangur Analysis, a few units at a time. Quotations must be exact. | analysis* |
get_analysis_submission | Reads | Shows which units of an earlier submission are saved and which are missing, so it can be resumed. | item_key, submission_key |
resolve_analysis_places | Writes | Matches a corpus's place names to places in the light of its context, and maps the ones with a single match. Decisions a person made are kept. | corpus_id*, refresh |
suggest_concept | Writes | Suggests a concept for a corpus. Pangur counts its expressions straight away; the blind test waits until you ask for it in Pangur. | corpus_id, label, description*, variants |
revise_corpus_dating | Writes | Adds a dating revision with its assertions and reason. | corpus_id, revision |
stage_source_inventory | Writes | Stages a source inventory without changing the live corpus. | corpus_id, manifest |
activate_source_inventory | Writes | Makes a staged inventory live, as a new revision that can be rolled back. Refused if the corpus changed in between. | corpus_id, manifest_id, expected_version* |
rollback_source_inventory | Writes | Restores the previous inventory as a new revision, keeping both. | corpus_id, expected_version |
Documents
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
list_documents | Reads | Lists the project's documents, newest first, optionally only those of one kind or drawing on one item. | kind, item_key, limit, start |
get_document | Reads | Returns a document's text, the items it drew on and its version history. | document_id*, version |
create_document | Writes, viewers too | Saves a piece of writing, such as a summary or literature review, as a document with the sources it drew on, and returns a link to it. A copy is also filed as a note. | body_markdown*, title, kind, sources, prompt |
append_to_document | Writes, viewers too | Saves a new version of a document with the full new text. The earlier versions stay readable. | document_id, body_markdown, title, sources, prompt |
Exhibitions
An assistant can build an exhibition draft, but it cannot publish the exhibition, apply a design to it, or place image, gallery, audio or video blocks.
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
list_exhibitions | Reads | Lists the project's exhibitions with their status: draft, published or unpublished. | — |
get_exhibition | Reads | Returns an exhibition's draft: its sections in order, each with its blocks. | exhibition_id* |
create_exhibition | Writes | Starts an exhibition draft. | title*, subtitle, summary_markdown |
add_exhibition_section | Writes | Adds a section to a draft. | exhibition_id*, title, kicker |
add_exhibition_block | Writes | Adds a block to a section, such as text, a heading, a quotation, a document, a IIIF leaf, a bibliography, a table or a chart. | exhibition_id, section_id, block_type, content, item_key, attachment_key, document_id |
compose_exhibition | Writes | Returns instructions for the assistant to build a draft from a brief and sources itself. Pangur composes nothing over MCP. | exhibition_id, brief, sources, document_ids, answer, deep |
get_exhibition_design | Reads | Reports a design composed in Pangur and how far its reading has got. | exhibition_id, version |
Arrangements, record links and source groups
An arrangement is a tree of levels and nodes in which you order sources your own way, alongside the built-in Library and Catalogue views.
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
list_perspectives | Reads | Lists the library's arrangements: the Library, the Catalogue and every custom arrangement with its levels. | — |
get_perspective | Reads | Returns one arrangement's levels and fields and its whole tree of nodes, each with the values it inherits. | perspective_id* |
create_perspective | Writes | Creates an arrangement, optionally with its levels. | name*, description, levels, flexible |
add_perspective_level | Writes | Adds a level below an arrangement's deepest one. | perspective_id, name, fields |
add_perspective_node | Writes | Adds a node, at the top or under another node. A node can stand for an item, a manuscript, a leaf, a region of a leaf or a span of text, or for nothing but its label. | perspective_id*, label, parent_node_id, item_key, manuscript_id, source_key, canvas_index, region, values, char_start, char_end |
arrange_texts | Writes | Divides an item's text into separate texts and places them under a node for the item. | perspective_id, item_key, spans, from_analysis, parent_node_id |
set_perspective_node_values | Writes | Records values in a node's fields. | node_id, values |
move_perspective_node | Writes | Moves a node under another parent at the same level, or to another position among its siblings. | node_id*, parent_node_id, sequence_index |
create_vocabulary | Writes | Creates a controlled vocabulary, a named list of terms that arrangement fields can use. | name, terms |
list_record_link_targets | Reads | Finds catalogue and arrangement records that an item could be linked to. | query |
list_library_record_links | Reads | Lists the links from an item to records, or from a record to items. | item_key, kind, record_id |
link_library_record | Writes | Links an item to a catalogue or arrangement record. | item_key, kind, record_id* |
list_source_groups | Reads | Lists the project's source groups and their members in order. | — |
save_source_group | Writes | Creates a source group, or adds and reorders its members. Members cannot be removed over MCP. | label, client_key, members*, kind, values, group_id, expected_revision |
Copies and parts
A copy is a set of files that together show a resource. An afternoon's photographs of a manuscript are a copy, and so is a library's digitisation of a book. The tools call a copy a surrogate set and each file in it a surrogate; the terms are explained in Resources, copies and surrogates.
| Tool | Kind | What it does | Main parameters |
|---|---|---|---|
list_surrogate_sets | Reads | Lists everything that shows a resource: its parts, its copies with their method, purpose and relation to earlier copies, their surrogates, and which surrogate is shown for each part. | resource*, role, purpose, part_id |
create_surrogate_set | Writes | Starts a copy for a resource. A copy can correct an earlier one (its images replace the earlier copy's for the parts it covers) or supplement it (it adds another view and replaces nothing). | resource, title, made_at, made_by, holder, method, purpose, relation, relation_to_id |
add_to_surrogate_set | Writes | Files photographs or library files of the same resource in a copy. A file already in another copy of that resource moves to this one. | set_id*, capture_ids, attachment_keys |
describe_surrogate | Writes | Records what one surrogate shows: the part, its role (such as verso or watermark), a region, or the surrogate it retakes. | surrogate_id*, depicts_part_id, role, region, replaces_id |
set_reading_copy | Writes | Makes a copy the resource's reading copy, the one the Read tab opens first. | set_id* |
add_resource_parts | Writes | Adds parts, such as pages, leaves or faces, to a resource that is not a catalogued manuscript. | resource, labels, kind |
Glossary
This page defines the terms Pangur uses on screen and in the documentation, and links each one to the page that explains it in full. It is the place to look when a familiar word seems to mean something particular in Pangur.
Command-line reference
This page lists every pangur command with its arguments and options, says which project each one works in, and marks the commands that edit, delete or use Pangur's model.