redis_execute_command

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 so richly: physical blocking of destructive commands (FLUSHALL/KEYS), a fail-close write gate, second-confirmation for high-risk deletes, automatic timeout rewriting for blocking reads (BLPOP/BRPOP), O(1) prechecks for unbounded reads, and result truncation at 100 items. Each of these is a non-obvious runtime behavior an agent needs in order to predict outcomes.

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 purpose and scope are front-loaded, and the bullet list of safety behaviors is scannable rather than a wall of prose. It is on the verbose side — the production HSCAN tip and the closing Returns note both overlap material covered elsewhere — but almost every line still carries actionable 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?

For a five-parameter, zero-annotation, side-effecting gateway tool, the description covers intent, argument semantics, safety gating, timeout/truncation side effects, and even outlines the return envelope, which the output schema also fully specifies. An agent has everything needed to call it correctly and anticipate edge-case responses.

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 and it does: it explains that 'command' and 'commands' are mutually exclusive, caps the pipeline at 20, notes 'connection' is effectively fixed to 'default', states db's 0–15 range and its silent binding to 0 in cluster mode, and confines 'confirm' to DEL/UNLINK with a pending-confirmation return when omitted.

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 opening sentence states a specific verb and resource — executing single-line raw Redis commands or a pipelined batch — and labels itself the 'core command gateway', which cleanly separates it from the read-oriented siblings (inspect_key, scan_keys, list_connections). An agent can tell what this tool is for without opening the 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 gives concrete usage direction: use 'commands' for single-round-trip batch execution (max 20), and prefer HSCAN/SSCAN/ZSCAN over HGETALL/SMEMBERS for large Hash/Set/ZSet reads in production. It stops short of explicit routing against siblings (e.g., when to prefer redis_inspect_key instead of a raw command), so it is clear context without full alternative coverage.

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