Search showtimes for a film

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.