Get Redis cache stats

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

Annotations declare readOnlyHint=true, and the description adds significant behavioral context: the tool is best-effort due to version-dependent SQL surface, validates server existence, and returns an object with specific fields including available, key_count, etc. It also mentions the return format and provides a diagnostic note. No contradiction with annotations.

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 concise, front-loaded with purpose, then explains behavior, lists return fields, and provides an example. Every sentence adds value, no fluff.

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 (2 parameters, simple output schema), the description is complete. It covers the best-effort nature, validation, return fields, and even references list_databases for the optional parameter. The output schema exists, so return values are covered.

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 50% (only database has a description). The description provides an example showing the server parameter but does not elaborate on its meaning beyond the name. The database parameter's description in the schema is sufficient, but the tool description adds no extra semantics for server. The description is adequate but not compensatory beyond baseline.

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 gets best-effort cache metrics for a redis_fdw server, with specific verb and resource. It distinguishes from live Redis queries by noting that operators should query Redis directly for live metrics, and it appears among siblings like list_redis_foreign_servers and describe_redis_cache_table, providing enough differentiation.

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 explicitly tells when to use (for cache metrics via redis_fdw) and when not to use (for live metrics, query Redis directly). It also explains the best-effort nature and the validation behavior (checks server existence, reports available=false with diagnostic). Provides an example and references list_databases for the optional parameter.

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