Skip to main content
Glama

Mechanism Simulate Submit

mechanism_simulate_submit

Submit an asynchronous PyBullet simulation of rigid-link mechanism dynamics to obtain trajectories, joint torques, and through-motion collisions; poll the returned job ID for results.

Instructions

Simulate a rigid-link mechanism's DYNAMICS with PyBullet, asynchronously (the MBD family; requires the mbd extra — pip install 'ankusdrive[mbd]'). Use mechanism_kinematics first for the exact closed-form gates (DOF, Grashof, stroke).

links is a tree: [{name, box_mm:[lx,ly,lz], mass_g, parent (link index, −1 = fixed base), joint_type ('revolute'|'prismatic'|'fixed'), joint_axis:[x,y,z], joint_at_mm:[x,y,z] (in the parent frame), com_mm:[x,y,z]}]. drivers: [{link, rate_dps}] (revolute) or [{link, rate_mm_s}] (prismatic). Optional obstacles ([{box_mm, at_mm}]) for through-motion contact, base, gravity (m/s², default [0,0,−9.81]), dt_s, duration_s. gears ([{link_a, link_b, ratio, axis?, max_force?}]) couples two revolute links by ω_b = −ω_a/ratio (ratio = Nb/Na for an Na/Nb external mesh) — the moving image of the gear-train ratio gate.

Returns immediately. If PyBullet is absent: {ok:false, reason, install, mobility_dof, n_links}. Otherwise {job_id, status, cache_hit, mobility_dof}; poll job_result(job_id) for {trajectories, orientations (per-link world quaternion, sampled with trajectories), max_torques, collisions_through_motion (with the sim time of each contact), reachable_envelope {bbox_mm}, mobility_dof}.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "links": "<links>"
    },
    "name": "mechanism_simulate_submit"
  }
}

Input Schema

NameRequiredDescriptionDefault
baseNo
dt_sNo
gearsNo
linksYes
driversNo
gravityNo
obstaclesNo
workspaceNoRun this call in this named workspace
duration_sNo
loop_closuresNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.7
    • addedInput schema / properties / workspace
      Added value: +{
      +  "default": "",
      +  "description": "Run this call in this named workspace",
      +  "title": "Workspace",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=false); the description adds the async contract (returns immediately, job_id, cache_hit), the optional-dependency failure mode ({ok:false, reason, install, ...}), and the full downstream payload shape from job_result. That is exactly the extra context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, prerequisite, and dependency caveat before the dense structural spec, and the async/return contract comes last in logical order. It is long, but nearly every clause conveys non-redundant structural or behavioral information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully documents both return paths and the polling flow, which is the critical piece. The remaining gap is the undocumented `loop_closures` parameter, which an agent cannot infer from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 10% and most params are untyped arrays, so the description carries the burden — it spells out the links tree fields, drivers, gears ratio convention, obstacles, base, gravity, dt_s, and duration_s in useful detail. The notable omission is `loop_closures`, which appears in the schema but is never mentioned.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — simulating rigid-link mechanism dynamics with PyBullet — and explicitly positions itself against the sibling mechanism_kinematics (closed-form gates vs. dynamics). The distinction is legible without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the prerequisite/alternative explicitly: 'Use mechanism_kinematics first for the exact closed-form gates (DOF, Grashof, stroke).' It also tells the agent the follow-up step (poll job_result(job_id)). No explicit when-not-to-use condition, so it stops short of a 5.

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

Deploy Server

Other Tools