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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description's genuinely additive behavior disclosure is that runners register via POST /v1/runner/hello and heartbeat every 30 s, which explains why 'online' is a heartbeat-derived, possibly stale status. Beyond that it says nothing about ordering, pagination, or what the output schema covers.

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 what a host contains and then the lookup form. The registration/heartbeat sentence is somewhat tangential to calling the tool but is short and earns its place by explaining the online/offline field.

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?

An output schema exists, so return-value explanation is not required, and the tool is read-only with only two parameters. Still, include_revoked is left undefined in both schema and description, and no sibling differentiation is offered among a very crowded list_* family, leaving a small but real gap.

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 description partially compensates by explaining that `host` accepts an hst_ id, a host address, or an agent_id, which is information the schema does not carry at all. The second parameter, include_revoked, is never mentioned, so the compensation is only half complete.

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 names the resource concretely (the computers/runners behind the workspace's agents) and enumerates what a host record exposes: system, runtimes with models and quota, free slots, current work, online/offline state. That is specific enough to distinguish it from list_agents or get_metrics without opening a schema, though it opens with a noun phrase rather than a verb and never explicitly says 'list'.

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 single conditional 'Pass host ... for one' implies the default is list-all versus fetch-one, which is real usage guidance. However, there is no guidance on when to prefer this over the many sibling list_* tools (list_agents, list_resources, list_leases) and no mention of when host lookup is the wrong call.

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