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

With no annotations, the description carries the burden well: it discloses idempotency, that only inbox state changes, and that voice content is not executed — useful behavioral context for a mutation. It omits error responses and what happens for an unknown event_id, so not a 5.

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 compact clauses with no waste, and the core action plus idempotency are front-loaded. Every sentence contributes; only minor verbosity from the trailing scope clause.

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 1-param, no-output-schema, no-annotation mutation tool, the description covers the essential scope and precondition. It still lacks any mention of failure behavior for invalid event_ids, which an agent reasoning about errors would want.

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?

One required parameter at 0% schema coverage, so the description must compensate. It ties event_id to identifying the voice message to acknowledge, adding some semantic value, but the uuid format and identifier origin are left to 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?

States a specific verb (确认/acknowledge) and resource (voice message by event_id), and makes the action scope clear. It is distinguishable from siblings like umouse_voice_inbox or umouse_wait_voice, though it never names them explicitly.

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?

Provides a real precondition (messages without completed transcription cannot be acknowledged) and notes idempotency, which helps decide when it is callable. However, it gives no explicit guidance on when to prefer this over sibling tools such as umouse_voice_inbox or umouse_voice_status.

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, the description carries the load well: it discloses audio format, that WAVs are written to disk and kept out of the conversation stream, and notably that action=stop is idempotent — if the session was already auto-closed by key release or timeout it returns the most recent completed file instead of an error. It omits what happens if start is called while a recording is already active, and there is no permission/auth context.

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?

Single dense paragraph with the key facts (format, no chat stream, recommended alternative) front-loaded before the per-action breakdown. Slightly compressed by bracketed parentheticals, but every clause carries information and nothing is redundant.

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?

No output schema exists, and the description covers the important returns — WAV path on stop, and the idempotent file= fallback. It does not describe what action=status yields, which is the one remaining gap for a tool an agent must call blind.

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 67%, but the description compensates for the undocumented action enum by giving meaning to each value (start = begin continuous audio, stop = finalize with idempotent fallback, status = inspect in-progress session). device_id and max_seconds are already well documented in the schema, so the description adds the piece the schema could not.

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+resource (device recording to a WAV file at 16kHz/16bit/mono) and immediately distinguishes itself from the recommended voice-key path handled via umouse_wait_events. An agent can tell what this tool is and is not 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?

Explicitly says the voice key + speechCaptured/umouse_wait_events flow is the default and recommended route, and this tool is only for manual scenarios such as long-running meeting capture. The when-not is as clear as the when.

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, the description carries the behavioral burden well: it describes per-device return data, capability sources, connection generation, online status, and hidden tools. It also discloses execution-layer rejection for unknown capabilities and the UMSDK_TEST_CAPS test mechanism, though it does not explicitly state side-effect or permission details.

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 front-loaded sentence with dense but relevant information. Parenthetical details about capability sources and test capabilities earn their place, though the paragraph could be more scannable if split into shorter statements.

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?

Because there is no output schema, the description usefully names the per-device return fields and the hidden-tool reasons. It is nearly complete for a capability-query tool, with only minor gaps around result ordering or pagination that are unlikely to affect correct invocation.

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?

There is only one parameter, device_id, and the schema description coverage is 100%. The schema already documents omission behavior, multi-device requirements, and temporary IDs, so the description adds no additional parameter semantics beyond 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?

States a specific verb and resource: querying device capabilities (voice / mouse_control / keyboard_control) and current executable state, including hidden tools and reasons. The purpose is clear, but it does not explicitly distinguish this tool from siblings such as umouse_status or umouse_list_devices.

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 when this is useful by explaining that unknown capabilities are rejected and that injection tools only work on devices declared supported. However, it never explicitly says when to call this versus alternatives like umouse_status or umouse_list_devices.

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, the description carries the full burden and does well: non-blocking semantics, strictly increasing seq, no replay, and the presence of a buffer field are all disclosed. It omits what happens on overflow beyond naming queueOverflow, and says nothing about auth or rate limits.

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?

Purpose, return shape, and cursor protocol are front-loaded, which is good. The long single-paragraph type enumeration is dense and run-on; it is justified only because the types parameter has no enum, and it could have been structured as a list for far easier scanning.

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?

There is no output schema, and the description compensates by giving the return object shape (events/nextSince/buffer), payload shapes for keyEvent and speechCaptured, and per-type semantics. Payloads for most other event types and the meaning of the buffer value remain unspecified.

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 goes beyond the schema by establishing the cursor continuation contract for since/nextSince and by enumerating the legal type values that the untyped types array filters on. limit is left to the schema, which is fine.

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 and resource (非阻塞拉取...设备事件) plus the cursor scope (自上次游标以来), which separates it from the blocking sibling umouse_wait_events. It never names that sibling explicitly, so the differentiation is implied by the 非阻塞 qualifier rather than stated.

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?

Gives a clear operating protocol: pass 0 on the first call and feed the returned nextSince back as since on every subsequent call. It does not say when to prefer this over umouse_wait_events or when to narrow with the types filter, so no explicit exclusions are offered.

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 full burden. It does disclose the returned fields and their meaning — connMode (USB/BLE), battery (%), status (normal/meeting), lastSeen — which is real behavioral value, but it never says whether the call is read-only, whether it blocks, what happens when zero devices are online, or whether it triggers a scan.

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?

A single sentence with the resource stated first and the return shape appended as a bracketed field list — zero filler and well front-loaded. The bracket notation is slightly terse/cryptic, but every element earns its place.

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?

With zero parameters and no output schema, the description correctly compensates by inlining the return structure and field meanings. What remains unstated is edge-case behavior (empty result, freshness of 'online', ordering), which is a minor gap for a no-arg list tool.

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 takes no parameters and the schema is empty, so there is nothing for the description to disambiguate; baseline 4 applies. The description's field list describes output rather than input semantics, so it neither helps nor hurts here.

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 (enumerate/枚举) and a specific resource (currently online Shengyun smart mice), and the bracketed field list makes the payload concrete. It does not name a sibling or contrast with umouse_status / umouse_get_capabilities, which also expose device-level information, so an agent must infer the difference.

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?

Usage is only implied: listing online devices is the natural first step before device-specific calls. There is no explicit when-to-use, no when-not-to-use, and no mention of the similarly scoped umouse_status or umouse_get_capabilities, leaving sibling selection to inference.

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 full burden and does so well: it discloses the state change (device enters meeting state), the ongoing resource use (audio continuously streaming), the global-exclusivity interception behavior with the meetingBusy owner, and async result reporting via meetingCreated/meetingDestroyed events. That is rich, non-obvious behavioral context beyond the schema.

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 compact clauses, each earning its place: the action, the exclusivity/interception rule, and the async event reporting. Front-loaded with the action and no 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?

There is no output schema, and the description compensates by explaining that results arrive asynchronously via meetingCreated/meetingDestroyed events and that failures surface as meetingBusy. An agent has everything it needs to call it and interpret the outcome.

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 single device_id parameter has 100% schema description coverage, including the single-vs-multiple-online rule and the transient-identity caveat. The description adds nothing about the parameter, so baseline 3 is appropriate when the schema already does the work.

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+resource: '开启会议模式' with the resulting device state (meeting state, continuous audio streaming). An agent can tell it apart from umouse_meeting_destroy/pause/resume by the sibling names alone, though the description doesn't explicitly name those alternatives.

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?

Gives a concrete usage condition: the meeting is globally exclusive, so the command is intercepted when another device is in a meeting (returning meetingBusy with the owner). This tells the agent when this call will fail and why, but it doesn't explicitly say to use pause/resume instead for temporary interruptions.

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, the description carries the full burden and does well: it discloses the ownership-release side effect, the global exclusivity lock, the interception behavior returning the busy owner, and that results arrive asynchronously via meetingCreated/meetingDestroyed events. It omits what happens when no meeting is currently active (idempotency or error) and any permission/auth requirements.

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, purpose front-loaded, then exclusivity constraint, then result-reporting mechanism. No filler and every sentence contributes information an agent needs.

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 mutation tool with no annotations and no output schema, the description covers the key behaviors: side effect, failure mode, and async result channel. It stops short of stating behavior when no meeting is active or how the agent should correlate the asynchronous events to this call.

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% and the single optional device_id parameter already documents omission rules, multi-device requirements, and ephemeral ID caveats. The description adds nothing about device_id, so the baseline 3 applies.

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+resource: ends meeting mode and releases ownership so other devices can start a meeting. This clearly distinguishes it from umouse_meeting_create/pause/resume, though it does not name those siblings explicitly.

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?

Explains the precondition under which the call succeeds and the condition under which it is rejected (another device holding the global meeting lock), which is meaningful routing guidance. It does not, however, tell the agent when to prefer destroy over pause or how to recover after a meetingBusy rejection.

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 supplied, the description carries the full burden and discloses several non-obvious behaviors: pause exempts the session from SDK disconnect adjudication, the meeting is globally exclusive, interception returns a meetingBusy owner, and results are asynchronous via events. It does not mention permissions, idempotency, or what pause does to existing media streams.

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 compact and front-loaded with the main action, then adds the important exclusivity and async-result details in a few dense clauses. There is no 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?

Given a complex stateful meeting operation with no annotations and no output schema, the description covers the critical operational constraints and async reporting behavior. It could be clearer about how pause results are confirmed, since meetingCreated/meetingDestroyed are lifecycle events rather than obviously pause-specific.

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 has 100% description coverage for device_id, including when it can be omitted and the instability of temporary identifiers. The description does not add further parameter guidance, so the baseline score of 3 is appropriate.

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 names a specific verb and resource: pausing a meeting (暂停会议). This is clearly distinguishable from the sibling meeting tools such as umouse_meeting_create, umouse_meeting_destroy, and umouse_meeting_resume.

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 explains a key context: a meeting is globally exclusive, and the command is intercepted if another device owns the meeting. However, it does not explicitly state when to prefer pause over destroy or resume, or give explicit 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?

With no annotations at all, the description carries the full burden and does substantial work: it discloses the global-exclusivity lock, the interception behavior and the meetingBusy payload (owner), and that the outcome arrives asynchronously via meetingCreated/meetingDestroyed rather than as a return value. It does not address permissions, whether the resume is reversible, or how long to wait for the events, leaving some behavioral gaps for a write-like state-changing operation.

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 short sentences, front-loaded with the action, then the exclusivity/error rule, then the async result channel. Dense but every clause carries information; the only cost is that the heavy compression in Chinese makes it slightly harder to parse for a non-native reader.

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 no annotations and no output schema, the description compensates well by explaining that results are delivered through meetingCreated/meetingDestroyed events, filling the hole an absent output schema would otherwise leave. The main remaining gap is what the caller should do after a meetingBusy interception.

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% and the single device_id parameter is documented in detail in the schema (SN, optional when one device is online, required when multiple, temporary identity caveat). The description adds nothing about the parameter, so the baseline 3 applies.

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 and resource ('恢复被暂停的会议' – resume a suspended meeting) and implicitly scopes it to meetings already paused, which separates it from meeting_create/meeting_pause/meeting_destroy. It does not name those siblings explicitly, so the differentiation is inferred from the shared meeting_* naming rather than stated.

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 a clear precondition (the meeting must already be paused) and an explicit failure condition (a meeting in progress on another device causes the call to be intercepted with meetingBusy and an owner). It stops short of saying what the agent should do next on interception (retry, query status, target another device), so the guidance is strong but not fully prescriptive.

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, the description carries the full burden and does well: it discloses that a controlled session restart occurs, that all online devices are disconnected, that event buffering survives, and that devices auto-reconnect. Missing pieces are the return shape and whether the restart is immediate or deferred, but the primary destructive side effect is stated plainly.

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 sentences, front-loaded with the capability, then the restart caveat, then the usage condition. Dense but each clause is meaningful; only the parenthetical device-recovery note could arguably be trimmed.

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 mutation tool with six optional parameters, no annotations, and no output schema, the description covers the side effect, the state preservation behavior, and the intended scope. An agent has enough to decide and call correctly; only return-value expectations and restart timing remain unstated.

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 every parameter (including the nested USB/BLE fields and the null-to-reset semantics) is already documented in the schema. The description's enumeration of config categories merely mirrors the schema's property set without adding format or constraint detail, so baseline 3 applies.

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 (reconfigure, requiring session restart) and enumerates the exact configuration surface: work mode, USB/BLE identifiers, device limit, and speech-key auto-record. This distinguishes it from runtime-operation siblings like umouse_set_dpi or umouse_audio_record, though it never names a sibling to contrast with explicitly.

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 a clear when-to-use condition ('only when connecting non-default devices') and an implied when-not ('generally keep environment variable configuration unchanged'), which steers the agent away from casual invocation. It stops short of naming an alternative tool for routine runtime changes, but the context 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 exist, so the description carries the full burden, and it discloses non-obvious side effects: other devices are muted at the SDK layer, the default policy is restored when device_id is omitted, and the call is refused by arbitration during an active voice session. It does not mention persistence, permissions, or what the response contains.

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?

Four short clauses with no filler, and the primary effect is front-loaded before the reset behavior and the rejection caveat. The parenthetical is slightly dense, but nothing is wasted.

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 one-parameter mutation tool with no annotations and no output schema, the description covers the effect, the reset semantics, and the failure condition. Missing details are relatively minor: permission requirements and whether the setting survives reconnection or session end.

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%, and the schema already states that device_id is a device SN and that empty or omitted restores the default policy. The description repeats and slightly contextualizes this meaning but adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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?

A specific verb (set) and resource (voice audio source device) with the effect spelled out: only that device is captured, other devices are muted at the SDK layer. This distinguishes it from umouse_audio_record and umouse_voice_start, which handle recording and session lifecycle rather than source selection.

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 clear conditions: use when multiple devices are online and the recognition session needs to be locked to one source; omit device_id to restore the default first-come-first-served policy; it will be rejected while a voice session is in progress. It does not name a sibling alternative such as umouse_set_channel_pref, so it falls 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?

With no annotations, the description carries the burden and discloses the key side effect: switching runs at runtime and momentarily disconnects the current channel before re-probing. It does not cover persistence, error behavior, or return effects, but the main disruption is surfaced.

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-loads the action, then adds essential runtime behavior and mode meanings in a compact single sentence. It is dense but contains little waste; structure could be slightly clearer due to nested parenthetical and semicolon list.

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 two-parameter mutation tool with no annotations or output schema, the description is largely complete: it defines modes, default, switching behavior, and a relevant BLE condition. Minor gaps remain around persistence and error handling.

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 pref enum values are explained with operational meaning beyond the bare enum labels, including AUTO default and BLE edge case. The device_id parameter is left to the schema, which already documents omitting it as applying to all connected devices, so coverage is adequate rather than exhaustive.

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 and resource: setting channel preference, with the three accepted modes. It does not explicitly differentiate itself from sibling tools, so it lands at clear-but-no-sibling-differentiation rather than top marks.

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?

Gives clear runtime context, default behavior, and a specific BLE use case when the receiver is present but the mouse is on Bluetooth with USB falsely online. It lacks explicit when-not-to-use guidance or comparisons to sibling tools.

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, the description carries the full burden and does so well: it discloses that the firmware gives no acknowledgement, that a return value of 1 only means the byte reached the channel, and that effect must be confirmed out-of-band via dpiChanged events. This is exactly the non-obvious behavioral trait an agent needs to avoid false success.

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?

Dense but front-loaded: the critical semantic (firmware byte, not DPI number) leads, followed by the mapping and the no-ack caveat. Every sentence earns its place, though the run-on structure of the final caveat is slightly harder to parse than ideal.

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?

No output schema and no annotations, but the description covers the important gaps for a mutation tool: what the argument means, the value encoding, and how to judge success given no firmware acknowledgement. Minor omissions are the device_id scoping (covered by schema) and any mention of persistence across reboot.

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 baseline would be 3, but the description goes far beyond: it explains the wire protocol (03 22 <level>), gives a concrete mapping table (800→21, 1200→32, etc.), and warns that other firmware families encode differently. The schema's own parameter description even defers to this table, making it load-bearing.

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 name plus description make clear this writes a firmware DPI-level byte for a device, and it explicitly disambiguates 'level' from an index or a DPI number. It never states the purpose as a standalone sentence ('set the mouse DPI'), relying partly on the name, but the encoding explanation is specific enough to identify the resource and operation.

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?

Usage is only implied: the reader infers you call it to change DPI, and there are no sibling tools that set DPI so no alternative routing is needed. The verification guidance (confirm via dpiChanged/cursor speed) is useful context but is about post-call validation, not when-to-use selection.

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 exist, so the description carries the full behavioral burden, and it does more than most: '查看' signals a read, and the seven enumerated categories tell the agent exactly what surface it observes, including diagnostic-specific content like event buffer watermark and legacy process takeover records. It does not explicitly state that the call is side-effect-free or mention cost, permissions, or latency, which keeps it below 5.

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?

A single dense sentence front-loads the resource and its returned contents, followed by a one-clause usage directive. No filler, no restatement of the tool name, and the actionable guidance sits at the end where it is easy to act on.

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?

There is no output schema, so the description must convey the return content, and it does: it lists all seven status categories an agent would receive. For a zero-parameter, read-only status tool, nothing needed to invoke or interpret the call is missing.

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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter claims in the description conflict with the empty 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 names a concrete verb and resource (查看 uMouse SDK 服务状态) and then enumerates the exact payload the tool returns: SDK version, uptime, config summary, online device count, event buffer watermark, recording status, and legacy-process takeover records. That lets an agent distinguish it from narrow siblings such as umouse_get_capabilities or umouse_list_devices, although the overlap with umouse_voice_status ('recording status' appears in both) is never explicitly resolved.

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 closing line '排查问题先调它' gives a clear triage directive: call this first when diagnosing problems. That is genuine usage guidance rather than an implied hint. It stops short of a 5 because it gives no exclusion or alternative-selection rule (e.g., when to prefer umouse_voice_status or umouse_get_events instead).

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 must carry the full behavioral burden, and it does add real value: it states that result delivery stops immediately, that cleanup is asynchronous ('not passing off cancel-wait as device-already-muted'), and that already-entered characters are not rolled back. This is exactly the kind of non-obvious semantic an agent would otherwise get wrong. Missing: permissions/auth needs, idempotency, and what the caller should do to observe cleanup completion.

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?

One sentence with zero filler, and the primary effect (immediately stop delivery, start cleanup) is front-loaded ahead of the caveats. The rhetorical quoted phrasing ('取消等待' versus '设备已关麦') is slightly dense but earns its place by preventing a specific misuse.

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?

With no output schema and no annotations, the description covers the essential semantics for a 1-parameter mutation, including the negative guarantees an agent needs. It stops short of saying what the call returns or whether the caller must poll umouse_voice_status/umouse_get_events to confirm that device cleanup has finished.

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?

There is only one parameter (session_id), and the schema already describes it at 100% coverage as '目标会话 ID', so the baseline is 3. The description says the session is 'specified' but adds no format, validity, or lifecycle meaning beyond the UUID format already 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 names a specific verb (取消/cancel) applied to a specific resource (指定语音会话/specified voice session), and clarifies the semantics: result delivery is blocked immediately while device cleanup begins. It implicitly separates itself from umouse_voice_wait and umouse_voice_finish by insisting that cancelling a wait is not the same as the device being muted, though it never names those siblings outright.

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 usage context is only implied – an agent can infer that this is the tool to call when it wants to abandon a session rather than complete it, but there is no explicit statement of when to prefer it over umouse_voice_finish, umouse_voice_wait, or umouse_ack_voice. There are no prerequisites or exclusions stated.

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, the description carries the full burden and does substantial work: it declares idempotency ('重复调用返回已有状态') and spells out the teardown ordering (meeting destroy → wait for device confirmation and audio-segment completion → terminal-state recognition → results retrievable). It stops short of stating blocking duration, failure modes, or what happens to an in-flight session's audio.

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 the action and its manual-entry scoping front-loaded, followed by the idempotency and ordering guarantees. No filler, though the parenthetical stack is slightly compact for a reader unfamiliar with the meeting/voice lifecycle.

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?

No output schema and no annotations, yet the description covers idempotency, the teardown sequence, and that results become retrivable afterward — enough for an agent to call it correctly and know what to do next. It is complete for a single-parameter session-termination tool.

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?

Only one parameter and schema description coverage is 100%, so the schema already fully documents session_id as the target UUID. The description adds nothing about that parameter's semantics, which is acceptable at the baseline for full coverage but not above it.

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+resource: '结束指定语音会话' (end the specified voice session), and immediately scopes it as the manual entry point outside the in-conversation complete button/VAD. It does not explicitly distinguish itself from the sibling umouse_voice_cancel, leaving that comparison implicit.

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 parenthetical '对话内完成按钮/VAD 之外的手动入口' implies when to reach for this tool (manual completion rather than automatic VAD/UI triggers), but there is no explicit statement of when to use this versus umouse_voice_cancel or umouse_voice_abort-style siblings, and no prerequisites are given.

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, the description carries the burden and does so well: default unacknowledged-only filtering, non-deleting read semantics, status-dependent behavior, and the important caveat that log notifications do not guarantee waking a new turn. It omits return structure beyond naming status/text/errorCode and says nothing about count or ordering.

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?

Dense and front-loaded: the core action and read semantics come first, followed by status semantics, then the ack workflow. Every clause carries information, though the semicolon-chained status list is slightly compressed rather than cleanly enumerated.

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?

No annotations and no output schema, so the description must convey return semantics — and it does by naming the status/text/errorCode fields and their meanings. The gap is the unexplained limit/ordering behavior, which matters for an inbox that can accumulate many messages.

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% and neither parameter is named, but '默认只读未确认消息' effectively explains the include_acknowledged default and its meaning. The limit parameter (1-100, default 100) is entirely undocumented in the description, leaving one of two params unexplained.

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 and resource: reads persistent transcription messages produced by the physical voice key. It also names the natural follow-up sibling (umouse_ack_voice), though it does not explicitly differentiate itself from umouse_voice_wait/umouse_wait_voice, which an agent might reasonably confuse it with.

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?

Gives concrete operational branching: ready means use the text (with recognition-error caveat), queued/transcribing means wait, empty means no conversation, failed means inspect errorCode, and ack only after processing or successful delivery to the explicit host. It lacks an explicit 'use this instead of umouse_voice_wait' statement, but the per-state guidance is strong.

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, the description carries the full burden and does well: it defines the readiness condition (meeting confirmation plus first PCM frame), the state returned, the single-session constraint, client_request_id idempotency, and the absence of typing side effects. It omits failure behavior — what happens when no device is online, mic permission denial, or a readiness timeout.

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 action and return state, then sequencing, then constraints. Every sentence carries information, though the trailing side-effect disclaimer and the idempotency note partially repeat what the schema already says.

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?

There is no output schema, and the description compensates by naming the returned state (listening/sessionId) and where the actual transcript arrives (via umouse_voice_wait). For a stateful hardware session-start tool the lifecycle is covered; only error and permission paths are absent.

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 schema already documents device_id's SN/transient-identity rules, end_mode's enum meaning, prompt, and client_request_id. The description only restates idempotency for client_request_id, adding no new parameter semantics; baseline 3 is correct.

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 and resource: starting one Agent voice Q&A session that captures audio via the device microphone in meeting mode and returns listening/sessionId. It also explicitly disclaims a plausible confusion — it only captures speech and returns final text as a tool result, never types into an input box.

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?

Gives the follow-up step by name (use umouse_voice_wait to await the final text) and lists the end conditions (VAD silence / finish button / cap), plus the one-session-at-a-time constraint. It does not state when to prefer umouse_audio_record over this tool, so the routing decision versus that sibling is left implicit.

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 full behavioral burden. It valuably discloses that dictation body text is not returned by default and that session details include segment durations, but it does not explicitly state that the tool is read-only or whether calling it has any side effects.

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 front-loaded with the core status scope, then adds the optional parameter behavior and default privacy behavior in a compact form. Every clause contributes useful information without repetition.

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 status tool with one optional parameter and no output schema, the description explains what is returned and the key default privacy behavior. It is nearly complete, though a note that the operation is read-only would improve completeness given the absence of annotations.

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 optional session_id parameter is already documented. The description adds meaningful semantics by explaining that session_id returns single-session details including segment durations, going beyond the schema's bare note that omission means global status.

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 names the specific resource (voice orchestration status) and enumerates what the status covers: ASR/typer readiness, active sessions, isolated unconfirmed mic-off records, and recent session summaries. This clearly identifies the tool's purpose, though it does not explicitly contrast it with sibling tools such as umouse_voice_wait or umouse_status.

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 explains that passing session_id returns single-session details, which implies a usage pattern, but it does not state when to use this tool versus alternatives like umouse_voice_wait or umouse_status. The guidance is implied rather than explicit.

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 full disclosure burden. It usefully discloses bounded wait behavior, pending versus terminal state distinction, terminal return fields (text, stopReason, mute confirmation, audio segment boundary facts), and that only agent-reply session text is returned. It does not explicitly state side-effect or ack semantics, but it is substantially transparent for a wait tool.

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 the purpose front-loaded and supporting details packed into parentheses and semicolons. It is dense but contains no filler, with only a minor readability cost from packing many facts together.

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?

With no output schema and no annotations, the description still explains terminal return values and wait-state behavior well enough to invoke the tool correctly. It could be more complete by describing the pending response shape and how this tool relates to ack/inbox/wait_voice siblings.

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 session_id and wait_ms are already documented in the schema. The description reinforces the ≤25s bound and adds a useful agent-reply-only restriction relevant to choosing session_id, but does not add meaningfully more about wait_ms beyond what the schema already says.

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-resource pair: wait for a voice session result, with bounded wait semantics. It is clear on its own, but it does not distinguish itself from the very similarly named sibling umouse_wait_voice, so it falls short of a 5.

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 says waits are bounded to ≤25s and that longer waits should use multiple rounds, which implies usage after a voice session exists. However, it never explicitly says when to use this tool versus umouse_wait_voice, umouse_voice_status, or umouse_voice_inbox, nor does it mention prerequisites or ack lifecycle.

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 to lean on, the description carries the full burden and does so: it discloses blocking/timeout behavior (empty return + timedOut:true), warns that the host may enforce a shorter timeout than the schema max of 30000 and recommends keeping a single call under 25000ms, and explains the nextSince cursor for multi-round continuation. It also distinguishes which types are server-generated (speechCaptured, sleepReset) and what origin/transport-down mean for meeting events — behavioral context an agent could not derive from the schema.

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 correctly with the core behavior, and little is pure filler — the type catalog and host-timeout warning are genuinely load-bearing. But it is delivered as one dense paragraph with ~20 enumerated types inline, making it hard to scan; the per-type notes (e.g. meeting event origins, sleepReset semantics) sit at the same visual weight as the critical timeout guidance.

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?

No annotations and no output schema, so the description must explain returns — it does so partially, revealing timedOut:true, nextSince, and payload contents for speechCaptured/keyEvent, but never states the overall response envelope (e.g. the array/count field names or how multiple events are ordered). Adequate for correct invocation, slightly short of complete.

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 real meaning beyond it: 'since' is tied to the returned nextSince cursor, 'types' is illustrated with concrete filter values and their payload contracts, and timeout_ms is given a practical ceiling (<25000) that is stricter than the schema's 30000 maximum. Only the pagination/continuation mechanics of the cursor remain slightly implicit.

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+resource combination ('long-poll wait for new device events') and pins down the semantics: immediate return on match, empty result with timedOut:true on timeout. It does not name the obvious siblings (umouse_get_events, umouse_wait_voice), so an agent must infer the blocking-vs-nonblocking distinction rather than being told.

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?

Explicitly frames itself as 'the standard tool for waiting on user physical operations' and gives two concrete recommended patterns (speech → types:["speechCaptured"], key → types:["keyEvent"]) with payload shapes for each. It stops short of exclusions — nothing says when to use umouse_get_events or umouse_wait_voice instead, or what to do when no relevant type exists.

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, the description carries the full burden, and it does real work: it discloses the 25-second cap, that pending results short-circuit the wait, that unacked results are re-delivered later, and the important caveat that the client may not be auto-woken after the current turn. What it omits is the timeout outcome (empty vs. error) and whether the call blocks or yields.

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?

Four compact clauses with no filler: the wait semantics and the 25-second cap come first, followed by the immediate-return rule, the ack requirement, and the wake caveat. Dense but front-loaded and each sentence carries a distinct operational fact.

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?

No output schema and no annotations exist, yet the description names the return states (ready/empty/failed), the confirmation lifecycle, and the timeout ceiling, which is most of what an agent needs to call it safely. The remaining gap is the exact behavior on timeout and the handoff ordering to umouse_ack_voice, which are left implicit.

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 0% for the single timeout_ms parameter, so the description must compensate. It conveys the effective cap ('最多 25 秒'), which matches the schema maximum and default, but says nothing about the minimum, units beyond seconds, or what a shortened timeout does behaviorally.

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 gives a specific verb and resource: wait inside the current active conversation for voice-key transcription to complete, returning ready/empty/failed messages. That is far more than a restatement of the name. It stops short of differentiating itself from the near-identical siblings umouse_voice_wait, umouse_voice_inbox, and umouse_wait_events, so an agent cannot tell these apart from the description alone.

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?

Usage is implied rather than stated: it should be called inside an active conversation, and existing unconfirmed results return immediately. The description also warns that after processing, the caller must ack or the result will be re-read, which hints at the inbox/ack workflow. However, it never says when to prefer this tool over umouse_voice_wait, umouse_voice_inbox, or umouse_wait_events, and it lists no exclusions.

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