Pollen Robotics Microduck を、あらゆる MCP クライアント（Claude Code、Claude Desktop、独自エージェント）から操作します。AI は、アヒルを歩かせたり、トリックを実行させたり、押したり、レンダリングされたカメラフレームを通して見るためのツールを手に入れます。
現在はシミュレートされたアヒル（公式の事前学習済み ONNX ポリシーを実行する CPU MuJoCo、pollen-robotics/microduck 由来）を操作します。コントロールプレーンはインテントのみ（速度、トリック、視線）で、実機の robotd コントラクトを反映しているため、アヒルが届いたら同じツールの背後にハードウェアバックエンドを組み込めます。
お散歩中 | roulade の途中 | 命令待ち |
|
|
|
すべてのフレームは 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)設計の根拠（ツールとリソース、構造化出力、エラーセマンティクス）は docs/mcp-design-notes.md に文書化されています。
Related MCP server: robot-runtime
公式リポジトリ2つ（シーン/ポリシーランナー用と同梱の 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シミュレーションサーバーを起動します（デフォルトでは3つのリポジトリが兄弟ディレクトリにあると想定）:
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シェルから試してみます:
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 recoverMCP サーバーを Claude Code に登録します:
claude mcp add duck -- uv --directory /path/to/microduck-mcp run duck-mcp状態を返すすべてのツールは、型付きの構造化出力（DuckState スキーマ、単位はフィールドごとに記載）を出力します。状態を変更するすべてのツールは操作後の状態を返すため、エージェントが追加でポーリングする必要はほとんどありません。
ツール | 機能 |
| 位置、姿勢、ボディフレーム速度、アクティブなポリシー、直立かどうか |
| 速度インテント。 |
| コマンドをゼロにして立位ポリシーへ |
|
|
| 頭部を向けます（サーボ書き込みではなく、ポリシーへのコマンドです） |
| レンダリングされたフレーム: |
| 胴体を押します。押し込みからの回復をテストします |
| 原点、デフォルト姿勢に戻します（ |
duck-sim は http://127.0.0.1:8400 で Agent Experience デバッグページも提供します（--web PORT、無効化は --web 0）。コントロールソケットに届くすべてのコマンドのライブフィード（クライアント mcp、cli、web でタグ付け）が、自動更新されるカメラビューと状態ダッシュボードの隣に表示されます。MuJoCo ビューアの横に開いて、エージェントが何をしているか、何を見ているかをリアルタイムで確認できます。標準ライブラリの HTTP + HTML ファイル1つだけです。レンダリングはすべて、他のクライアントと同じインテントキューを介してシミュレーションスレッド上で行われます。
シミュレーションサーバーはすべての MuJoCo 呼び出しを1つのスレッドで実行します。ソケットクライアントはインテントをエンキューするだけです。複数クライアント（MCP + CLI の同時使用）も問題ありません。
ポリシーは、実機と同じ共有の61次元観測コントラクトの背後でホットスワップされます。駆動で歩行が開始され、ゼロコマンドで立位に戻り、エピソード型トリックはタイムアウトで立位に戻ります。
カメラレンダリングはオフスクリーンです（ウィンドウ不要）。macOS の --viewer モードではオフスクリーンレンダリングが利用できない場合があります。フレームが必要な場合はヘッドレスで実行してください。
同梱のポリシーセットには StandUp ポリシーが含まれていないため、横向きに倒れたアヒル（例: 乱暴な roulade 着地の後）はそのままになります。duck_reset が逃げ道です。StandUp ポリシーの学習（microduck_rl の Mjlab-StandUp-*）が修正策です。
同じツールの背後で、デーモンの WebSocket API（microduck ドキュメントの design/architecture.md §5.3 を参照）を話す実機ロボットバックエンド
体の姿勢インテント（立位でのしゃがみ/リーン）
オプションの StandUp ポリシースロット。duck_reset なしで転倒から回復可能に
Apache-2.0。microduck と microduck_rl（Pollen Robotics 製、ともに 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.
