get_console_state

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

The readOnlyHint annotation already signals this is a non-mutating operation. The description adds useful behavioral context by noting the state is cached and by listing the returned dimensions, but it does not disclose details like staleness semantics or whether any connection-specific setup is required. This is adequate but not rich.

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 one short, front-loaded sentence that names the action, the resource, and the key return components. Every word earns its place, and there is no redundant filler.

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-parameter, read-only tool, the description provides enough context to know what data will be returned and that it is cached. It is slightly light on the exact shape or formatting of the user/connection values, but the absence of an output schema and the tool's simplicity make this a minor gap rather than a blocking one.

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 coverage is effectively total, so there is no parameter meaning for the description to add. Per the rubric, a no-parameter tool starts at baseline 4; the description correctly avoids inventing parameter details.

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 uses a specific verb ('Return') and resource ('cached console state'), then enumerates exactly what state is included: blind/live, user, and connection. This clearly distinguishes it from sibling tools like cue_fire or channel_set_level, none of which return console state.

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 implies that the tool is used when an agent needs the current cached console state, and the sibling names make it clear that most other tools perform actions rather than reads. However, it does not explicitly state when to prefer this tool over alternatives such as get_active_cue or get_command_line, nor does it provide exclusions.

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