agent_status

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that: the agent is local to the user's machine and holds the qualified certificate on a USB token, which explains why probing its state matters and implies no server-side side effects. It says nothing about failure modes (what is returned when the agent is offline), which keeps it from a 5.

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, front-loaded with the direct question the tool answers, followed by only the context needed to understand what the agent is. No filler, nothing repeated from annotations.

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?

For a zero-param status probe with full annotation coverage and no output schema, the description adequately covers what the call reports and what the agent represents. The remaining gap is the offline case — an agent would benefit from knowing what a negative result looks like or what to do next, but nothing essential is missing.

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 to disambiguate and the baseline is 4. The description correctly frames the call as a simple query requiring no input.

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 a precise purpose: checking whether the local Storno Agent is running, its version, and update availability — three concrete answers from one call. The second sentence distinguishes the local desktop agent from the cloud backend, which is the key conceptual split against siblings like system_version or agent_certificates, though it never names an alternative explicitly.

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?

Usage is only implied: an agent would infer this is the pre-flight check before agent-dependent operations (agent_sign_pdf, declarations_file_via_agent), since the description explains the agent holds the signing certificate. There is no explicit when-to-use, when-not-to-use, or pointer to sibling tools such as agent_certificates for certificate details.

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