rag_index_stats

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

There are no annotations, so the description carries the burden; it discloses that the operation is a passive report and describes its diagnostic role, making clear it mutates nothing. It omits the read-only/non-destructive framing explicitly and says nothing about cost, rate limits, or permissions. For a zero-parameter, side-effect-free diagnostic the remaining risk is low, but the disclosure is not exhaustive.

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?

Front-loaded with the one-line purpose, followed by the return contents and then the diagnostic trigger, in order of decreasing importance. Three sentences with no filler or redundant restatement of the tool name.

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 needn't be fully documented here, yet the description still previews the key fields to justify the call. With zero parameters and no annotations to reconcile, an agent has everything needed to invoke 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?

The tool takes zero parameters, which is the baseline-4 case: there is nothing for the description to disambiguate and the empty schema matches the stated behavior of reporting global service state.

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?

States a specific verb (report) and resource (index state / RAG configuration) and enumerates the concrete fields returned: collection name, chunk count, embedding and chat models, reranker, tracing flag. This makes it immediately distinguishable from the rag_search / rag_answer siblings, which retrieve content rather than describing the index itself.

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?

Gives an explicit trigger condition: "Call this first when a search returns nothing, to tell an empty index from a bad query." That is a clear when-to-use rule grounded in a sibling's failure mode. It stops short of naming explicit alternatives or stating when-not to call it (e.g. no need to poll per query), so a 4 rather than a 5.

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