build_list_ancestries

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

No annotations are provided, so the description carries the burden. It discloses a key behavioral trait: legacy-flagged ancestries are excluded by default, and explains that 38% are still playable. This goes beyond a simple 'list' and arms the agent with important context, though it omits minor details like sorting or response format.

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 moderately sized and front-loaded with the main purpose. The detailed explanation of include_legacy is valuable, but the internal reference 'See `_legacy_filter_sql`' is an implementation detail that adds little for an agent. Overall, it is concise and well-structured, earning a high score.

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 tool's simplicity (2 params, no nested objects) and the presence of an output schema (so return values need not be explained), the description is complete. It covers the primary purpose and the non-obvious legacy behavior, which is sufficient context for an agent to 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?

Schema description coverage is 0%, but the description compensates: 'filter' is clarified as a name substring, and 'include_legacy' is explained in depth, including its default behavior and the 38% legacy-flagged ancestries. This adds meaning beyond the bare schema types, though it doesn't provide explicit syntax or examples for the filter parameter.

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's function: 'List playable ancestries, optionally filtered by name substring.' This specifies the verb (list), resource (playable ancestries), and optional filtering. It distinguishes itself from sibling tools like build_list_backgrounds and build_list_classes by focusing specifically on ancestries.

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 provides clear context for when to set the include_legacy parameter, advising to set it True when the user wants the full catalog. It does not explicitly mention alternative tools or exclusions, but the tool's purpose and siblings make selection obvious, and the parameter guidance is a useful decision point for the agent.

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