List creatures by criteria

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

Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond these: how unknown filters are handled (reported as ignored), the no-adapter behavior (filtering refused, unfiltered list returns all actors), and the limit behavior (default 100, max 1000). These are operational traits not covered by annotations, and they align with the read-only idempotent nature.

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 efficient. It front-loads the purpose and usage, then details system-specific filters and edge cases. Every sentence contributes meaningful information, but the length is near the upper bound for a tool with 25 parameters. The structure is logical—purpose, filter understanding, fallbacks—and avoids redundancy, but a slightly tighter wording could improve conciseness.

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 complexity (25 parameters, multiple game systems, no output schema), the description covers the essential context: what the tool returns (a list with little data per creature), how to use it for encounter building, the system-specific filter behavior, unknown filter handling, no-adapter fallback, and the limit. It also directs users to get-compendium-item for details, completing the workflow. No critical missing information 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?

Schema description coverage is 100%, so each parameter is already well-documented individually. The description adds value by explaining how filters are interpreted across different game systems (e.g., challengeRating for D&D 5e, level for Pathfinder 2e) and the global behavior when filters are not recognized. This semantic layer ties the parameters together, but it doesn't add per-parameter meaning beyond what the schema already provides; hence a 4 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 opens with 'Creature discovery for encounter building' and specifies 'a long list of creatures matching criteria' with 'little data per creature', clearly stating the verb (list) and resource (creatures). It explicitly differentiates itself from get-compendium-item by advising to fetch details only for the final selection, so an agent can distinguish it from sibling tools without ambiguity.

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 explicit usage guidance: it's for encounter building, filters are system-specific (with a breakdown per game system), and it states that filters the active system does not know are reported as ignored. It also explains the fallback when no adapter exists (filtering is refused) and that a call without filters lists every actor by name. This gives clear when-to-use instructions and exclusions, including the alternative get-compendium-item for details.

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