status

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

With no annotations, the description fully discloses behavior: it always includes version, conditionally includes roots/dbPath/model/hybridWeight/counts or indexError/configError, explains chunkScheme, staleChunkCount, schemeWarning, ocr engine status, and ocrHint. This goes well beyond a simple status report and covers expected edge cases.

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 a one-sentence summary, then organized into logical paragraphs for valid/invalid configuration, chunk scheme, and OCR. Each sentence adds unique value—no filler or repetition—making it appropriately sized for the information conveyed.

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?

The description covers all major behaviors and edge cases: invalid configuration, index open failure, chunk scheme staleness, and missing OCR extras. Since an output schema exists, it doesn't need to detail return values, but it still explains the meaning of key fields, making it complete for a status tool in a complex setup.

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 has zero parameters, and the input schema is an empty object. The description adds no parameter-specific semantics because none are needed. Baseline for 0 params is 4, which fits here.

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 reports configuration and index status, with a specific verb and resource. It also distinguishes itself implicitly by noting it works even when configuration is invalid, which sets it apart from other tools, though it does not explicitly name alternatives like sync_status.

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 provides clear context for when to use this tool: it works even when configuration is invalid, and it notes that every other tool raises an error referencing configError until fixed, implying this is the diagnostic tool. However, it does not explicitly say 'use this instead of X' or list alternative tools by name.

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