Stacks
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PORT | No | Port for `--http` mode. | 3000 |
| STACKS_PROXY | No | Proxy mode: `off`, `auto` (retry through a TinyFish proxy if blocked), `tinyfish`, or a country code. | auto |
| TINYFISH_API_KEY | Yes | Your TinyFish key (required). | |
| STACKS_HTTP_TOKEN | No | Secret required by `--http` mode when it uses the server's own key. Default: none. | |
| STACKS_AGENT_WAIT_MS | No | How long Agent tools wait before returning a `job_id`. | 40000 |
| STACKS_DEFAULT_LIBRARY | No | Library id used when a call omits `library`. Default: none. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Stacks gives you live access to public library websites (catalogue, branches, events) through typed tools. Data is read from the library's website at call time by TinyFish; it is not from memory or a search index.
Typical flow:
find_library("Toronto") -> library_id "tpl". Pass it as
libraryto every other tool.search_catalog -> title_id. Then check_availability (which branches have it on the shelf), estimate_wait (hold queue), or get_title (details).
list_branches / get_branch for hours and services. list_events for programs.
ask_library for open questions about services and policies (slow; may return a job_id for get_job_result).
watch_title to be told when availability changes.
Errors are structured: { error: { code, message, hint } }. SITE_CHANGED means the website changed and the tool is broken: tell the user, and run health_check for details. Never guess an answer after an error.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| find_libraryA | Find the public library system for a city or library name and get its library_id. Call this first: every other tool needs the library_id. Covers library systems whose catalogue runs on BiblioCommons (e.g. Toronto, Vancouver, Chicago, Seattle, San Francisco, Boston, Ottawa, Calgary). |
| search_catalogA | Search a library's catalogue for books, eBooks, audiobooks, DVDs and more. Returns typed titles with live availability counts and hold queues. Use the title_id of a result with check_availability to see which branches have a copy on the shelf. |
| get_titleB | Full details for one title: description, contributors, publisher, ISBNs, subjects, series, and every other format the library holds it in. |
| check_availabilityA | Live, copy-level availability for one title: which branches have it on the shelf right now, call numbers, and due dates for checked-out copies. Branches with a copy on the shelf are listed first. |
| estimate_waitA | Estimate how long you would wait if you placed a hold today, from the live hold queue, copy count and due dates. Also lists other formats of the same work with a shorter queue. This is an estimate computed by Stacks, not a figure published by the library. |
| list_branchesA | List a library system's branches with address, phone, today's hours and whether each is open right now. Pass coordinates to sort by distance. Use get_branch for a branch's full weekly hours and services. |
| get_branchB | Everything about one branch: weekly hours, whether it is open now, upcoming holiday closures, services and facilities (meeting rooms, printing, makerspaces), accessibility, parking and directions. |
| list_eventsA | Find events and programs at a library: storytimes, book clubs, classes, author talks. Filter by branch, date range, audience (e.g. kids, teens, adults) and type. Returns typed events with local start and end times and whether registration is required. |
| ask_libraryA | Answer an open-ended question about a library's services, policies or facilities by having a TinyFish Agent browse the library's own website. Use it for things the other tools do not cover, e.g. 'How do I get a card as a non-resident?', 'Can I book a study room at North York Central?', 'What are the overdue fines?'. Much slower than the other tools: a full answer usually takes 1 to 3 minutes. This call waits about 40 seconds; if the Agent is still working it returns status 'running' with a job_id, and you call get_job_result with that id until it is done. |
| get_job_resultA | Fetch the result of a slow TinyFish Agent run that another Stacks tool started (a job_id from ask_library, a fallback_job_id from an error, or a diagnosis_job_id from health_check). If status is still 'running', wait about 15 seconds and call again. |
| watch_titleA | Create a standing watch on a title using TinyFish Monitor. TinyFish re-reads the title's page on a schedule and detects when its availability changes (for example a copy comes back on the shelf). Notifications go to the webhook you pass, or to the alerts set up in the TinyFish dashboard. Use list_watches to see watches and their current availability. |
| list_watchesA | List the title watches created with watch_title. Set check_now to also read each title's live availability, so you can tell the user whether a copy is available yet. |
| cancel_watchA | Stop and permanently delete a watch created with watch_title. TinyFish stops re-checking the title and sends no more notifications. Only watches made by Stacks can be cancelled; get the watch_id from list_watches. Set dry_run to see which watch would be cancelled without cancelling it, for example to confirm with the user first. |
| health_checkA | Run live checks against a library's website to confirm every Stacks tool still works, and report exactly what broke if the site changed. Checks page landmarks (TinyFish Fetch) and the data contract of each tool using known-good queries (TinyFish Browser). Set deep to also start a TinyFish Agent that inspects a failing page and explains what changed. Takes about 20 to 40 seconds. Run this when a tool returns SITE_CHANGED. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 14 tools
Most tools have clearly distinct targets: list_branches vs get_branch, list_events, find_library, ask_library, and the watch trio (watch/list/cancel) are unambiguous. The main soft spot is the cluster around a single title — search_catalog, get_title, check_availability and estimate_wait all return title-level data and partially overlap (e.g. get_title and estimate_wait both list other formats), though the descriptions do a good job of drawing the lines and pointing to each other.
Almost everything follows a clean snake_case verb_noun pattern (get_branch, list_branches, list_events, find_library, search_catalog, check_availability, get_title, watch_title, cancel_watch, get_job_result). The only real deviations are health_check (noun_noun) and the slightly softer ask_library/estimate_wait, which are still readable and consistent with the rest.
14 tools is well within a healthy range and each one maps to a distinct capability: library lookup, branches, events, catalogue search, title detail, availability, wait estimation, a slow-agent fallback pair (ask_library/get_job_result), watch lifecycle, and diagnostics. Nothing feels padded or missing at the count level.
Discovery, branches, events, availability, alerts and a self-diagnostic path are all covered, and ask_library backstops policy questions. However the surface is read-only where the domain implies action: you can estimate a hold wait but there is no way to place or cancel a hold, and there are no account tools (my loans, holds, renewals), which are core library workflows. Also no get_event detail for individual events.