get_status

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

With no annotations provided, the description carries the full burden. It clearly states that the tool 'Returns' a specific list of status components, implying a read-only operation. This is sufficient transparency for a status getter, though it does not explicitly say 'does not modify server state' or mention potential limitations like staleness.

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 two sentences, front-loaded with the purpose, and lists the exact return categories without any fluff. Every word contributes meaning, and it is appropriately sized for the tool's simplicity.

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 tool is extremely simple (no parameters, no output schema), yet the description comprehensively lists all returned data categories, giving the agent enough to decide when to call it and what to expect. Sibling tools do not overlap, so the context is complete.

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 schema has 100% coverage (vacuously). The baseline for 0 parameters is 4. No additional description is needed, and the absence of parameter documentation is not a gap.

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 states 'Get comprehensive server status' with a specific verb and resource, and explicitly enumerates the returned data: server state, watcher status, indexing progress, index statistics, and exclusion patterns. This clearly distinguishes it from sibling tools, which are all actions (initialize, reindex, pause_watcher, etc.) rather than status queries.

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 that this tool is for retrieving overall server status, covering multiple aspects. While it does not explicitly mention alternatives or when-not-to-use, the sibling tools are all mutating or search operations, so the usage context is unambiguous. A bit more explicit guidance (e.g., 'Use when you need an overview') would have earned a 5.

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