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

Annotations already cover read-only, idempotent, non-destructive, so the safety profile is handled. The description adds value beyond that with the hard 200-row cap and the returned field set (name, type, ID), which matters because there is no output schema. It stops short of describing ordering or what happens when the cap is hit.

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, zero waste. The primary behavior and row cap come first, the escalation path second — front-loaded exactly as an agent scanning tools would want.

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 one-parameter read tool with full annotations, this covers purpose, limits, returned fields, and the alternative. The only gap is the ambiguity around whether the `type` param belongs to this tool or should be delegated to actor-filter.

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 single parameter is fully documented in the schema (100% coverage), so the baseline is 3. However, there is mild friction: the description enumerates "creature type" as an actor-filter concern even though actor-list itself has a `type` filter param, which could make an agent second-guess whether to pass it here.

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?

Specific verb + resource ("List actors in the world") plus an explicit scope statement ("plain listing, at most 200 rows"). It names the returned fields and contrasts itself with actor-filter, so an agent can distinguish it from siblings without opening a schema.

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 routes the agent: use this for a plain listing, use actor-filter for anything by name, CR, creature type, size, folder, HP, AC. The when-to-use and the alternative are both named outright rather than implied.

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