get_screenshot_data

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

With no annotations, the description carries the full burden and does substantial work: it discloses the side effect (writes a LOCAL file under MHO98_DATA_DIR), the return contract (path + size, never the blob), inherited configurability via :SAVE:IMAGe:* options, and format detection from magic bytes. Missing only edge-case behavior such as overwrite handling or failure modes.

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?

Front-loaded with the core action and kept to three short sentences. The parenthetical listing of :SAVE:IMAGe:* options is dense but earns its place by routing the agent to configure_save for details.

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 single-optional-parameter read-and-write-to-disk tool with no annotations, the description covers the query used, the destination, the return shape, and the option dependencies. An output schema exists, yet the description still usefully states what is returned; only the filename parameter's semantics remain unexplained.

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 coverage is 0% for the single optional `filename` parameter, so the description must compensate. It clarifies the destination directory (MHO98_DATA_DIR) and that the output is a file path, but says nothing about how `filename` is interpreted (relative vs absolute, default naming when null, extension injection) — only partial compensation for the coverage gap.

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?

States a specific verb (fetch) and resource (current screen bitmap), names the exact SCPI query used, and explicitly distinguishes itself from the display subsystem's :DISPlay:DATA? screenshot and, by implication, the sibling get_screenshot. An agent can identify the operation without opening the schema.

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 identifies itself as an alternative to the :DISPlay:DATA? screenshot path and points to `configure_save` for the :SAVE:IMAGe:* options that govern output. However, it never states a condition for choosing this over the sibling get_screenshot or the display path, so the routing decision is left implicit.

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