Index status

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that include_files enumerates every indexed file, hinting at a potentially large response, but it never warns about output size or cost, so the addition is modest.

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 tight sentences with no filler. Slight deduction because it opens with a bare list of returned fields rather than a framing clause like 'Returns index status', which would front-load the purpose more cleanly.

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?

With no output schema, the description usefully enumerates the return contents, which is what an agent needs from a status tool. It is adequate for a read-only one-parameter tool, missing only guidance on when to prefer it over other index-inspecting siblings.

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% and the sole parameter include_files has no schema description at all, so the description carries the full burden. It does define the parameter's effect ('lists every indexed file'), which is exactly the compensation needed for a single-parameter tool.

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 enumerates exactly what the tool reports (documents folder, index size, embedder, primary status, last sync), so the resource is unambiguous even though it never states a verb like 'reports'. It does not distinguish itself from siblings such as ragdown_list or ragdown_reindex, which is the only real gap.

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?

There is no statement of when to call this versus alternatives like ragdown_list or ragdown_reindex, and no prerequisites or context given. Usage is only inferable from the fact that it reports index state.

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