redis_scan_keys

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

With no annotations, the description carries the full behavioral burden and does well: it discloses non-blocking execution, automatic cursor handling, a hard limit of 200, and that include_meta performs concurrent metadata fetches. It does not describe error or failure behavior, but the read-only nature and pagination mechanics are otherwise clearly conveyed.

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 front-loaded with the core behavior before the Args block, and each parameter line earns its place. It is slightly verbose in repeating cursor semantics twice (prose and Args), but overall well structured.

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?

An output schema exists, so return values need no explanation, and the description covers pagination, filtering, and optional metadata enrichment thoroughly. Only the absence of guidance on choosing this over redis_execute_command leaves a small completeness gap.

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%, so the description must compensate entirely, and it does: it documents all 7 parameters with defaults, the hard cap on limit, the accepted type values (string/hash/list/set/zset/stream), the db range 0-15, and that only 'default' connection exists. This is meaningfully richer than the bare schema.

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 a specific verb and resource – a non-blocking aggregated scanner that retrieves matching key names and handles cursor pagination internally. It is clearly distinguishable from redis_inspect_key (per-key inspection) and redis_execute_command (raw command execution), though it never names those siblings explicitly.

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 gives useful operational context: pass the previous page's cursor to resume, use include_meta=True to avoid N+1 round trips. However, it offers no explicit when-to-use/when-not-to-use guidance relative to redis_execute_command, which could also run SCAN, so routing is left to inference.

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