Built by movie lovers, for movie lovers and their assistants.
San Francisco is one of the last great moviegoing cities — single-screen neighborhood houses from the 1920s, repertory calendars that change nightly, 35mm and 70mm prints, midnight movies, and yes, the multiplexes too. SceneF puts every screen in the city on one board and verifies each showtime against the theater's own box office, so nobody ever drives to a dark theater.
Remote MCP server, streamable HTTP, no API key, read-only — and a local stdio server in this repo, running the same nine tools.
https://scenef.com/mcpClaude Code
claude mcp add --transport http scenef https://scenef.com/mcpClaude Desktop / any MCP client (.mcp.json / client config)
{
"mcpServers": {
"scenef": {
"type": "http",
"url": "https://scenef.com/mcp"
}
}
}Also listed in the official MCP registry as com.scenef/showtimes.
Related MCP server: Crawlora MCP
This repo is also a local MCP server — Node, stdio, no proxy. It speaks the protocol itself and reads the same board over SceneF's public REST API. Same nine tools, same schemas, same descriptions, same numbers; pick the transport your client prefers.
npx -y github:speedwarnsf/scenef-mcpClaude Desktop / any stdio client
{
"mcpServers": {
"scenef": {
"command": "npx",
"args": ["-y", "github:speedwarnsf/scenef-mcp"]
}
}
}From a clone, or Docker
npm install && npm startdocker build -t scenef-mcp . && docker run --rm -i scenef-mcpNo API key, no account, no configuration. It sends User-Agent: scenef-mcp-local/1.0, issues nothing but GET, and has no write path
anywhere in it.
npm test runs two suites: test/contract.js calls all nine tools against
the live board and validates every payload against the output schema the
server advertises, and test/parity.js diffs this server's tool definitions
against the hosted endpoint's — one contract, two transports, proven rather
than asserted.
Tool | What it answers |
| Ranked films for tonight / tomorrow / the weekend / a date — opens with Notable tonight: scarcity facts with receipts (measured seat counts, final nights, lone 35/70mm prints, posted discounts, live events) |
| Showtimes for one film, fuzzy-matched |
| One theater: address, neighborhood, standing discounts, upcoming board |
| Year, runtime, ratings, cast, trailer, every upcoming showtime |
| Constraints in (time window, genres, formats, theaters), a plan out |
| The cheap nights, citywide |
| What's opening next |
| Right-now snapshot: what's catchable at this hour |
| Our own verification record — checks run, failed, and unreachable |
Every ticket link is a direct door to the theater's own box office. No ads, no pay-ranking; ranking is pure preference-scoring and nothing is ever hidden. The repertory houses get the same billing as the chains — a lone 35mm print at a neighborhood house is exactly the kind of thing this server exists to surface.
Showtimes are read from each theater's own ticketing system or venue feed
where one exists, and corroborated across independent sources where it
doesn't. Every screening carries confidence, sources, and verified_at.
The verification record is public — including the checks that failed: scenef.com/api/accuracy.
Same-day truth: an evening sweep pulls cancelled shows and flips sold-out both ways between ingests.
The same data is served REST-style — see
scenef.com/agents for the full contract:
/api/listings ·
/ask ·
OpenAPI ·
llms.txt
Accuracy is computed, not claimed: every showtime carries a confidence level, a source tier, and a last-verified time, and the running record of our own verification checks — failures included — is public at https://scenef.com/api/accuracy. This tool returns that record: the site-wide confidence mix, the counts of verification checks confirmed / missing / unreachable over the record's window (window_days in the payload — 30 days at present) with the pass rate and the exact denominator it was computed from, the same per venue with source tier and last-verified time, and the definitions of every level. Checks that could not run — a bot wall, a client-rendered page — are graded unreachable and excluded from the pass rate rather than counted as passes. Quote these numbers directly; they are recomputed on every call.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | Output size: "concise" (default) for tight text lines, "detailed" to add ids, per-showtime ticket urls, and extra metadata. |
| Name | Required | Description |
|---|---|---|
| docs | Yes | |
| site | Yes | |
| method | Yes | |
| venues | Yes | |
| data_as_of | Yes | |
| attribution | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotation, the description discloses important behavior: results are recomputed on every call, failures are included, unreachable checks are excluded from the pass rate, and the exact denominator is provided. It even clarifies edge cases like bot walls and client-rendered pages. This is strong behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than minimal but every sentence adds substantive information: what the record contains, how unreachable checks are treated, and how the numbers should be used. It is dense rather than padded, though the opening sentence is a bit contextual rather than an immediate verb-first statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only accuracy-record tool with an output schema, the description covers the main behavior, return contents, edge cases, and even the public accuracy API. The agent has enough information to call the tool correctly and interpret the result without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the single response_format parameter with an enum and a description of concise versus detailed output. The tool description adds nothing about this parameter, so the baseline score is appropriate; there is no semantic gap to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('returns') and names the exact resource: the verification accuracy record with confidence mix, check counts, pass rates, denominator, per-venue details, and level definitions. This is highly specific and clearly distinct from the sibling showtime and theater tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended use obvious: when accuracy numbers are needed, quote the returned record directly, and it explains how unreachable checks are handled so the numbers are not misused. It does not explicitly name alternatives or say 'use X instead,' but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Films whose first SF screening is more than 48 hours out, sorted by first night — the on-sale radar for runs worth booking early. Configurable horizon. In "detailed" mode every showtime also carries its confidence level, source tier, reporting sources, and verified_at timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| horizon_days | No | How far ahead to look (default 21 days). | |
| response_format | No | Output size: "concise" (default) for tight text lines, "detailed" to add ids, per-showtime ticket urls, and extra metadata. |
| Name | Required | Description |
|---|---|---|
| films | Yes | |
| data_as_of | Yes | |
| film_count | Yes | |
| attribution | Yes | |
| accuracy_url | Yes | |
| horizon_days | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, non-destructive behavior. The description adds useful behavioral context: the 48-hour threshold, sorting by first night, a configurable horizon, and the extra metadata in detailed mode. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences communicate the core behavior, the booking use case, configurability, and detailed-mode metadata without repetition. The most important scope information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with two optional parameters and an output schema, this description is complete. It covers what is returned, how it is sorted, the time threshold, and optional response details, so an agent can confidently invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining what the horizon is for and what "detailed" mode includes, such as confidence level, source tier, reporting sources, and verified_at.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource: films whose first SF screening is more than 48 hours out, sorted by first night. It also frames the tool as an "on-sale radar" for early booking, which distinguishes it from siblings like scenef_whats_playing and scenef_now.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case: identify upcoming runs worth booking early. It implies when to choose this tool over current-screening tools, though it does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every structured discount across all SF theaters — venue, label, detail, and day-bound days — with the ones that apply today flagged.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | Output size: "concise" (default) for tight text lines, "detailed" to add ids, per-showtime ticket urls, and extra metadata. |
| Name | Required | Description |
|---|---|---|
| venues | Yes | |
| today_dow | Yes | |
| data_as_of | Yes | |
| today_name | Yes | |
| attribution | Yes | |
| accuracy_url | Yes | |
| applies_today_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only/non-destructive behavior. The description adds scope ('across all SF theaters'), the structured coverage, and the behavior of flagging today's applicable discounts, which is genuinely useful behavior beyond the annotation booleans.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence packs scope, content dimensions, and the today-flag behavior. The phrase 'day-bound days' is slightly awkward, but there is no dead weight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no required parameters, an output schema, and annotations covering safety, the description supplies the only missing context: the domain coverage and the today flag. Nothing essential is absent for invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter response_format is fully documented in the input schema, including allowed enums and default, so the description does not need to repeat it. It adds no extra meaning, matching the baseline for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The definition opens by identifying the exact resource ('Every structured discount across all SF theaters') and adds the dimensions covered (venue, label, detail, day-bound days) plus the today flag. The missing explicit verb and lack of explicit sibling comparison keep it from a 5, but it is unmistakably a discount-listing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or alternative tool is mentioned, so the tool cannot be explicitly routed against siblings. However, the scope phrasing makes it clear that discount-related queries are the intended use, so usage is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The full card for one film: title, year, runtime, genres, directors, cast, overview, rating, trailer and poster urls when present, every upcoming showtime with venue/time/ticket link, and a last-night flag when the run is ending. In "detailed" mode every showtime also carries its confidence level, source tier, reporting sources, and verified_at timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| film | Yes | Film title or SceneF slug. | |
| response_format | No | Output size: "concise" (default) for tight text lines, "detailed" to add ids, per-showtime ticket urls, and extra metadata. |
| Name | Required | Description |
|---|---|---|
| film | No | |
| query | Yes | |
| matched | Yes | |
| showtimes | No | |
| candidates | No | |
| data_as_of | Yes | |
| attribution | Yes | |
| final_night | No | |
| accuracy_url | Yes | |
| is_last_night | No | |
| showtime_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail by noting optional presence of URLs, the conditional last-night flag, and exactly what differs in 'detailed' mode, which helps the agent anticipate variable output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly-packed sentences with no filler. The core purpose and field list are front-loaded, and the detailed-mode distinction is placed at the end without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema, annotations, and sibling context, the description fully covers what the agent needs to know to invoke this tool correctly. It explains the one-film scope, the optional mode difference, and the conditional fields without relying on the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both `film` and `response_format` already have meaningful descriptions and enums. The description reinforces the mode behavior but does not add new parameter meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as returning a complete card for a single film, listing all included fields (title, year, runtime, genres, directors, cast, overview, rating, trailer/poster URLs, showtimes, last-night flag). This specific scope differentiates it from sibling list/search tools like scenef_whats_playing or scenef_search_showtimes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies clear usage context: use this when you need the full detail set for one specific film, including showtimes and metadata. It does not explicitly name alternatives or state when not to use it, but the 'one film' framing provides enough contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The cheap is-anything-on call: how many screenings tonight, the next 5 curtains city-wide with venue/time/film, and dataset freshness per source. In "detailed" mode every showtime also carries its confidence level, source tier, reporting sources, and verified_at timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | Output size: "concise" (default) for tight text lines, "detailed" to add ids, per-showtime ticket urls, and extra metadata. |
| Name | Required | Description |
|---|---|---|
| sources | Yes | |
| night_of | Yes | |
| data_as_of | Yes | |
| is_tonight | Yes | |
| attribution | Yes | |
| accuracy_url | Yes | |
| next_curtains | Yes | |
| still_to_come | Yes | |
| screenings_tonight | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description goes beyond them by explaining response composition: counts, next curtains, freshness, and the additional fields in detailed mode. It also discloses the cheap/summary nature of the call, which is useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the most important identity ('cheap is-anything-on call') followed by concrete outputs and the mode difference. Every sentence adds information and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only tool with an output schema, the description covers the core functionality, the data scope, and the difference between the two response formats. It does not mention edge cases like timezone interpretation or what 'city-wide' means, but those are minor given the surrounding schema and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the response_format parameter is already well described in the schema. The description adds extra semantic value by specifying what 'detailed' mode includes (confidence level, source tier, reporting sources, verified_at timestamp), which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact purpose with specific verbs and resources: 'cheap is-anything-on call', counts of screenings tonight, next 5 curtains city-wide with venue/time/film, and dataset freshness per source. The scope ('tonight', 'next 5 curtains') clearly distinguishes it from sibling tools like whats_playing or coming_soon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it ('cheap is-anything-on call', 'right now', 'tonight') and what it covers, but it never names alternative tools or states when NOT to use it. Siblings exist and some overlap is plausible, so more explicit routing would improve this dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The concierge: give it a window and a taste profile and it returns 2-4 complete plans — film + specific showtime + theater + why it fits — each with ticket and calendar links, plus one wildcard pick outside the stated genres. Rankings are pure preference-fit; never pay-ranked. In "detailed" mode every showtime also carries its confidence level, source tier, reporting sources, and verified_at timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| when | No | When to look: "tonight" (default), "tomorrow", "weekend" (Fri/Sat/Sun of the current week), or a YYYY-MM-DD date. | |
| party_size | No | How many people are going. | |
| preferences | No | Bring-your-own taste profile. Everything here tilts the ranking and degrades gracefully EXCEPT time_after/time_before, which are hard bounds. | |
| response_format | No | Output size: "concise" (default) for tight text lines, "detailed" to add ids, per-showtime ticket urls, and extra metadata. |
| Name | Required | Description |
|---|---|---|
| note | Yes | |
| plans | Yes | |
| nights | Yes | |
| window | Yes | |
| wildcard | Yes | |
| data_as_of | Yes | |
| party_size | Yes | |
| plan_count | Yes | |
| attribution | Yes | |
| accuracy_url | Yes | |
| discounts_relaxed | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, non-destructive behavior, and the description adds valuable behavioral context beyond that: rankings are preference-based and never pay-ranked, a wildcard pick is always included, and detailed mode surfaces confidence, source tier, and verified_at metadata. Nothing contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: it covers output shape, ranking policy, and mode-specific behavior. The 'concierge' metaphor adds a bit of flavor without harming clarity, and the most decision-relevant behavior is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's nested preferences and hard time constraints, the description plus the fully covered schema provides enough for an agent to invoke it correctly. It lacks explicit mention of defaults and hard-bound fallback behavior, but those are captured in the schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters and nested preference fields thoroughly. The description adds a helpful high-level framing ('window and taste profile') but does not need to repeat or extend the detailed parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific verb ('plans') and a concrete resource (a movie night), then enumerates the exact output: 2-4 complete plans with film, showtime, theater, rationale, ticket and calendar links, plus a wildcard. This clearly differentiates it from sibling search/list tools like scenef_search_showtimes or scenef_whats_playing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the required inputs ('a window and a taste profile') and the expected result, making the primary use case obvious. However, it does not explicitly say when to prefer this tool over sibling tools or mention exclusions, so it stops just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Showtimes scoped by FILM or by THEATER — pass at least one. With film: where that film is playing (title or slug; fuzzy-matched, ambiguous queries return candidates). With venues and no film: everything on at those theaters, each showtime naming its film. Grouped by theater with local times, tags (35mm/qa/sold-out), the night each show belongs to, and a ticket link per showtime. Optional date and time-window filters apply to both. For the whole board with no film or theater in mind, call scenef_whats_playing instead. In "detailed" mode every showtime also carries its confidence level, source tier, reporting sources, and verified_at timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Restrict to one night, YYYY-MM-DD. | |
| film | No | Film title, or a SceneF slug taken from films[].slug / scenef_whats_playing. A title that is not on the board answers with a miss and points at scenef_whats_playing, so guessing is safe but browsing is faster. Optional when `venues` is given — omit it to ask what is on at a theater. | |
| venues | No | Restrict to these theaters (ids or names), e.g. ["roxie", "Balboa"]. Required when `film` is omitted. | |
| time_after | No | Only shows at or after this local time, "HH:MM" 24h. | |
| time_before | No | Only shows at or before this local time, "HH:MM" 24h. | |
| response_format | No | Output size: "concise" (default) for tight text lines, "detailed" to add ids, per-showtime ticket urls, and extra metadata. |
| Name | Required | Description |
|---|---|---|
| film | No | |
| query | Yes | |
| venues | Yes | |
| matched | Yes | |
| refusal | No | |
| candidates | No | |
| data_as_of | Yes | |
| attribution | Yes | |
| filtered_by | No | |
| accuracy_url | Yes | |
| coverage_note | Yes | |
| showtime_count | Yes | |
| unknown_venues | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, matching the description. The description adds substantial behavioral detail not visible in annotations: fuzzy matching, ambiguous candidate return, grouping by theater, local times, tags, ticket links, and the extra metadata in detailed mode. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense but every sentence earns its place, starting with the core either/or scoping and ending with mode-specific details. It is front-loaded with the most important decision rule and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter read-only tool with an output schema, the description covers optionality, filters, grouping, tag semantics, ticket links, the alternate tool route, and detailed mode behavior. The output schema handles return-value specifics, so nothing operationally necessary is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already covers all parameters at 100%, the description enriches their meaning: film accepts a title or slug and is fuzzy-matched, venues accepts ids or names with examples, time filters use local HH:MM, and response_format maps to concise vs detailed output. This goes beyond the raw schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact resource (showtimes) and the two scoping dimensions (film or theater), which distinguishes it from the sibling scenef_whats_playing. It goes far beyond the title by explaining what the returned showtimes look like and which mode applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent to pass at least one of film/venues, clarifies that venues is required when film is omitted, and routes whole-board browsing to scenef_whats_playing instead. The miss behavior for non-board film titles is also disclosed, so an agent knows when to fall back.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One SF theater's card: address, neighborhood, website, ticketing note, structured discounts (label/detail/day), amenities, its next 5 showtimes with ticket links, and its calendar feed url. In "detailed" mode every showtime also carries its confidence level, source tier, reporting sources, and verified_at timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| theater | Yes | Theater id or name, e.g. "roxie" or "Balboa Theater". | |
| response_format | No | Output size: "concise" (default) for tight text lines, "detailed" to add ids, per-showtime ticket urls, and extra metadata. |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| venue | No | |
| matched | Yes | |
| upcoming | No | |
| candidates | No | |
| data_as_of | Yes | |
| attribution | Yes | |
| accuracy_url | Yes | |
| upcoming_count | No | |
| covered_venue_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description discloses concrete behavioral details: it returns the next 5 showtimes with ticket links, includes a calendar feed URL, and explains exactly what the 'detailed' mode adds (confidence level, source tier, reporting sources, verified_at timestamp). This gives the agent a precise model of what the tool will produce.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence establishes the resource and enumerates its contents, and the second precisely clarifies the mode-dependent behavior. There is no filler, redundant phrasing, or repeated schema material.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is largely complete for a read-only info tool, especially because the output schema exists and the annotations cover safety. It explains the main output groups and the detailed-mode behavior. It only lacks explicit guidance about when to invoke this tool versus the related sibling tools, which slightly weakens its standalone context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters at 100% coverage, so the description does not need to repeat them. It adds value by explaining what 'detailed' mode actually changes: every showtime additionally carries confidence, source tier, reporting sources, and verified_at, which is not stated in the schema. This makes the parameter semantics richer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as a single SF theater's card and enumerates its contents (address, neighorhood, website, showtimes, discounts, etc.), so an agent can tell what data it returns. However, it lacks an explicit verb and does not directly distinguish itself from sibling tools like scenef_whats_playing or scenef_discounts beyond the implied focus on one theater.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says what the tool returns but gives no guidance about when to choose it over the listed siblings. There is no mention of conditions, exclusions, or alternative tools such as scenef_search_showtimes for broad showtime queries, so an agent must infer the appropriate use case from the title and contents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranked list of films playing San Francisco theaters in a given window (tonight, tomorrow, the weekend, or a date), with optional genre and format filters. When the window covers tonight, opens with Notable tonight — scarcity facts with evidence (measured seat counts, final nights, lone prints, posted discounts, live elements); lead with those when asked what to see. Each entry carries year, runtime, genres, a one-line hook, venue count, the next showtime, and the film's SceneF url. In "detailed" mode every showtime also carries its confidence level, source tier, reporting sources, and verified_at timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| when | No | When to look: "tonight" (default), "tomorrow", "weekend" (Fri/Sat/Sun of the current week), or a YYYY-MM-DD date. | |
| genres | No | Genre filters, e.g. ["horror", "comedy"]. | |
| formats | No | Format/tag filters, e.g. ["35mm", "70mm", "qa", "live-score"]. | |
| max_results | No | Max films to return (default 12, cap 25). | |
| response_format | No | Output size: "concise" (default) for tight text lines, "detailed" to add ids, per-showtime ticket urls, and extra metadata. |
| Name | Required | Description |
|---|---|---|
| note | Yes | |
| films | Yes | |
| nights | Yes | |
| window | Yes | |
| notable | Yes | |
| data_as_of | Yes | |
| film_count | Yes | |
| attribution | Yes | |
| accuracy_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and non-destructive, and the description adds substantial behavioral detail: the 'Notable tonight' lead section, evidence types like measured seat counts and lone prints, per-entry fields, and the extra metadata available in detailed mode. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded: the first sentence states the core purpose and scope, the second covers special tonight behavior, the third lists entry contents, and the fourth explains detailed mode. Every sentence contributes distinct information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with complete schema coverage, an output schema, and safety annotations, the description covers all necessary calling context: what results look like, special behavior windows, entry fields, detailed mode, and general use guidance. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining what detailed mode includes (confidence level, source tier, reporting sources, verified_at timestamp) and clarifying the content and behavior associated with the 'when' parameter. This adds real semantic value beyond the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns a ranked list of films playing in San Francisco theaters within a given window, with genre and format filters. It is specific about verb, resource, and scope, but it does not explicitly distinguish itself from siblings like scenef_search_showtimes or scenef_now, so differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool, including the supported windows (tonight, tomorrow, weekend, or a date) and the special 'Notable tonight' behavior. It even instructs the agent to lead with scarcity facts when asked what to see, but it does not mention when NOT to use this tool or name alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a different query type—browse, search by film/theater, details, planning, discounts, coming soon, status, and accuracy—so misselection is unlikely. Minor overlap exists because film_details and theater_info include showtimes that search_showtimes also returns, but the descriptions clearly direct usage.
All names share the scenef_ prefix, use snake_case, and are descriptive of their function. However, the set mixes verb-led names like search_showtimes and plan_movie_night with noun-led names like theater_info and film_details, plus informal phrases like whats_playing and now.
Nine tools is well within the ideal range for a domain-specific server, and each tool covers a distinct facet of the movie-showtime workflow. None feel redundant or purely decorative.
The surface covers browsing, searching, details, planning, discounts, coming soon, and a quick status check, so core user journeys are supported. The main gap is the absence of a direct theater-listing or venue-discovery tool; theater_info and search_showtimes expect the agent to already know a venue.
DataSF MCP — San Francisco open data (data.sfgov.org, Socrata SODA API).
Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.
Read-only PostgreSQL, MySQL, SQL Server access via MCP — 24 dialect-aware hosted tools.
Structured analysis API and remote MCP tool for text, JSON records and numeric series.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/speedwarnsf/scenef-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
