SceneF — San Francisco Movie Showtimes

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

Beyond the readOnlyHint annotation, the description discloses that the tool is safe, recomputes data on every call, and provides detailed behavioral context: unreachable checks are excluded from the pass rate, failures are included, and definitions are provided. It also mentions the public API URL and that no user/workspace filtering is implied.

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 well-structured and front-loaded with the core purpose. It is a bit long, but every sentence adds meaningful detail about the returned data, the grading of unreachable checks, and usage guidance. It balances depth with clarity, though it could be trimmed slightly without losing value.

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 that an output schema exists and the readOnlyHint annotation is present, the description thoroughly covers the tool's behavior, data items, and exclusion policy. It provides a complete picture for an agent to decide when and how to use it, including the fact that numbers are recomputed on every call.

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 schema fully documents the response_format parameter with an enum and description. The description adds a bit of context by mentioning 'concise' as the default and 'detailed' adds extra metadata, but the schema already covers the essential meaning. Baseline 3 is appropriate given 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 description clearly states that this tool returns the site-wide accuracy record, including confidence mix, verification check counts, pass rates, and definitions. It distinguishes itself from sibling tools by focusing on Scenef's own verification accuracy rather than showtimes, films, or theaters.

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 explains when to use the tool: when the user wants accuracy statistics, confidence levels, or verification pass rates. It instructs to quote the numbers directly and notes that checks that could not run are excluded. It does not explicitly name alternative tools, but the specific focus on accuracy metrics clearly differentiates it from the showtime/theater siblings.

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

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

Annotations provide readOnlyHint=true, so the safety profile is established. The description adds behavioral details such as the 48-hour threshold, sorting by first night, configurable horizon, and what detailed mode includes (confidence, source tier, reporting sources, verified_at). This goes beyond annotations without contradicting them.

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 sentences, front-loaded with purpose and followed by a concise explanation of the configurable horizon and detailed mode. Every phrase earns its place with no 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?

For a list tool with read-only annotation and no output schema, the description sufficiently explains the output's nature (sorted by first night, detailed mode metadata). It does not cover return format or pagination, but those are not critical for this simple use case.

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 schema already fully documents both parameters. The description reinforces the existence of a configurable horizon and detailed mode but adds no new semantic details beyond the schema. 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 states the tool lists films whose first SF screening is more than 48 hours out, sorted by first night. The title 'on-sale radar' and the contrast with siblings (now, whats_playing) reinforce its unique role.

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 usage as an 'on-sale radar for runs worth booking early', providing clear context. It does not explicitly list exclusion criteria or alternative tools, but the sibling names make the differentiation apparent.

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

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

Description adds context beyond the readOnlyHint annotation by noting that discounts applying today are flagged. However, it does not disclose other behavioral traits such as output format, sorting, or limitations beyond 'structured' discounts. With annotations covering safety, the addition is modest.

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 a single concise sentence that front-loads the core function and key distinguishing details. Every word adds value without unnecessary 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 simple read-only listing tool with one optional parameter and no output schema, the description provides a clear overview of what is returned. It could be slightly more complete by explaining 'day-bound days' or the response format, but overall it is sufficient for basic usage.

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 only parameter (response_format) is fully documented in the schema with enum values and description; the tool description does not add any parameter-specific semantics. Schema coverage is 100%, 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?

Description clearly states it lists every structured discount across all SF theaters, with specific elements (venue, label, detail, day-bound days) and flags today's applicable ones. This distinguishes it from sibling tools focused on showtimes, theater info, or film details.

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 guidance on when to use this tool versus alternatives. It does not mention any exclusions, alternatives, or prerequisites. While the purpose is clear, there is no explicit usage context.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral details: conditional inclusion of trailer/poster 'when present', a 'last-night flag when the run is ending', and mode-dependent fields ('In detailed mode...'). This goes well beyond what annotations provide and helps the agent anticipate output variations.

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 sentences front-loaded with the core purpose ('The full card for one film'), followed by a concise enumeration of included data and a conditional mode explanation. Every word earns its place with no 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?

The description thoroughly covers the tool's data output, conditional fields, mode differences, and specific metadata. Despite lacking an output schema, the description provides sufficient context for an agent to understand what the tool returns and when.

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?

With 100% schema coverage, the baseline is 3, but the description adds value by explaining the effect of 'detailed' mode on showtime metadata (confidence level, source tier, reporting sources, verified_at), which supplements the schema's brief enum description.

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 'one film' and states it returns the 'full card' with a comprehensive list of contents. This distinguishes it from sibling tools like search_showtimes or theater_info, which focus on other scopes.

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 (for a single film's comprehensive details) through the phrase 'for one film' and the exhaustive field list. However, it does not explicitly state alternatives or exclusions compared to sibling tools, so it stops short of full guidance.

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

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

With readOnlyHint=true already covering safety, the description adds meaningful context: it discloses that results include dataset freshness per source, and that 'detailed' mode adds confidence level, source tier, reporting sources, and verified_at timestamps. This enriches the agent's understanding of data provenance without contradicting the annotation.

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 sentences pack significant detail: the tool's purpose, core outputs, the data-freshness aspect, and explicit description of mode-specific additions. The lead phrase 'cheap is-anything-on call' immediately sets expectations, and every clause adds useful 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 simple read-only tool with one optional parameter and no output schema, the description fully covers what the agent needs: what the call returns, the two modes, and the extra metadata in detailed mode. The sibling list is not needed for this self-contained description.

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 schema already fully describes the single 'response_format' parameter (100% coverage), so the baseline is 3. The description goes beyond the schema by specifying exactly what extra metadata the detailed mode includes (confidence level, source tier, reporting sources, verified_at), adding valuable semantic context.

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 it answers 'is anything on' by returning screening counts, next 5 showtimes with venue/time/film, and data freshness per source. It specifies the resource (current screenings) and scope (city-wide tonight), but does not explicitly contrast with sibling tools like 'whats_playing' or 'search_showtimes', so it misses the top tier for sibling differentiation.

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 this is a 'cheap' quick-overview call, but it offers no explicit guidance on when to choose this over siblings. No alternatives are named, and no exclusions or conditions are provided. Usage context is only vaguely implied.

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

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

Annotations declare readOnlyHint=true, and the description adds substantial behavioral context: rankings are pure preference-fit and never pay-ranked, a wildcard pick outside stated genres is included, and detailed mode carries confidence/source/verified_at metadata. These disclosures go well beyond the structured annotation.

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 two well-structured sentences. The first sentence front-loads the core function and return value; the second adds ranking integrity and detailed-mode metadata. Every clause earns its place without redundancy or 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?

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: 2-4 plans, components, links, wildcard, and detailed-mode extras. It covers the main contract well, though it doesn't address edge cases like no available showtimes or error handling, leaving a small gap.

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 covers 100% of parameters with descriptions, so baseline is 3. The description adds value by clarifying response_format's detailed mode (adds confidence/source/verified_at), identifies window and taste profile as key inputs, and describes wildcard behavior for preferences. It doesn't individually elaborate all parameters but enhances meaning for a few.

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 specific verb 'plan' with resource 'movie night' and details the deliverable: 2-4 complete plans with film, showtime, theater, and rationale. It clearly distinguishes itself from sibling tools like scenef_search_showtimes by emphasizing curation and complete plans rather than raw results.

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 clearly implies when to use the tool: when you want a curated movie night plan from a time window and taste profile. However, it does not explicitly exclude alternatives or provide when-not-to-use guidance, so it loses one point for lacking explicit exclusions.

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

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

Annotations declare readOnlyHint=true, so the safety profile is known. The description adds rich behavioral detail: fuzzy matching, ambiguous query handling, grouping, tags, ticket links, and the detailed mode's extra metadata. This far exceeds minimal expectations and no contradictions exist.

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 three sentences, front-loading the core behavior then optional filters and detailed mode. Every sentence adds distinct value without fluff, making it appropriate in length.

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 output schema, the description relays the key output structure (grouped by theater, per-showtime ticket links, tags) and optional behaviors. It covers all parameter categories and the detailed mode's extra fields, making the tool's behavior fully understandable.

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 covers 100% of parameters, so baseline is 3. The description adds meaning by explaining that 'detailed' mode appends confidence level, source tier, reporting sources, and verified_at to each showtime, which complements the schema's enum description. It also contextualizes the date/time/venue filters as a group.

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 the tool provides upcoming showtimes for one film, with specific details like grouping by theater and fuzzy matching. It distinguishes from siblings by emphasizing 'one film' and the fuzzy-matched candidate behavior, though it does not explicitly name sibling 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 implies when to use this tool: when you need showtimes for a specific film, with optional filters. It does not explicitly mention alternatives like scenef_whats_playing or scenef_coming_soon, but the 'for one film' scope provides clear context.

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

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

The description explains what data is returned, including the default 5 showtimes and how 'detailed' mode enriches showtimes with confidence level, source tier, reporting sources, and verified_at timestamp. This goes beyond the annotation's readOnlyHint, providing meaningful behavioral context. No contradiction.

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 dense sentences lead with the core result and immediately enumerate the card's contents without filler. Efficient and well-structured.

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 tool with no output schema, the description enumerates the card's components and the optional mode's additions. It is sufficiently complete for an agent to understand what result to expect, though error behavior for invalid theater IDs is not mentioned.

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 with 100% coverage. The description reinforces the 'detailed' response_format by specifying exactly what extra metadata appears, adding value beyond the schema's 'extra metadata' phrasing.

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 opens with 'One SF theater's card' and enumerates specific fields (address, neighborhood, website, ticketing note, structured discounts, amenities, next 5 showtimes, calendar feed URL). This clearly distinguishes it from sibling tools like scenef_search_showtimes or scenef_whats_playing, which operate across theaters.

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 does not explicitly name alternatives or state when to prefer this tool over siblings. However, it clearly scopes to a single theater and lists the comprehensive card contents, making its intended use apparent. Lacks explicit exclusions or comparisons.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds value by disclosing exactly what each entry includes (year, runtime, genres, venue count, next showtime, SceneF URL) and how 'detailed' mode differs (confidence, source tier, reporting sources, verified_at). It does not describe ranking methodology or rate limits, but for a read-only listing this is adequate.

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 focused sentences front-load the core purpose and then detail the output fields and the detailed-mode distinction. There is no filler or repetition of schema information.

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?

As a read-only tool with no output schema, the description provides a comprehensive overview of inputs (window, filters, modes) and outputs (entry fields, detailed mode additions). It omits minor defaults like max_results or cap, but those are in the schema, so an agent has enough context to select and invoke this tool correctly.

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 provides descriptions for all five parameters at 100% coverage, so the description does not need to elaborate. It loosely mentions 'genre and format filters' and the 'when' window, but these are already documented. No additional semantic meaning beyond the schema is introduced.

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 opens with 'Ranked list of films playing San Francisco theaters in a given window', which clearly states the verb (list) and resource (films playing in SF theaters). It explicitly differentiates this from siblings like scenef_coming_soon or scenef_search_showtimes by focusing on current playing films with time-window and filter options.

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 by listing supported windows (tonight, tomorrow, weekend, or a date) and optional filters, making it obvious this is the broad 'what's playing' tool. However, it does not explicitly state when to prefer this over alternatives like scenef_search_showtimes, or provide any exclusions.

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