从任意 MCP 客户端驱动 Pollen Robotics Microduck —— Claude Code、Claude Desktop 或你自己的 agent。AI 获得一系列工具，可以带着鸭子四处走动、触发特技、推它，并通过渲染的相机画面看到它。
目前它驱动的是模拟鸭子（CPU 版 MuJoCo 运行来自 pollen-robotics/microduck 的官方预训练 ONNX 策略）。控制面仅包含意图 —— 速度、特技、注视 —— 与真实机器人的 robotd 契约保持一致，因此当你的鸭子到手时，硬件后端可以无缝接入同一套工具。
外出散步 | 翻滚进行中 | 等待指令 |
|
|
|
所有画面均由 duck_camera 工具渲染 —— 这正是 AI 在驱动时看到的画面。
MCP client (Claude, ...) duck CLI (humans / scripts) browser: AX debug page
│ stdio │ │ http :8400
▼ ▼ ▼
duck-mcp ────────────► Unix socket, JSON lines ◄──── built-in web UI
│
▼
duck-sim (50 Hz MuJoCo loop,
ONNX policy hot-swapping via
microduck_rl's PolicyInference)设计原理（工具 vs 资源、结构化输出、错误语义）记录在 docs/mcp-design-notes.md 中。
Related MCP server: robot-runtime
需要克隆两个官方仓库（用于场景/策略运行器和随附的 ONNX 策略），以及 uv：
git clone https://github.com/pollen-robotics/microduck
git clone https://github.com/pollen-robotics/microduck_rl
git clone https://github.com/aj-dev-smith/microduck-mcp
cd microduck-mcp && uv sync启动模拟服务器（默认假设三个仓库是同级目录）：
uv run duck-sim --rl-repo ../microduck_rl --policies ../microduck/policies默认无头运行。要在 MuJoCo 查看器中观看（macOS 需要 mjpython）：
uv run mjpython -m microduck_mcp.sim_server --viewer \
--rl-repo ../microduck_rl --policies ../microduck/policies从 shell 中调用它：
uv run duck state
uv run duck drive 0.2 # walk forward at 0.2 m/s
uv run duck trick roulade # forward roll
uv run duck cam follow # render a frame, prints the PNG path
uv run duck push # shove it, watch it recover向 Claude Code 注册 MCP 服务器：
claude mcp add duck -- uv --directory /path/to/microduck-mcp run duck-mcp所有返回状态的工具都会输出类型化的结构化结果（DuckState 模式，每个字段都标注了单位）；每个变更工具都会返回操作后的状态，因此 agent 很少需要后续轮询。
工具 | 功能 |
| 位置、朝向、机体坐标系速度、当前策略、是否直立？ |
| 速度意图；带 |
| 零指令 → 站立策略 |
|
|
| 指向头部（这是给策略的指令，不是舵机写入） |
| 渲染画面： |
| 推躯干；测试推挤恢复 |
| 回到原点，默认姿态（ |
duck-sim 还在 http://127.0.0.1:8400 提供 Agent Experience 调试页面（--web PORT，--web 0 可禁用）：实时显示到达控制套接字的每条指令 —— 按客户端（mcp、cli、web）标记 —— 旁边是自动刷新的相机视图和状态仪表盘。在 MuJoCo 查看器旁边打开它，即可实时观察agent 在做什么以及它能看到什么。纯标准库 HTTP + 一个 HTML 文件；所有渲染仍然通过与其他客户端相同的意图队列在模拟线程上完成。
模拟服务器在单线程上执行所有 MuJoCo 调用；套接字客户端只入队意图。多个客户端可以同时使用（MCP + CLI 同时运行）。
策略在共享的 61 维观测契约之后热切换，与机器人上完全一致：驱动时启用行走，零指令回到站立，回合制特技超时后回到站立。
相机渲染在离屏进行（无需窗口）；在 macOS 的 --viewer 模式下，离屏渲染可能不可用 —— 如果需要画面，请以无头模式运行。
随附的策略集不包含 StandUp 策略，因此一只最终侧倒在地的鸭子（例如在一次粗暴的翻滚落地后）会保持那个状态 —— duck_reset 是逃生舱。训练一个（microduck_rl 中的 Mjlab-StandUp-*）是解决办法。
在同一套工具后面实现真实机器人后端，使用守护进程的 WebSocket API（参见 microduck 文档 design/architecture.md §5.3）
身体姿态意图（站立时下蹲/倾斜）
可选的 StandUp 策略槽位，使跌倒无需 duck_reset 即可恢复
Apache-2.0。基于 Pollen Robotics 的 microduck 和 microduck_rl 构建，两者均为 Apache-2.0。
Render a camera frame of the sim. Views: 'follow' (behind the duck),
'front' (facing it), 'side', 'top'. distance in meters (0.4 close-up
to ~1.5 wide). Pair with duck_state for pose numbers.
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | follow | |
| distance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the no-side-effect profile is covered. The description adds useful context about views and distance but does not disclose additional behavioral details such as output format or whether the frame is static or animated. There is no contradiction with the annotations.
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 long and every clause adds distinct, actionable information: what the tool does, valid view values, distance semantics, and a usage hint. There is no filler or repetition of schema defaults.
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, zero-required tool with a readOnly annotation and no output schema, the description covers the key invocation details: valid views, distance range, and a state-pairing tip. The return format is not explicitly described, but 'render a camera frame' makes the output type inferable.
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 provides only parameter names and defaults, with 0% description coverage and no enums. The description fully compensates by defining each view ('follow' behind the duck, 'front' facing it, 'side', 'top') and giving distance units and a usable range of 0.4 to ~1.5 meters.
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 specific action and object: 'Render a camera frame of the sim.' The view list and distance range further clarify exactly what kind of camera output is produced. This clearly distinguishes the tool from siblings like duck_drive, duck_push, and duck_state, which are action/state tools rather than rendering tools.
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 an explicit pairing recommendation: 'Pair with duck_state for pose numbers.' It does not explicitly state when not to use it or name alternatives, but for a simple visualization tool the guidance is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the walking velocity intent. vx: forward m/s (max ±0.3; the policy tracks ~half the commanded speed, so command 0.25+ for a brisk walk), vy: leftward m/s (max ±0.2), wz: counterclockwise yaw rate rad/s (max ±1.5). Nonzero engages the walking policy; all-zero hands back to standing.
With duration_s (max 10): drive for that long, then stop and return the resulting state — one call instead of drive/poll/stop. Without it the intent persists until changed: the robot keeps walking between your tool calls, and the sim runs in real time, so returned state is already slightly stale when you read it.
| Name | Required | Description | Default |
|---|---|---|---|
| vx | Yes | ||
| vy | No | ||
| wz | No | ||
| duration_s | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| rpy_deg | Yes | Trunk orientation [roll, pitch, yaw], degrees |
| sitting | Yes | |
| upright | Yes | False once tilted past ~45 deg. There is no self-recovery policy: if the duck falls, use duck_reset. |
| vel_cmd | Yes | Current sticky velocity intent [vx, vy, wz] |
| behavior | Yes | Episodic trick currently running, else null |
| position_m | Yes | Trunk world position [x, y, z], meters |
| sim_time_s | Yes | Sim clock, seconds. The sim runs in real time; this snapshot is stale on arrival. |
| ground_pick | Yes | |
| vel_body_mps | Yes | |
| yaw_rate_rps | Yes | Yaw rate, rad/s, counterclockwise positive |
| active_policy | Yes | Which ONNX policy is driving: standing, walking, sit, ground_pick, kick_left/right, roulade |
| ball_position_m | No | Ball world position [x, y, z], meters (ball scene only) |
| trunk_height_mm | Yes | Trunk height above floor, mm (~116 standing) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavioral context beyond annotations: intents persist across calls, the sim runs in real time, returned state is already slightly stale, nonzero values engage walking, and all-zero returns to standing. It also discloses policy tracking behavior and commanded-speed scaling. No contradiction with annotations.
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 paragraphs with no filler. The opening sentence states the core purpose, parameter details are grouped logically, and the duration_s alternative is explained in a dedicated paragraph. Every sentence adds operational value.
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 4-parameter tool with no schema descriptions, the description covers all parameters, limits, behavioral persistence, and the optional duration mode. The output schema exists, so return values do not need to be described. Nothing essential is missing for an agent to invoke this 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 coverage is 0%, so the description carries the full burden for parameter meaning. It explains vx, vy, wz with units, sign conventions, and max magnitudes, plus duration_s semantics and the all-zero special case. Every parameter is given actionable meaning beyond the bare 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: 'Set the walking velocity intent.' The description clearly distinguishes this from siblings by explaining when velocity intents engage the walking policy and when they hand back to standing, and it contrasts the one-call duration mode with drive/poll/stop.
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 describes the two usage modes: with duration_s for a self-terminating drive, and without it for persistent intent. It also tells the agent when to use the shorter one-call form instead of drive/poll/stop, which routes to the relevant alternative behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Point the head (radians; caps ~±1.4 yaw, ±1.1 pitch, ±0.31 roll). This is a command to the balance policy, not a servo write — the body compensates. All zeros returns the head to neutral. The gaze intent is sticky — it holds between tool calls until changed.
| Name | Required | Description | Default |
|---|---|---|---|
| head_yaw | No | ||
| head_roll | No | ||
| head_pitch | No | ||
| neck_pitch | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| rpy_deg | Yes | Trunk orientation [roll, pitch, yaw], degrees |
| sitting | Yes | |
| upright | Yes | False once tilted past ~45 deg. There is no self-recovery policy: if the duck falls, use duck_reset. |
| vel_cmd | Yes | Current sticky velocity intent [vx, vy, wz] |
| behavior | Yes | Episodic trick currently running, else null |
| position_m | Yes | Trunk world position [x, y, z], meters |
| sim_time_s | Yes | Sim clock, seconds. The sim runs in real time; this snapshot is stale on arrival. |
| ground_pick | Yes | |
| vel_body_mps | Yes | |
| yaw_rate_rps | Yes | Yaw rate, rad/s, counterclockwise positive |
| active_policy | Yes | Which ONNX policy is driving: standing, walking, sit, ground_pick, kick_left/right, roulade |
| ball_position_m | No | Ball world position [x, y, z], meters (ball scene only) |
| trunk_height_mm | Yes | Trunk height above floor, mm (~116 standing) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It adds substantial behavior beyond annotations: the command is sticky and persists between calls, all zeros returns to neutral, and the body compensates rather than directly moving a servo. These details meaningfully shape how an agent should invoke and reason about the 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 compact—three sentences, each carrying distinct value: units/caps, policy behavior, and persistent-state behavior. It is front-loaded and free of 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?
The description covers the main purpose and key behavioral traits, and an output schema exists so return values need not be described. Still, neck_pitch is absent, direction conventions are unclear, and interaction with sibling tools is not addressed, so an agent is left with material 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?
With 0% schema description coverage, the description compensates by providing units and approximate caps for yaw, pitch, and roll. However, neck_pitch is never mentioned, and sign/direction conventions are not explained, leaving an important parameter underspecified.
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 points the head and gives units and range caps, which is specific and useful. It does not explicitly differentiate from sibling tools like duck_camera or duck_drive, though the resource ('head') is unambiguous.
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 important context: it is a command to the balance policy, not a servo write, and the body compensates. However, it does not name alternatives or give explicit when-to-use vs. when-not-to-use guidance relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shove the duck: sets trunk velocity to magnitude m/s (max 2.0) in a
world-frame direction (random if angle_deg omitted). Tests push recovery.
| Name | Required | Description | Default |
|---|---|---|---|
| angle_deg | No | ||
| magnitude | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| rpy_deg | Yes | Trunk orientation [roll, pitch, yaw], degrees |
| sitting | Yes | |
| upright | Yes | False once tilted past ~45 deg. There is no self-recovery policy: if the duck falls, use duck_reset. |
| vel_cmd | Yes | Current sticky velocity intent [vx, vy, wz] |
| behavior | Yes | Episodic trick currently running, else null |
| position_m | Yes | Trunk world position [x, y, z], meters |
| sim_time_s | Yes | Sim clock, seconds. The sim runs in real time; this snapshot is stale on arrival. |
| ground_pick | Yes | |
| vel_body_mps | Yes | |
| yaw_rate_rps | Yes | Yaw rate, rad/s, counterclockwise positive |
| active_policy | Yes | Which ONNX policy is driving: standing, walking, sit, ground_pick, kick_left/right, roulade |
| ball_position_m | No | Ball world position [x, y, z], meters (ball scene only) |
| trunk_height_mm | Yes | Trunk height above floor, mm (~116 standing) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-readonly, non-idempotent mutation. The description adds meaningful behavioral detail: velocity is in m/s with a max of 2.0, direction is world-frame, and angle_deg is randomly chosen when omitted. There is no contradiction with annotations.
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 that front-loads the action, then covers the mechanism, constraints, and purpose. Every clause adds useful information with no repetition or 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 the low parameter count and existing annotations, the description covers the core behavior, bounds, and purpose. The output schema exists, so return value explanation is unnecessary. It could be slightly more complete with angle convention details, but it is sufficient for calling 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 0%, so the description must carry parameter meaning. It does: magnitude is velocity in m/s capped at 2.0, and angle_deg defines a world-frame direction that becomes random when omitted. Minor ambiguity remains about the reference axis for angle_deg, so it is not a perfect 5.
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 operation: 'Shove the duck' sets trunk velocity, naming the resource (duck/trunk), the action (set velocity), and the parameterized behavior. It does not explicitly distinguish itself from siblings such as duck_drive or duck_trick, 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 use case is implied by 'Tests push recovery,' which tells the agent this is for simulating a push and checking recovery. However, there is no explicit when-to-use versus alternatives like duck_drive or duck_trick, and no exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reset the sim: duck back to the origin in its default standing pose, ball back to its spawn. Discards the current episode — the escape hatch after a fall (there is no stand-up policy yet).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| rpy_deg | Yes | Trunk orientation [roll, pitch, yaw], degrees |
| sitting | Yes | |
| upright | Yes | False once tilted past ~45 deg. There is no self-recovery policy: if the duck falls, use duck_reset. |
| vel_cmd | Yes | Current sticky velocity intent [vx, vy, wz] |
| behavior | Yes | Episodic trick currently running, else null |
| position_m | Yes | Trunk world position [x, y, z], meters |
| sim_time_s | Yes | Sim clock, seconds. The sim runs in real time; this snapshot is stale on arrival. |
| ground_pick | Yes | |
| vel_body_mps | Yes | |
| yaw_rate_rps | Yes | Yaw rate, rad/s, counterclockwise positive |
| active_policy | Yes | Which ONNX policy is driving: standing, walking, sit, ground_pick, kick_left/right, roulade |
| ball_position_m | No | Ball world position [x, y, z], meters (ball scene only) |
| trunk_height_mm | Yes | Trunk height above floor, mm (~116 standing) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructive and idempotent behavior. The description goes beyond them by revealing exactly what changes: the duck returns to origin in its standing pose, the ball returns to spawn, and the current episode is discarded. This is valuable behavioral context for a destructive 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?
Two tight sentences: the first states the reset outcome, the second explains the trigger and rationale. Every clause adds value, with the core action front-loaded and no redundant detail.
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 zero-parameter reset with annotations and an output schema, the description fully covers what happens, when to use it, and why it is the fallback. Nothing required for correct invocation 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 has 0 parameters and 0 required inputs, so the description carries no parameter-semantics burden. The schema already fully covers the empty parameter set, and the description naturally communicates a parameterless call.
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 ('Reset the sim') and specifies the exact resulting state: 'duck back to the origin in its default standing pose, ball back to its spawn'. This makes the tool's purpose concrete and clearly distinct from sibling action tools like duck_drive or duck_trick.
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 explicitly positions this as the 'escape hatch after a fall' and explains the need with 'there is no stand-up policy yet'. That gives clear trigger conditions. It does not explicitly name an alternative, but no sibling tool provides a reset action, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current robot state: pose, body-frame velocity, active policy, whether it is upright/sitting/mid-trick, and the ball position. Cheap — poll freely.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| rpy_deg | Yes | Trunk orientation [roll, pitch, yaw], degrees |
| sitting | Yes | |
| upright | Yes | False once tilted past ~45 deg. There is no self-recovery policy: if the duck falls, use duck_reset. |
| vel_cmd | Yes | Current sticky velocity intent [vx, vy, wz] |
| behavior | Yes | Episodic trick currently running, else null |
| position_m | Yes | Trunk world position [x, y, z], meters |
| sim_time_s | Yes | Sim clock, seconds. The sim runs in real time; this snapshot is stale on arrival. |
| ground_pick | Yes | |
| vel_body_mps | Yes | |
| yaw_rate_rps | Yes | Yaw rate, rad/s, counterclockwise positive |
| active_policy | Yes | Which ONNX policy is driving: standing, walking, sit, ground_pick, kick_left/right, roulade |
| ball_position_m | No | Ball world position [x, y, z], meters (ball scene only) |
| trunk_height_mm | Yes | Trunk height above floor, mm (~116 standing) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so no side effects are expected. The description goes beyond annotations by adding that the tool is 'cheap' and safe to poll freely, which signals performance characteristics. It also clarifies that the state includes posture modes like upright/sitting/mid-trick, giving useful behavioral 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?
The description is a single, compact sentence that front-loads the core purpose, lists concrete return fields, and ends with actionable usage guidance. No words are 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?
Given no parameters, a readOnly annotation, and an existing output schema, the description provides all necessary context. It tells the agent what the tool returns, that it is low-cost, and implicitly that it should be used for telemetry rather than actions.
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 there is nothing to document. The description correctly omits parameter details; the baseline of 4 applies because no parameter compensation is needed.
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 identifies the tool as a state-read operation for the robot, listing the specific fields it returns (pose, velocity, active policy, posture status, ball position). This distinguishes it from the sibling action tools like duck_drive and duck_trick, which perform movements rather than report 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 phrase 'Cheap — poll freely' provides explicit guidance that this tool is safe to call frequently, making its usage context clear. It does not explicitly name alternatives or exclusions, but the sibling tools are all action-oriented, so the intended use case of polling status is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Zero all velocity intents — the duck stops walking and stands.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| rpy_deg | Yes | Trunk orientation [roll, pitch, yaw], degrees |
| sitting | Yes | |
| upright | Yes | False once tilted past ~45 deg. There is no self-recovery policy: if the duck falls, use duck_reset. |
| vel_cmd | Yes | Current sticky velocity intent [vx, vy, wz] |
| behavior | Yes | Episodic trick currently running, else null |
| position_m | Yes | Trunk world position [x, y, z], meters |
| sim_time_s | Yes | Sim clock, seconds. The sim runs in real time; this snapshot is stale on arrival. |
| ground_pick | Yes | |
| vel_body_mps | Yes | |
| yaw_rate_rps | Yes | Yaw rate, rad/s, counterclockwise positive |
| active_policy | Yes | Which ONNX policy is driving: standing, walking, sit, ground_pick, kick_left/right, roulade |
| ball_position_m | No | Ball world position [x, y, z], meters (ball scene only) |
| trunk_height_mm | Yes | Trunk height above floor, mm (~116 standing) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal mutability (readOnlyHint=false), idempotency (idempotentHint=true), and non-destructiveness. The description adds a useful behavioral detail—all velocity intents are zeroed and the duck stands—but does not discuss side effects like interactions with duck_trick or state persistence.
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, front-loaded sentence immediately conveys the core effect and an accessible metaphor. There is no filler or redundant restatement of the title.
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 parameterless command with an output schema and simple behavior, the description captures everything an agent needs: it knows the call stops the duck and stands it. No prerequisites or additional context are required.
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 are no parameter semantics to clarify; the baseline of 4 for a parameterless tool applies. The description imposes no hidden arguments or prerequisites.
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 precise action—'Zero all velocity intents'—and adds an observable effect ('the duck stops walking and stands'). This clearly distinguishes it from movement-producing siblings like duck_drive and duck_push.
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 intended use is implicit from the action description: call this to halt the duck. However, it does not explicitly state when to use this tool over duck_reset, duck_drive, or other siblings, and no alternative is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a trick: 'sit', 'stand', 'ground_pick' (touch beak to floor), 'kick_left'/'kick_right' (stages the ball at that foot, then kicks), or 'roulade' (forward roll — NOTE: usually ends with the duck down, since no stand-up policy ships yet; follow with duck_reset). Episodic tricks hand control back to standing automatically after a few seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| rpy_deg | Yes | Trunk orientation [roll, pitch, yaw], degrees |
| sitting | Yes | |
| upright | Yes | False once tilted past ~45 deg. There is no self-recovery policy: if the duck falls, use duck_reset. |
| vel_cmd | Yes | Current sticky velocity intent [vx, vy, wz] |
| behavior | Yes | Episodic trick currently running, else null |
| position_m | Yes | Trunk world position [x, y, z], meters |
| sim_time_s | Yes | Sim clock, seconds. The sim runs in real time; this snapshot is stale on arrival. |
| ground_pick | Yes | |
| vel_body_mps | Yes | |
| yaw_rate_rps | Yes | Yaw rate, rad/s, counterclockwise positive |
| active_policy | Yes | Which ONNX policy is driving: standing, walking, sit, ground_pick, kick_left/right, roulade |
| ball_position_m | No | Ball world position [x, y, z], meters (ball scene only) |
| trunk_height_mm | Yes | Trunk height above floor, mm (~116 standing) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important physical side effects beyond the annotations, including that ground_pick touches the beak to the floor, kicks stage the ball at the indicated foot first, and roulade usually leaves the duck down because no stand-up policy ships yet. It also reveals that episodic tricks automatically hand control back to standing after a few seconds, which is exactly the kind of behavioral context an agent needs.
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 verb and immediately lists options in a scannable inline list. Every clause earns its place: the parentheticals clarify physical behavior, and the trailing note explains an important edge case rather than padding.
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 tool has one required parameter and an output schema, so the description need not document return values. It covers the accepted value set, per-value semantics, post-trick state, a required follow-up action, and automatic control handback, leaving no practical gap for an agent deciding whether and how to invoke the 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?
With 0% schema description coverage and only a bare string 'name' in the schema, the description carries full responsibility for parameter meaning. It compensates completely by listing every accepted value and explaining the effect of each, including the roulade/duck_reset caveat.
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 'Trigger a trick' and enumerates every valid trick value ('sit', 'stand', 'ground_pick', 'kick_left'/'kick_right', 'roulade'), making the operation specific and unambiguous. This clearly separates it from the sibling tools, which are state, drive, push, stop, look, camera, and reset operations.
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 intended trigger action is clear, and the description gives sequencing advice ('follow with duck_reset' after roulade) plus automatic return-to-standing behavior. However, it never explicitly states when to prefer this tool over sibling alternatives such as duck_drive or duck_push, so usage guidance is mostly implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0duck_cameraduck_driveduck_lookduck_pushduck_resetduck_stateduck_stopduck_trickScored across 8 tools
Each tool targets a distinct aspect of the duck robot: tricks, state reading, locomotion, perturbation, stopping, head gaze, camera rendering, and reset. Even though duck_stop overlaps slightly with duck_drive(all-zero), the descriptions clearly separate an explicit stop from a velocity command.
All tools share the duck_ prefix and use lowercase snake_case, which is easy to follow. However, the suffixes mix verbs (trick, push, reset) with nouns (state, camera), so the naming is mostly consistent but not perfectly uniform.
Eight tools is well within the ideal range for a robot-control MCP server. Each tool covers a necessary capability: actuation, sensing, perception, perturbation, and recovery, with no obvious bloat or redundancy.
The tool surface covers the core sim-control loop: inspect state, move, trick, push, look, view, stop, and reset. Minor gaps exist, such as no dedicated stand-up command and no ball manipulation beyond trick-triggered kicks, but those are explicitly handled via reset or documented limitations.
Hosted MCP server to manage a restaurant menu from AI agents - 39 tools over the DuckHub API.
Official Duck Framework MCP server for AI-assisted development and project scaffolding.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
