norns_status

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

With no annotations, the description must carry behavioral disclosure, and the read-only guarantee ('Sends nothing that changes the norns') is a genuinely useful safety statement that goes beyond the empty schema. It says nothing about operational traits that matter for connectivity probes — latency, timeouts, or whether SSH/REPL checks can hang or fail partway — so the disclosure is partial.

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 sentences with no filler, and the read-only assurance is placed last as a clean safety note. It would be stronger if the headline ('reports health of the norns') came first before the field enumeration, but the current form is still tight.

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?

A zero-parameter read-only probe with an output schema is a simple tool, and the description covers both what is checked and that nothing is mutated. The only meaningful omission is operational behavior around SSH/REPL reachability probing, which the schema cannot express.

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, so there is nothing for the description to disambiguate; baseline 4 applies. The listed status fields do not correspond to inputs and are not presented as such, so no confusion is introduced.

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 the concrete facts returned (SSH reachable, norns version, service states, REPL reachable, running script, server live), which makes the tool's function as a health/status probe unambiguous. It falls short of a crisp verb+resource statement and does not acknowledge overlap with siblings such as norns_current_script, which also reports the running script.

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 closing line 'Sends nothing that changes the norns' implies this is the safe, non-mutating choice for checking on the device, which suggests when to prefer it over load/start/stop siblings. However, it never explicitly states when to call it, no prerequisites, and no named alternatives, so the guidance is only implied.

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