Reads persistent voice-transcription messages from the uMouse voice key, returning unacknowledged messages by default without deleting them. Check status fields and acknowledge after processing to clear the inbox.
读取物理语音键产生的持久化转写消息。默认只读未确认消息，读取不删除。status=ready 的 text 是用户语音转写，可能有识别错误；queued/transcribing 请等待，empty 不创建对话，failed 查看 errorCode。处理或向明确宿主成功交付后用 umouse_ack_voice。日志通知不保证唤醒新回合。
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| include_acknowledged | No |
Changes observed during successful MCP inspections.
v0.1.0Does 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.