Skip to main content
Glama

List events and programs

list_events
Read-onlyIdempotent

Find library events and programs such as storytimes, book clubs, classes, and author talks by branch, date range, audience, and event type; get start/end times and registration requirements.

Instructions

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.

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": "list_events"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoResults page, up to 20 events per page.
limitNoReturn at most this many events from the page. Use a small number when you only need the next few.
queryNoKeywords to search event titles and descriptions.
branchNoOnly events at this branch (name or code).
libraryNoLibrary system id such as "tpl" (Toronto), "vpl" (Vancouver), "chipublib" (Chicago). Get it from find_library. A city or library name also works.
audienceNoAudience name, matched loosely, e.g. "school age", "teens", "adults". Valid values are returned in available_filters.
end_dateNoLast day to include (YYYY-MM-DD).
event_typeNoEvent type, matched loosely, e.g. "book club", "crafts". Valid values are returned in available_filters.
start_dateNoFirst day to include (YYYY-MM-DD).

Output Schema

NameRequiredDescriptionDefault
pageYes
pagesYes
totalYes
eventsYes
sourceYesProvenance of the data.
libraryYes
available_filtersYesValid values for the audience and event_type inputs at this library.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.3

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds some value by noting results carry local start/end times and a registration-required flag, but it says nothing about result volume, pagination behavior, or what open-world coverage means in practice.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with what the tool finds before listing filters and return content. No filler or redundant phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema and full annotation set exist, so the description only needs to frame purpose, filters and result character, which it does. Minor gaps: it never hints that the library id should come from find_library, nor how paging interacts with the 20-per-page cap, both of which affect a correct call.

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 100% with all nine parameters documented, so the schema carries the semantics. The description restates only four of them (branch, date range, audience, type) and adds no syntax or formatting detail beyond the schema's own examples, so it does not exceed the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Uses a specific verb ("Find") with a concrete resource ("events and programs at a library") and enumerates real event types (storytimes, book clubs, classes, author talks), which makes it clearly distinct from a catalog/title search tool. It does not name a sibling or state the boundary explicitly, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The filtering sentence implies the situations where the tool is appropriate (by branch, date, audience, type), but there is no explicit when-to-use versus when-not guidance and no mention of alternatives such as search_catalog for books or find_library for resolving the library id. Usage is inferable rather than stated.

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