Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
PORTNoPort for `--http` mode.3000
STACKS_PROXYNoProxy mode: `off`, `auto` (retry through a TinyFish proxy if blocked), `tinyfish`, or a country code.auto
TINYFISH_API_KEYYesYour TinyFish key (required).
STACKS_HTTP_TOKENNoSecret required by `--http` mode when it uses the server's own key. Default: none.
STACKS_AGENT_WAIT_MSNoHow long Agent tools wait before returning a `job_id`.40000
STACKS_DEFAULT_LIBRARYNoLibrary 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:

  1. find_library("Toronto") -> library_id "tpl". Pass it as library to every other tool.

  2. search_catalog -> title_id. Then check_availability (which branches have it on the shelf), estimate_wait (hold queue), or get_title (details).

  3. list_branches / get_branch for hours and services. list_events for programs.

  4. ask_library for open questions about services and policies (slow; may return a job_id for get_job_result).

  5. 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

CapabilityDetails
tools
{
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A3.9/5.0

Scored across 14 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness3/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues