DualStream connection status

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

Annotations declare readOnlyHint=true, and the description does not contradict this. It adds meaningful behavioral context beyond the annotation, such as the meaning of consent state ('pending' means the streamer must approve the client) and the recommendation to use it as a first troubleshooting step. This enriches the agent's understanding of the tool's role and dependencies.

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 exactly two sentences: the first states the core purpose and output details, the second gives usage guidance. Every word earns its place, with no redundancy or 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 no-input diagnostic tool, this description is complete. It covers what the tool reports, the meaning of consent state, and when to invoke it. Even without an output schema, it gives enough information about the expected response to guide an agent.

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, so the baseline is 4. The description adds no parameter details (none are needed) but compensates by describing what the report includes (version, port, auth mode, consent state), which is helpful given the absence of an output schema.

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 the specific verb 'Report' and clearly identifies the resource (DualStream desktop app's control server reachability). It lists the exact information provided (app version, port, auth mode, consent state), making it distinct from sibling tools that manipulate scenes or triggers.

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?

It explicitly instructs to 'Call this first when other DualStream tools fail' and explains the diagnostic value: distinguishing 'app not running' from real errors. This is a clear when-to-use directive, and although no alternative tools are named, the tool's unique role makes this sufficient.

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