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

No annotations are present, so the description carries the full safety burden. It discloses that any operation can be invoked, but does not warn about possible side effects, mutation, device-state requirements, or the need to call bmahs_describe/bmahs_occupy before executing. For a generic arbitrary-action tool this is a significant transparency gap.

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 concise sentences: the first front-loads the core behavior, the second clarifies the intended use cases. No filler or redundant restatement of the tool name.

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?

The description provides the essential call pattern and use cases for a generic dispatcher, but it does not explain how to discover the operations list, what the response looks like, or whether actions can mutate device state. With no output schema and no annotations, these are meaningful gaps.

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 baseline is 3. The tool description adds the useful idea that args must match the selected action's definition, but the schema property descriptions already state this; the description adds little beyond that.

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 states a specific action: execute any operation in the device's operations list, and explicitly positions it as the fallback for operations that do not have a dedicated tool. This clearly distinguishes it from specialized siblings like bmahs_screenshot or bmahs_describe.

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 gives concrete when-to-use guidance: for actions without a standalone tool or for temporarily inspecting a new device. The '尚未生成独立工具' condition implies preference for dedicated tools when available, though it does not name specific alternatives.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description is consistent with that by saying '读取'. The description adds useful context about what the tool returns (operations, security, self-description), but it does not disclose additional behavioral details such as error conditions or whether missing devices produce failures.

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 a single, compact sentence with no filler. It front-loads the action and resource before listing the returned content, making it immediately scannable and information-dense.

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 one-parameter read-only introspection tool, the description adequately conveys what the tool returns. There is no output schema, so the description's enumeration of operations, security, and self-description partially compensates, though it could mention what 'security' means or how failures are surfaced.

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 schema already documents the single parameter 'device' as '设备 id 或显示名' with 100% coverage, so the description needs to add little. The description's reference to '某台 BMAHS 设备' aligns with the schema but adds no new semantic detail about formats or constraints.

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 ('读取', read) with a specific resource ('某台 BMAHS 设备') and clearly enumerates the returned content: operations, security boundaries, and natural-language self-description. This distinguishes it from action-oriented siblings like bmahs_call and bmahs_occupy.

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 gives no explicit guidance on when to use this tool versus its siblings. It does not name alternatives or state conditions such as 'use before calling bmahs_call' or 'use to inspect device capabilities', leaving the agent to infer usage from the word 'describe'.

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

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

The annotations already include readOnlyHint: true, so the agent knows this is a safe read operation. The description adds value by listing the fields returned (id, display name, natural language description, type, status, occupant, connection address), which is useful context. However, it does not disclose any behavioral caveats such as pagination, performance, or data freshness, which would be relevant for a list tool. With annotations covering the safety profile, a 3 is appropriate.

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 two concise sentences with no fluff. It front-loads the primary action and return fields, then gives a clear usage directive. Every sentence earns its place, and the structure is efficient and scannable.

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 list tool with no output schema, the description adequately covers what the tool does, what it returns, and when to use it. It includes the key fields and the usage context. It does not address edge cases like empty results or the need to refresh the discovery list, but given the presence of a bmahs_refresh sibling, the 'currently discovered' phrasing implies current state. Overall, it is complete enough for an agent to invoke 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?

The schema description coverage is 100%, meaning the 'type' parameter is fully documented in the schema with its purpose (filter by category) and examples (light, display). The tool description does not add any additional meaning about the parameter; it does not even mention filtering. Since the schema already provides complete parameter semantics, the baseline of 3 is maintained.

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 clearly states the tool's purpose: '列出当前发现的全部 BMAHS 设备' (list all discovered BMAHS devices) and enumerates the returned fields (id, display name, description, type, status, occupant, address). It differentiates from siblings by positioning itself as the 'first' tool for device selection and occupancy checks, distinguishing it from more specific operations like occupy, release, or describe.

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 provides explicit usage guidance: '选设备、查占用状态时先用这个工具' (use this tool first when selecting a device or checking occupancy status). This tells the agent when to start, but it does not explicitly name alternative tools or state when not to use it. The guidance is clear and action-oriented, though it lacks the explicit sibling differentiation seen in the highest example.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: token persistence, gateway-managed lease enforcement, default TTL, upper-limit truncation, prohibition of indefinite leases, automatic reclamation on expiry, and manual release via bmahs_release. This is strong behavioral transparency.

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?

Three dense sentences, each earning its place. The main purpose is front-loaded, followed by lease constraints and the release alternative. No filler or redundant restatement of the schema is present.

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?

The description is nearly complete for a lease-acquisition tool: it covers default behavior, limits, automatic expiry, token handling, and release. It does not specify what happens if the device is already occupied or whether occupancy is blocked or queued, a small but relevant gap for an exclusive-occupancy tool. No output schema exists, but the token handling is disclosed.

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 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it clarifies that omitting ttl defaults to 120 seconds, that values beyond the default server cap of 3600 seconds are truncated, and that infinite leases are unsupported. This goes beyond the schema's field-level text.

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 opens with a precise action and resource: '独占占用一台 BMAHS 设备' (exclusively occupy one BMAHS device). It clearly identifies the tool's core purpose and distinguishes it from the release sibling by explicitly naming bmahs_release as the early-release counterpart.

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 gives clear operational context: leases are finite, default to 120 seconds, get truncated at the upper limit, and auto-expire. It also routes the agent to bmahs_release when the task ends. It does not explicitly state when not to use this tool versus bmahs_call or bmahs_screenshot, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=true, which the description does not contradict—refreshing is a read-like operation that updates a cached view. The description adds context beyond the annotation by specifying the mechanism (multicast query) and the effect (refresh self-descriptions), giving the agent a better mental model of what happens. It does not detail potential side effects like network traffic or latency, but given the read-only hint, this is acceptable.

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 two sentences with no fluff. The first sentence states the action and mechanism; the second lists the usage triggers. The most important information (what it does) is front-loaded, and every clause earns its place. It is compact yet comprehensive for a zero-parameter tool.

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?

Given the tool's simplicity (no parameters, no output schema, read-only annotation), the description covers the essential aspects: what it does, how it works, and when to call it. It does not describe the return value or post-refresh behavior, but since no output schema exists, this is not a critical gap. It is complete enough for an agent to invoke 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?

The tool has zero parameters, so the input schema is trivial (coverage 100%). The description does not need to explain parameter semantics, and the absence of parameters makes this dimension a non-issue. The baseline of 4 applies because there is nothing to document; the description correctly stays focused on the operation itself.

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 clearly states the action ('重新扫描' / rescan) and the resource (BMAHS devices), and explains it sends a multicast query to refresh each device's self-description. This distinguishes it from sibling tools like bmahs_devices (likely listing devices) and bmahs_describe (describing a device), as it focuses on refreshing the device list rather than retrieving or modifying specific entries.

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 explicit conditions for when to invoke the tool: when the device list is empty, a new device has just powered on, or the list is suspected to be stale. These clear triggers guide an agent to choose this tool over siblings, which have different purposes (e.g., bmahs_occupy/release for device control, bmahs_call/screenshot for device interaction).

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses the state mutation (releasing occupancy) and the system-level consequence of skipping the call: "否则其它智能体会一直收到「被占用」" (otherwise other agents will keep receiving 'occupied'). This reveals the locking semantics of the occupancy model. It does not cover idempotency or error behavior on double-release, but the critical behavioral traits are present.

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 dense sentences with zero filler. The first states the operation, the second gives the mandatory call-condition and the failure consequence. Every clause earns its place, and the core purpose is front-loaded in the first sentence.

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-parameter, no-output-schema tool, the description is nearly complete: it covers what the tool does, when it must be called, and the consequence of not calling. Minor gaps are the lack of return-value information and double-release behavior, but an agent has what it needs to invoke the tool correctly at the right time.

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% — the schema already documents `device` as "设备 id 或显示名" (device id or display name). The description adds no parameter-level detail beyond referring to "某台 BMAHS 设备" (a certain BMAHS device), which does not exceed what the schema already provides. Baseline 3 applies since the schema does the heavy lifting.

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 states a specific verb and resource: "释放对某台 BMAHS 设备的占用" (release the occupancy of a BMAHS device). It clearly identifies the inverse of the sibling bmahs_occupy without needing to open any schema, and is distinct from the listing, refresh, describe, call, and screenshot siblings.

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 gives explicit call timing: "任务结束、失败或取消后必须调用" (must be called after the task ends, fails, or is cancelled), telling the agent exactly when to invoke it. It also explains the consequence of omission — other agents keep seeing the device as occupied — which reinforces the condition. It stops short of explicitly naming the alternative (bmahs_occupy), but the when-condition is unambiguous.

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

Does 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.