[ Docs ](https://yore.steddle.com/docs) [ Agents ](https://yore.steddle.com/docs/agents) The tools ========= Every tool the MCP server offers, the envelope each answer travels in, and the caveats to pass on. 04 Agents ------ Article 2 of 4 The MCP server offers 31 tools. Each one is a route of Yore's API under another name, so a tool answers exactly what the site and the [yore command](https://yore.steddle.com/docs/agents/the-command) get. This page lists them as the server describes them to an assistant. The envelope ------------ Every answer is one JSON object: ``` {"yore": 1, "data": { }, "caveats": [ ]} ``` - `yore` is the contract's number. It goes up when a consumer would have to change. - `data` holds the answer. - `caveats` states the limits on what the answer supports: that a version runs from its first capture to its last, that the archive didn't look in between. An assistant should pass each one on with the answer it belongs to. A failure carries `error` in place of `data`, with a `kind`, a finer `code` and a `message`: ``` {"yore": 1, "error": {"kind": "not_found", "code": "not_fetched", "message": "no version [9]"}} ``` | Kind | Means | |---|---| | `usage` | The request is wrong as asked. Asking again fails the same way. | | `auth` | No account, or not this account's. | | `not_found` | The thing doesn't exist as asked. A version that isn't fetched yet answers with the code `not_fetched`. | | `throttled` | Too many requests. `retry_after` says when to ask again. | | `archive` | The Internet Archive refused or didn't answer. | | `internal` | Yore failed. | The order of a plan ------------------- A plan goes through `plan_create`, `plan_tree` to see what the site holds, `plan_update` to set paths and languages, `plan_read` to read the archive's index, `plan_pages` and `plan_tick` to choose pages, `plan_coverage` to see what a run costs, and `plan_run`. Reading and running happen in the background, so an assistant polls `plan_show` and `plan_coverage`. Plans ----- ### `status` Who is connected, how many plans the account holds and its caps. Call it first. ### `plan_list` Every plan of the account: its website, its rules, its state and how many pages it holds. ### `plan_create` Make a plan for a website. Yore reads the site's sitemaps, today's and the archive's older ones, so plan\_tree can show what the site holds; the plan is `reading` until that is done. Name the paths and languages now or later with plan\_update, then call plan\_read. Takes `hosts` (required), `name`, `paths`, `locales`, `from`, `until`, `density`. ### `plan_show` One plan: its rules, its state (draft, reading, ready, indexing, indexed, running, paused, done, failed) and its counts. While it is busy, `progress` states the step it is on, how much of that is done, and the minutes left at the archive's pace where that sets the wait. Takes `plan` (required). ### `plan_update` Change a plan's rules. On a plan whose index was read, a path or language taken away takes its pages off the plan at once, and one added is read from the archive's index in the background: the plan is `indexing` until it is `indexed`, and its other pages stay. A plan never read needs plan\_read. Takes `plan` (required), `name`, `paths`, `locales`, `from`, `until`, `density`. ### `plan_delete` Delete a plan. The captures Yore fetched stay in its shared cache; the plan, its ticks, its exports and its share links go, and that cannot be undone. Takes `plan` (required). ### `plan_tree` What the website holds under one path, as Yore knows it from the sitemaps and the index: each child segment with how many pages lie under it, and the languages the site speaks. Use it to choose paths. Takes `plan` (required), `host`, `under`, `locale`. ### `plan_read` Read the archive's index for the plan's rules: every page its paths name, including pages the site has since removed, and every capture of each. Runs in the background; the plan is `indexing` until it is `indexed`. Costs one request or a few per path and language, and a path read in the last day is not read again. On a plan already read, this is how to learn what the archive captured since. Takes `plan` (required). ### `plan_pages` The pages on a plan, each with whether it is ticked, how many captures and versions it has, its first and last capture, and its removal if the archive shows one. Takes `plan` (required), `under`, `locale`, `ticked`, `removed`, `q`, `sort`, `limit`, `page`. ### `plan_tick` Tick pages in or out of a plan. Only ticked pages are fetched, compared and exported. Name the pages by id, by the start of their path, by language, by a part of their address, those removed or redirected, or all of them; filters narrow each other. Takes `plan` (required), `ticked` (required), `pages`, `under`, `locale`, `q`, `removed`, `all`. ### `plan_coverage` What running the plan costs and how far it is: ticked pages, captures in the window, distinct versions to read, how many are already fetched, how many requests remain, the minutes that takes at the archive's pace, and captures per year. Read it before plan\_run. Takes `plan` (required). ### `plan_run` Start fetching the plan's captures from the web archive. Yore fetches each distinct version once, at the archive's pace, taking turns with other plans; then it reads the text, builds the versions and fetches the images. Runs in the background: plan\_coverage shows progress. Takes `plan` (required). ### `plan_pause` Stop fetching for a plan. plan\_run resumes it. Takes `plan` (required). Reading ------- ### `page_show` One page: its versions in order, each from its first capture to its last with how many captures prove it, its removal, and its captures per year. Takes `plan` (required), `page` (required). ### `version_show` One version of a page: its text in sections, the whole text with nothing set aside, the capture it comes from (snapshot URL, UTC time, status, the archive's digest and the SHA-256 of the bytes Yore froze), and its images, each with the date of its own capture. Takes `plan` (required), `page` (required), `position` (required). ### `compare` Two versions of one page set against each other, section by section: which sections stayed, changed, came or went, with the text before and after, and how many words were added and removed. Takes `plan` (required), `page` (required), `from` (required), `to` (required), `whole`. ### `phrase` The life of a sentence: on which pages it stood, from which capture until which, how many captures prove it, the longest stretch the archive did not look, and the first capture without it. Letter case and typographic quotes are ignored. Quote the sentence as the page prints it. Takes `plan` (required), `q` (required), `page`. ### `changes` What changed across the plan, by month, newest first: pages that first appeared, pages whose text changed, and pages that were removed or redirected. Takes `plan` (required), `from`, `until`. ### `languages` The same page in the site's other languages on one date, each as its own latest capture on or before that date, in sections. Pages are paired by the hreflang links the page itself carries, or by the same path under another language. Takes `plan` (required), `page` (required), `at` (required). Evidence -------- ### `export_make` Make an export of the plan: one zip with every ticked page, each capture the archive holds in the window, each version, the bytes, the texts and the images, and a manifest with the SHA-256 of every file. Built in the background: export\_list shows when it is `ready`, with the manifest's own SHA-256. The file is downloaded on the site or with `yore export download`. Takes `plan` (required). ### `export_list` The plan's exports, newest first, each with its state, its size and its manifest's SHA-256. Takes `plan` (required). ### `exhibit_make` Print one comparison as an exhibit: a PDF with the two captures, their addresses in the web archive, their hashes, and every changed section word by word. Answers the PDF's SHA-256; the file is downloaded on the site or with `yore exhibit`. Takes `plan` (required), `page` (required), `from` (required), `to` (required), `whole`. ### `share_make` Make a link that shows one comparison, read-only, to whoever holds it. Only make one when the user asks to share: the link opens archived text to anyone. Takes `plan` (required), `page` (required), `from` (required), `to` (required), `whole`. ### `share_list` The plan's share links, each with its address, what it shows and whether it was revoked. Takes `plan` (required). ### `share_revoke` Revoke a share link. It closes for everyone who holds it. Takes `plan` (required), `token` (required). ### `verify` Whether Yore issued a file with this SHA-256, an export's manifest.json or an exhibit's PDF, and when. It says nothing of what the file holds. Takes `sha256` (required). Going forward ------------- ### `watch_set` Start or stop watching pages. A watched page is checked once a day with Yore's own client: a change is captured and frozen that day, and the Internet Archive is asked to capture it too. Takes `plan` (required), `pages` (required), `watched` (required). ### `watch_list` The pages the plan watches, each with its last check: when, what the site answered, and whether the page was captured, unchanged, changed, removed or blocked. Takes `plan` (required). ### `watch_check` Check one page now with Yore's own client. One request to the site, at most once a minute per page. Takes `plan` (required), `page` (required). ### `watch_log` Every check of a page, newest first: the ledger only grows. Takes `plan` (required), `page` (required). Other ----- ### `plan_resume` Hand a busy plan that went quiet to a worker again. plan\_show says `quiet` when a plan is reading, indexing or running and Yore has not heard from its job for 15 minutes: a worker stopped mid-way leaves it so. What was already read is kept. Refused while the plan is still at work. Takes `plan` (required). Checked against the code on 1 October 2026. [ Connect over MCP ](https://yore.steddle.com/docs/agents/connect-over-mcp) [ The yore command ](https://yore.steddle.com/docs/agents/the-command)