List story arcs

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that output is ordered, grouped by saga, restricted to canon arcs, and omits arcs beyond the spoiler limit. It also explains the optional filtering behavior, giving an agent important behavioral context not present in structured 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?

Three economical sentences front-load the primary list behavior, add a secondary lookup mode, and close with the spoiler-limit caveat. No word is wasted and every sentence carries distinct 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?

Given one optional parameter, no output schema, and a straightforward list operation, the description covers the output shape (ordered, grouped by saga, chapter/episode ranges), the filtering behavior, and spoiler-limit interaction. Minor details like exact field names or empty-result behavior are not spelled out, but the description is strong enough for an agent to call it 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 schema already fully documents `chapter` as 'Only return the arc containing this chapter' (100% coverage). The description restates this as 'answers which arc is chapter N in?' and adds use-case framing, but provides no additional semantic details about types, defaults, or edge cases, so it earns the baseline 3.

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 names the resource ('canon story arcs'), the action ('list ... in order'), the grouping ('by saga'), and the output detail ('chapter and episode ranges'), and it also calls out the chapter-based lookup mode. This clearly distinguishes it from sibling tools like get_arc and get_chapter.

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 establishes two direct use cases—get the full ordered arc list, or resolve a chapter to its containing arc via the `chapter` parameter. However, it never names alternatives such as get_arc or get_episode, nor does it say when not to use this tool, so it falls short of the explicit routing bar.

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