Capture a JPEG screenshot of the current screen from a BMAHS device with UI capability, returning the image and its saved file path. Automates UI start and stop for one-frame capture.
（实验）对声明了 ui 能力的 BMAHS 设备抓取一帧当前画面：自动 ui.start → 二进制流取一帧 JPEG → ui.stop，返回图片与保存路径。
| Name | Required | Description | Default |
|---|---|---|---|
| device | Yes | 设备 id 或显示名 | |
| max_width | No | 期望画面最大宽度（像素），设备按自身能力缩放 |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses the full operational sequence: automatic ui.start, JPEG frame capture from binary stream, and ui.stop, plus the return value. This goes beyond the schema and gives the agent a realistic model of side effects, though it does not discuss failure modes or permissions.
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 entire tool behavior, precondition, workflow, and return value are packed into one efficient sentence with no filler. The purpose is front-loaded and the lifecycle detail is presented in a clear, compact sequence.
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 simple 2-parameter tool with no output schema, the description covers the key return value (image and saved path), the precondition (UI capability), and the operational flow. It is slightly vague about the exact image representation (binary vs base64) but is otherwise sufficient for invoking the tool correctly.
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 100%, so the parameters are already documented in the input schema. The description does not add meaningful semantics beyond stating the screenshot purpose; max_width's scaling behavior is already described in the 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 a specific verb and resource: '对声明了 ui 能力的 BMAHS 设备抓取一帧当前画面' clearly states it captures a screenshot frame from UI-capable BMAHS devices. It also mentions the output (image and saved path), distinguishing it from siblings like bmahs_devices and bmahs_call.
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 provides clear context by restricting use to devices that declare UI capability and by outlining the automated ui.start → capture → ui.stop flow. It does not explicitly name alternatives or exclusion cases, but the precondition plus the very distinct purpose makes intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.