The Physics MCP Server transforms LLMs into a comprehensive physics engine with 79 specialized tools for calculations and simulations across classical mechanics, fluid dynamics, rotational motion, and rigid-body physics.
Core Physics Calculations: Projectile motion, forces (F=ma), kinetic/potential energy, momentum, work/power, and energy conservation verification—all computed instantly without external services.
Rigid-Body Simulations (Rapier Engine): Create 2D/3D physics worlds with multiple shapes (box, sphere, capsule, cylinder), material properties (friction, restitution, damping), joints (hinge, slider, spherical), and track multi-object interactions, collisions, stacking, and contact events with impulse magnitudes.
Advanced Projectile Physics: Realistic trajectories incorporating air resistance, Magnus force (spin effects), wind, altitude, and temperature, with orientation-dependent drag for tumbling objects.
Collision Physics: Predict 3D elastic and inelastic collisions with timing, impact location, energy loss quantification, and momentum transfer analysis.
Fluid Dynamics: Drag, buoyancy, terminal velocity, lift, Magnus force, Bernoulli's principle, pressure at depth, Reynolds number, Venturi effect, and underwater motion simulations.
Rotational Mechanics: Torque (τ = r × F), moment of inertia for various shapes, angular momentum (L = Iω), rotational kinetic energy (½Iω²), and angular acceleration.
Oscillations & Waves: Spring-mass systems (Hooke's law, periods, frequencies), simple harmonic motion, damped oscillations (underdamped, critically damped, overdamped), and pendulum calculations with large-angle corrections.
Circular Motion & Orbits: Centripetal force (mv²/r), orbital mechanics (Kepler's 3rd law), banking angles, escape velocity, and complete circular orbit analysis.
Statics & Equilibrium: Force balance (ΣF = 0), torque balance (Στ = 0), center of mass, static friction, normal force on inclines, beam reactions, and structural analysis.
Kinematics Analysis: Derive velocity, acceleration, and jerk from position data, trajectory fitting (linear, quadratic, cubic), motion graph generation, and average/instantaneous velocity calculations.
Conservation Laws: Verify energy, momentum, and angular momentum conservation, plus track energy dissipation over time.
Unit Conversions: Convert between 62+ unit types across 16 categories (velocity, distance, mass, force, energy, power, temperature, angle, pressure, area, volume, time, acceleration, torque, frequency, data size).
Visualization Integration: Generate detailed trajectory data (position, orientation, velocity) with automatic bounce and contact event detection for React Three Fiber, Remotion, and other 3D animation frameworks.
Use Cases: Education, game development, 3D visualization, engineering design, sports analytics, aerospace, marine engineering, film VFX, robotics, and scientific research including ML training data generation.
Provides specialized tools for generating physics-based trajectory and motion data tailored for React-based 3D frameworks such as React Three Fiber and Remotion.
Generates precise physical motion paths and trajectory arrays compatible with Three.js-based visualization engines for realistic 3D animations.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Physics MCP Server Calculate the trajectory of a soccer ball with 15mph wind and Magnus force."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Features: 🌀 Magnus Force • 💨 Wind Effects • 🏔️ Altitude • 🌡️ Temperature • 🔄 Tumbling Drag • 🎮 Rigid-Body Sims • 📊 515 Tests
A Model Context Protocol (MCP) server that brings comprehensive physics simulation and calculation capabilities to Large Language Models.
Transform your LLM into a physics engine! This MCP server provides 55 specialized tools spanning classical mechanics, fluid dynamics, rotational motion, and rigid-body simulations. Built for seamless integration with Claude, ChatGPT, and any MCP-compatible AI system.
Related MCP server: Physics MCP Server
Physics MCP Server enables LLMs to perform sophisticated physics calculations and simulations through a standardized protocol. Instead of hallucinating physics formulas or making calculation errors, LLMs can now:
Calculate precisely: Use validated physics formulas for exact results
Simulate realistically: Run rigid-body physics with the Rapier engine
Visualize motion: Generate trajectory data for React Three Fiber, Remotion, and other 3D frameworks
Teach interactively: Answer physics questions with real calculations, not memorized facts
Design intelligently: Analyze forces, collisions, and motion for engineering applications
The Model Context Protocol provides a standardized way to extend LLM capabilities beyond text generation. This server implements MCP to give language models direct access to:
⚡ Instant physics calculations (projectile motion, forces, energy)
🎮 Rigid-body simulations (collisions, bounces, stacking)
📊 Motion analysis (trajectory fitting, kinematics, velocity profiles)
🌊 Fluid dynamics (drag, buoyancy, lift, Bernoulli)
🔄 Rotational mechanics (torque, angular momentum, gyroscopes)
⚖️ Static analysis (equilibrium, beam reactions, friction)
🔄 Unit conversions (62 unit types: velocity, distance, mass, time, acceleration, torque, frequency, data size, and more)
Category | Tools | Description |
Basic Mechanics | 8 tools | Projectile motion, forces, energy, momentum, collisions |
Fluid Dynamics | 10 tools | Drag, buoyancy, terminal velocity, lift, Magnus force, Bernoulli |
Rotational Dynamics | 5 tools | Torque, moment of inertia, angular momentum, rotational KE |
Oscillations | 5 tools | Springs, pendulums, harmonic motion, damping |
Circular Motion | 5 tools | Centripetal force, orbits, banking angles, escape velocity |
Statics | 7 tools | Force balance, torque balance, friction, beam reactions |
Kinematics | 7 tools | Motion analysis, trajectory fitting, velocity calculations, projectile with drag |
Collisions | 2 tools | Elastic and inelastic 3D collisions with energy loss |
Conservation Laws | 4 tools | Energy, momentum, and angular momentum verification |
Unit Conversions | 2 tools | 62 unit types across 16 categories (velocity, distance, mass, time, acceleration, torque, frequency, data, etc.) |
See the dramatic difference when including real-world effects:
Sport | Scenario | Ideal (No Drag) | Realistic (With Enhancements) | Difference |
⚾ Baseball | 90 mph fastball | 87.5m | 52.3m (with drag) | -40% range |
⛳ Golf | Pro drive at sea level | 251m | 129m (with drag) | -49% range |
⛳ Golf | Same drive in Denver | 251m | 181m (drag + altitude) | -28% range |
⚽ Soccer | Free kick with wind | 25m straight | 26m + 5.6m curve (wind + spin) | Bends 5.6m! |
🎾 Tennis | Serve on hot day | 27m | 26.8m (less drag) | +2.3% vs cold |
💡 Key Insight: Real physics matters! Air resistance can reduce range by 20-70% depending on the sport.
Analytic Mode (Built-in, no setup)
Instant mathematical calculations
Perfect for education and quick answers
Exact solutions using physics formulas
Now includes: Advanced drag, spin (Magnus), wind, altitude effects
Simulation Mode (Requires Rapier service)
Full rigid-body dynamics
Complex multi-object interactions
Realistic material properties and constraints
# Try it instantly with uvx (no installation needed)
uvx chuk-mcp-physics
# Or with the public Rapier service for simulations
RAPIER_SERVICE_URL=https://rapier.chukai.io uvx chuk-mcp-physics
# Or use the public hosted MCP server (no local installation)
# Add to Claude Desktop config with URL: https://physics.chukai.io/mcpFor Claude Desktop: Add to your config file:
Option 1: Public Hosted MCP Server (Easiest - No Installation)
{
"mcpServers": {
"physics": {
"command": "node",
"args": ["-e", "require('https').get('physics.chukai.io/mcp')"]
}
}
}Option 2: Local uvx (Recommended)
{
"mcpServers": {
"physics": {
"command": "uvx",
"args": ["chuk-mcp-physics"],
"env": {
"RAPIER_SERVICE_URL": "https://rapier.chukai.io"
}
}
}
}LLM as Physics Tutor
User: "If I throw a ball at 20 m/s at 45°, how far will it go?"
LLM: [calls calculate_projectile_motion]
"The ball will travel 40.8 meters and reach a maximum height of 10.2 meters..."
[generates visualization with trajectory points]Real-World Problem Solving
Students ask physics questions in natural language
LLM calculates exact answers using the MCP tools
Can generate trajectory plots, force diagrams, energy graphs
Interactive "what-if" scenarios: "What if gravity was half?"
Ballistics Design
User: "I'm designing a cannon in my game. Initial velocity 50 m/s, 30° angle.
Will it clear a 15m wall at 80m distance?"
LLM: [calls calculate_projectile_motion]
"At 80m, the projectile is at 18.6m height - it WILL clear the wall.
It lands at 110.9m range."Collision Detection
User: "Two spaceships: Ship A at (0,0,0) moving at (10,0,0) m/s, Ship B at (100,5,0)
moving at (-8,0,0) m/s. Will they collide?"
LLM: [calls check_collision]
"Yes, collision in 5.3 seconds at position (53.0, 2.65, 0.0) with impact speed 18 m/s"Rapid Iteration
Test different launch angles, speeds, masses without coding
Verify collision logic before implementation
Generate realistic physics data for procedural content
Automated Animation Data Generation
User: "Create a realistic basketball shot animation - 7m throw into 3m high basket"
LLM: [calls calculate_projectile_motion with solved angle]
[returns trajectory_points array]
"Here's the trajectory data for R3F. The ball needs 52° launch angle..."
<mesh position={interpolate(trajectory)}>
<sphereGeometry args={[0.12]} />
</mesh>Rigid-Body Simulations
User: "Simulate 10 boxes falling and stacking in a pile"
LLM: [calls create_simulation]
[calls add_rigid_body for ground + 10 boxes with random positions]
[calls record_trajectory for each box]
"Here are 10 trajectory arrays for your R3F scene, ready to use..."Use Cases:
Product visualizations (dropping phones, bouncing balls)
Architectural collapse simulations (building demolition previews)
Sports analytics visualizations (ball trajectories, collision analysis)
Sci-fi effects (asteroid fields, debris clouds)
Vehicle Crash Prediction
User: "Two cars: Car A (1500kg) at 30 m/s, Car B (1200kg) at 25 m/s approaching.
Distance 100m. When do they collide and what's the impact energy?"
LLM: [calls check_collision for timing]
[calls calculate_kinetic_energy for both cars]
[calls calculate_momentum for momentum analysis]
"Collision in 1.82 seconds. Total kinetic energy: 1,050,000 J..."Safety Analysis
Calculate impact forces for crash test scenarios
Predict collision times for autonomous vehicle planning
Analyze momentum transfer in industrial equipment
Structural Testing (with Rapier simulations)
Simulate falling objects hitting structures
Test load-bearing capacity under dynamic loads
Model chain reactions (domino effects)
Realistic Ball Trajectories with Air Resistance
User: "How far does a 90 mph baseball fastball actually travel with air resistance?"
LLM: [calls calculate_projectile_with_drag with baseball parameters]
"With drag (realistic): 52.3m range
Without drag (vacuum): 87.5m range
Air resistance reduces range by 40%! Energy lost to drag: 89.2 J..."Golf Drive Analysis
User: "Pro golfer hits 70 m/s (155 mph) at 12° angle. How far with real air resistance?"
LLM: [calls calculate_projectile_with_drag with golf ball parameters]
"With drag: 129.4m (142 yards)
Without drag: 251.0m (274 yards)
Dimples reduce drag coefficient from 0.47 to 0.25 - saves ~50% range loss!"Basketball 3-Pointer
User: "What launch angle for a 7.5 m/s shot from 6.75m away (3-point line)?"
LLM: [calls calculate_projectile_with_drag iterating angles]
"With air resistance, optimal angle is 48° (high arc).
Range: 6.73m (close!), max height: 3.2m, flight time: 1.1s..."Shot Analysis Applications
Baseball: Pitch trajectories, drag reduces 90mph fastball range by 40%
Golf: Drive distance with dimpled ball (Cd=0.25 vs smooth ball Cd=0.47)
Basketball: Arc optimization for free throws and 3-pointers
Soccer: Penalty kick trajectories, minimal drag at short distances
Track & field: Javelin, shot put with realistic air resistance
Tennis: Serve and groundstroke trajectory analysis
Orbital Mechanics (Simplified)
User: "Two asteroids on collision course. A: 500m radius at (0,0,0) moving 15 km/s.
B: 300m radius at (100km, 2km, 0) moving -12 km/s. Impact prediction?"
LLM: [calls check_collision with appropriate units]
"Collision in 3.47 seconds at closest approach distance 650m.
They will NOT collide - miss distance is 150m..."Applications:
Asteroid impact prediction
Satellite collision avoidance
Debris field analysis
Launch trajectory planning (simplified cases)
Underwater Torpedo Simulation
User: "A torpedo is launched underwater at 20 m/s. It weighs 100kg, has a
streamlined shape (Cd=0.04), and cross-section of 0.03 m².
How far does it travel in 30 seconds?"
LLM: [calls simulate_underwater_motion]
"The torpedo travels 147.5 meters before drag and buoyancy slow it down.
Final velocity: 0.2 m/s. Maximum depth: 729.9 m..."Terminal Velocity & Drag Analysis
User: "What's the terminal velocity of a skydiver (70kg, 0.7m² area)?"
LLM: [calls calculate_terminal_velocity]
"Terminal velocity is 40 m/s (90 mph) in belly-down position.
Takes 12.2 seconds to reach 95% of terminal velocity..."Buoyancy & Float/Sink Predictions
User: "Will a 1kg steel ball (10cm diameter) float in water?"
LLM: [calls calculate_buoyancy]
"No, it will sink. Buoyant force is 5.14 N, but weight is 9.81 N.
The ball is denser than water..."Applications:
Marine engineering: Submarine drag, torpedo trajectories, underwater vehicles
Aerospace: Parachute descent, atmospheric re-entry, drag optimization
Sports science: Swimming efficiency, diving trajectories
Product design: Floatation devices, drag reduction, hydrodynamics
Environmental: Particle settling rates, pollutant dispersion
Stunt Planning
User: "Car jumps off 3m ramp at 25 m/s, 20° angle. How far does it fly and where does it land?"
LLM: [calls calculate_projectile_motion]
"Airtime: 1.75 seconds, landing at 42.9m horizontal distance,
impact speed 26.3 m/s. Recommend crashmat at 40-45m mark..."Destruction Sequences
Building collapses with rigid-body sim
Explosion debris trajectories
Vehicle stunts and crashes
Realistic object interactions
Ballistics Training
User: "Artillery shell: muzzle velocity 800 m/s, 45° elevation. Range and time of flight?"
LLM: [calls calculate_projectile_motion]
"Range: 65.3 km, flight time: 115.5 seconds, max altitude: 16.3 km"Collision Avoidance
Projectile trajectory analysis
Impact point prediction
Intercept course calculations
Path Planning
User: "Robot arm needs to toss part into bin 2m away, 0.5m higher.
What velocity is needed?"
LLM: [reverse-calculates using projectile_motion multiple times]
"Minimum velocity: 4.7 m/s at 38° angle. Recommend 5.0 m/s for safety margin..."Collision Detection
Multi-robot coordination
Object catching/throwing
Assembly line optimization
Physics Simulations for ML Training Data
# Generate thousands of collision scenarios for ML model training
for i in range(10000):
result = await check_collision(random_params())
training_data.append({
'features': params,
'label': result.will_collide,
'impact_time': result.collision_time
})Use Cases:
Generate labeled physics data for ML models
Validate physics-informed neural networks
Test scientific hypotheses with rapid iteration
Monte Carlo simulations (vary parameters, aggregate results)
1. User: "I'm 2m tall shooting from free-throw line (4.6m). Basket is 3.05m high.
What's the minimum velocity needed?"
2. LLM calls calculate_projectile_motion with varying velocities
- Try v=5 m/s → doesn't reach
- Try v=7 m/s → reaches
- Binary search finds minimum: v=6.2 m/s at 52° angle
3. LLM: "Minimum velocity is 6.2 m/s at 52° launch angle.
For comfortable margin, use 7.0 m/s (typical free throw speed).
Here's the trajectory visualization..."1. User: "Analyze accident: Car A (1500kg) skid marks 30m, Car B (1200kg) skid marks 25m.
Coefficient of friction 0.7. What were impact speeds?"
2. LLM:
- Calculates deceleration from friction: a = μg = 0.7 × 9.81 = 6.87 m/s²
- Uses v² = 2ad to find velocities
- Calls calculate_kinetic_energy for both cars
- Calls calculate_momentum for momentum analysis
3. LLM: "Car A impact speed: ~20.3 m/s (45 mph), Car B: ~18.5 m/s (41 mph).
Total kinetic energy at impact: 513,000 J. Here's the force analysis..."1. User: "Create a Rube Goldberg machine: ball rolls down ramp, hits dominos,
dominos knock ball into basket"
2. LLM:
- Calls create_simulation(gravity_y=-9.81)
- Adds ground plane (static)
- Adds ramp (static, angled)
- Adds ball (dynamic, sphere, position at ramp top)
- Adds 10 dominos (dynamic boxes in a line)
- Adds basket (static)
- Calls step_simulation(steps=1000)
- Analyzes contacts to verify chain reaction
- Calls record_trajectory for each piece
3. LLM: "Simulation complete! Ball triggers all dominos successfully.
Here are the trajectories for R3F visualization.
Domino #3 falls at t=1.2s, domino #7 at t=2.1s..."1. User: "Satellite A: position (6700km, 0, 0), velocity (0, 7.5km/s, 0)
Satellite B: position (6650km, 50km, 0), velocity (0, 7.6km/s, 0.1km/s)
Collision risk?"
2. LLM:
- Calls check_collision with satellite data
- Analyzes closest approach
3. LLM: "No collision. Closest approach: 48.3 km at t=412 seconds.
Satellites are in similar orbits but safe separation.
Recommend: monitor as orbits may precess over time."function PhysicsAnimation() {
const [trajectory, setTrajectory] = useState([]);
useEffect(() => {
// LLM generated this trajectory data via MCP
fetch('/api/mcp/record_trajectory', {
body: JSON.stringify({
sim_id: "sim_xyz",
body_id: "ball",
steps: 300
})
}).then(res => setTrajectory(res.frames));
}, []);
return (
<Canvas>
<AnimatedBall trajectory={trajectory} />
<Ground />
</Canvas>
);
}
function AnimatedBall({ trajectory }) {
const ref = useRef();
useFrame((state) => {
const t = state.clock.getElapsedTime();
const frame = trajectory[Math.floor(t / 0.016) % trajectory.length];
if (frame && ref.current) {
ref.current.position.fromArray(frame.position);
ref.current.quaternion.fromArray(frame.orientation);
}
});
return (
<mesh ref={ref}>
<sphereGeometry args={[0.5]} />
<meshStandardMaterial color="orange" />
</mesh>
);
}All trajectory recordings follow a canonical schema for maximum interoperability with R3F, Remotion, Three.js, and other animation systems.
interface Trajectory {
dt: number; // Time step between frames (seconds)
frames: Frame[]; // Ordered list of frames
meta: {
body_id: string; // Fully qualified: "rapier://sim-123/body-1"
total_time: number; // Total duration (seconds)
num_frames: number; // Frame count
};
}
interface Frame {
t: number; // Absolute time (seconds)
position: [number, number, number]; // [x, y, z] in meters
rotation: [number, number, number, number]; // Quaternion [x, y, z, w]
velocity?: [number, number, number]; // Optional: linear velocity (m/s)
angular_velocity?: [number, number, number]; // Optional: angular velocity (rad/s)
}{
"dt": 0.016,
"frames": [
{
"t": 0.0,
"position": [0, 1, 0],
"rotation": [0, 0, 0, 1],
"velocity": [0, 0, 0]
},
{
"t": 0.016,
"position": [0.1, 1.01, 0],
"rotation": [0, 0.01, 0, 0.9999],
"velocity": [6.25, 0.61, 0]
}
],
"meta": {
"body_id": "rapier://sim-abc123/ball",
"total_time": 4.8,
"num_frames": 300
}
}import { useRef } from "react";
import { useFrame } from "@react-three/fiber";
function AnimatedObject({ trajectory }) {
const ref = useRef();
useFrame((state) => {
const elapsed = state.clock.getElapsedTime();
const frameIdx = Math.floor(elapsed / trajectory.dt);
const frame = trajectory.frames[frameIdx % trajectory.frames.length];
if (frame && ref.current) {
ref.current.position.fromArray(frame.position);
ref.current.quaternion.fromArray(frame.rotation);
}
});
return (
<mesh ref={ref}>
<sphereGeometry args={[0.5]} />
<meshStandardMaterial color="orange" />
</mesh>
);
}import { useCurrentFrame } from "remotion";
import { ThreeCanvas } from "@remotion/three";
export const PhysicsAnimation = ({ trajectory }) => {
const frame = useCurrentFrame();
const frameData = trajectory.frames[frame];
return (
<AbsoluteFill>
<ThreeCanvas>
<mesh position={frameData.position}>
<sphereGeometry />
</mesh>
</ThreeCanvas>
</AbsoluteFill>
);
};Quaternions for rotation: More compact and interpolation-friendly than Euler angles
Absolute time: Each frame has absolute time t, making scrubbing easier
Constant dt: Frames are evenly spaced, simplifying playback
Optional velocities: Include if needed for motion blur or physics visualization
Qualified body_id: Format is rapier://sim-{id}/{body_id} for traceability
Python 3.11+
For simulations: Rapier service (see RAPIER_SERVICE.md)
Public service available at: https://rapier.chukai.io
Or run locally with Docker (see below)
The fastest way to try chuk-mcp-physics without installation:
# Run directly with uvx (no installation needed)
uvx chuk-mcp-physics
# With environment variables
uvx --with chuk-mcp-physics chuk-mcp-physics# Install globally
pip install chuk-mcp-physics
# Or with pipx (isolated environment)
pipx install chuk-mcp-physics
# Run the server
chuk-mcp-physics
# Or via python module
python -m chuk_mcp_physics.server# Clone repository (from your source location)
cd chuk-mcp-physics
# Install in development mode
make dev-install
# Run the server
chuk-mcp-physicsAdd to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"physics": {
"command": "uvx",
"args": ["chuk-mcp-physics"],
"env": {
"PHYSICS_PROVIDER": "rapier",
"RAPIER_SERVICE_URL": "https://rapier.chukai.io"
}
}
}
}{
"mcpServers": {
"physics": {
"command": "python",
"args": ["-m", "chuk_mcp_physics.server"],
"env": {
"PHYSICS_PROVIDER": "rapier",
"RAPIER_SERVICE_URL": "https://rapier.chukai.io"
}
}
}
}{
"mcpServers": {
"physics": {
"command": "uvx",
"args": ["chuk-mcp-physics"],
"env": {
"PHYSICS_PROVIDER": "analytic"
}
}
}
}Tools are organized into two tiers to help you choose the right abstraction:
Best for: Quick calculations, education, simple scenarios
Direct formula-based calculations that return instant results:
Tool | What It Does | Example Use Case |
| Ballistic trajectory using kinematic equations | "How far does a cannonball go?" |
| Predict if two spheres will collide | "Will these asteroids hit?" |
| F = ma calculations | "What force accelerates this car?" |
| KE = ½mv² | "How much energy in this crash?" |
| p = mv | "What's the momentum transfer?" |
| PE = mgh | "What's the energy at height?" |
| Work (F·d) and power (W/t) | "How much work lifting this box?" |
| 1D elastic collision (conserves energy & momentum) | "Pool balls colliding?" |
| Air/water resistance (F = ½ρv²C_dA) | "What's the drag on this car?" |
| Will it float? (Archimedes) | "Does a steel ball float in water?" |
| Maximum fall speed | "How fast does a skydiver fall?" |
| Underwater trajectory with drag & buoyancy | "How far does a torpedo travel?" |
Characteristics:
⚡ Instant execution (< 1ms)
📦 No external dependencies
🎯 Exact mathematical solutions
✅ Always available (no service required)
Limitations:
Only spherical objects (for collisions)
No complex shapes
No multi-body interactions
No friction or material properties
Best for: Complex physics, multi-body dynamics, visualization data
Low-level building blocks for rigid-body simulations:
Tool | What It Does | When to Use |
| Initialize physics world | Start any simulation |
| Add objects (box, sphere, capsule, etc.) | Build scene |
| Advance time | Run physics |
| Capture motion for R3F/Remotion | Generate animation data |
| Cleanup resources | End simulation |
Characteristics:
🦀 Requires Rapier service
🔄 Stateful (track simulation ID)
🧩 Composable (combine for complex scenarios)
💪 Full rigid-body dynamics
Typical workflow:
# 1. Create world
sim = create_simulation(gravity_y=-9.81)
# 2. Add objects
add_rigid_body(sim.sim_id, "ground", type="static", shape="plane")
add_rigid_body(sim.sim_id, "ball", type="dynamic", shape="sphere",
radius=0.5, position=[0, 5, 0])
# 3. Run simulation
step_simulation(sim.sim_id, steps=300)
# 4. Record for visualization
trajectory = record_trajectory(sim.sim_id, "ball", steps=300)
# 5. Cleanup
destroy_simulation(sim.sim_id)Tool | Purpose | Example |
| Ballistic trajectories | "How far does a cannonball travel?" |
| Predict sphere collisions | "Will these asteroids hit?" |
| F = ma calculations | "What force accelerates this car?" |
| KE = ½mv² | "Energy in moving object?" |
| p = mv | "Momentum of moving object?" |
| PE = mgh | "Energy at height?" |
| Work (F·d) and power (W/t) | "Work done lifting object?" |
| 1D elastic collision | "Pool ball velocities after impact?" |
Tool | Purpose | Example |
| Air/water resistance | "Drag on car at speed?" |
| Will it float? (Archimedes) | "Does steel ball float?" |
| Maximum fall speed | "Skydiver terminal velocity?" |
| Underwater trajectory | "How far does torpedo travel?" |
| Aerodynamic lift | "Lift on aircraft wing?" |
| Force on spinning ball | "Why does curveball curve?" |
| Pressure in flowing fluid | "Pressure in pipe constriction?" |
| Hydrostatic pressure | "Pressure at 30m depth?" |
| Flow regime classification | "Is flow turbulent?" |
| Flow through constriction | "Velocity in throat?" |
Tool | Purpose | Example |
| τ = r × F (cross product) | "Torque from wrench?" |
| Rotational inertia | "MOI of spinning disk?" |
| L = Iω | "Angular momentum of wheel?" |
| Rotational KE = ½Iω² | "Energy in flywheel?" |
| α = τ/I | "How fast does it spin up?" |
Tool | Purpose | Example |
| Spring force F = -kx | "Force in compressed spring?" |
| Oscillation period | "How fast does mass oscillate?" |
| Position at time t | "Where is mass at t=2s?" |
| Motion with damping | "How quickly does it settle?" |
| Pendulum swing time | "Period of 1m pendulum?" |
Tool | Purpose | Example |
| F_c = mv²/r | "Force for circular motion?" |
| Kepler's 3rd law | "Satellite orbital period?" |
| Optimal curve angle | "Banking for highway curve?" |
| Escape from gravity | "Earth escape velocity?" |
| Complete orbital analysis | "Analyze ISS orbit?" |
Tool | Purpose | Example |
| Verify ΣF = 0 | "Are forces balanced?" |
| Verify Στ = 0 | "Will seesaw balance?" |
| Balance point | "Where is center of mass?" |
| Max friction force | "Will object slip?" |
| Force on incline | "Normal force on ramp?" |
| Force + torque balance | "Is structure stable?" |
| Support forces | "Reaction forces on beam?" |
Tool | Purpose | Example |
| Derive from position data | "Acceleration from motion capture?" |
| Rate of acceleration change | "How jerky is motion?" |
| Find trajectory equation | "Fit parabola to data?" |
| Position/velocity/accel graphs | "Generate motion graphs?" |
| Speed along path | "Average speed on route?" |
| Velocity at exact time | "Speed at t=2.5s?" |
| Realistic projectile with air resistance | "How far does baseball actually go?" |
Tool | Purpose | Example |
| 3D perfect collision | "Pool balls in 3D?" |
| 3D collision with energy loss | "Car crash analysis?" |
Tool | Purpose | Example |
| Verify energy conserved | "Is collision realistic?" |
| Verify momentum conserved | "Is momentum preserved?" |
| Verify L conserved | "Is rotation valid?" |
| Energy loss over time | "Where did energy go?" |
Tool | Purpose | Supported Units |
| Convert between units | Velocity: m/s, km/h, mph, ft/s, knotsDistance: m, km, mi, ft, yd, inMass: kg, g, lb, ozForce: N, kN, lbfEnergy: J, kJ, cal, BTU, kWhPower: W, kW, hpTemperature: K, C, FAngle: rad, degPressure: Pa, kPa, bar, psi, atmArea: m², km², ft², acreVolume: m³, L, gal, ft³Time: s, min, hr, dayAcceleration: m/s², g, ft/s²Torque: N·m, lb·ft, lb·inFrequency: Hz, kHz, MHz, GHzData Size: B, KB, MB, GB |
| Get all supported units | Returns complete list of conversions |
Examples:
# Natural language queries work perfectly
"Convert 60 mph to m/s" # → 26.82 m/s
"How fast is 100 km/h in mph?" # → 62.14 mph
"What's 10 kg in pounds?" # → 22.05 lb
"Convert 100 feet to meters" # → 30.48 m
"What's 98.6°F in Celsius?" # → 37°C
"Convert 3 g-force to m/s²" # → 29.42 m/s²
"What's 300 N·m in lb·ft?" # → 221.27 lb·ft
"Convert 1 hour to seconds" # → 3600 sFeatures:
⚡ Instant conversions (no external service needed)
🔄 Automatic indirect conversions (e.g., mph → km/h via m/s)
📐 70+ unit types across 16 categories
🎯 Perfect for natural language physics queries
🚀 Includes engineering units (torque, acceleration, frequency)
For use with calculate_projectile_with_drag tool:
Object | Drag Coefficient (Cd) | Notes |
Sports Balls | ||
Baseball | 0.4 | Stitched surface |
Golf ball (dimpled) | 0.25 | Dimples reduce drag by ~50% |
Golf ball (smooth) | 0.47 | Without dimples (don't use!) |
Basketball | 0.55 | Large, textured surface |
Soccer ball | 0.25 | Modern, smooth panels |
Tennis ball | 0.55 | Fuzzy surface |
Football (American) | 0.05-0.15 | Highly streamlined, orientation-dependent |
Generic Shapes | ||
Sphere (smooth) | 0.47 | Default reference |
Flat plate (perpendicular) | 1.28 | Maximum drag |
Streamlined body | 0.04 | Teardrop/airfoil |
Cylinder (perpendicular) | 1.15 | Like a pole |
Vehicles | ||
Car (modern) | 0.25-0.35 | Aerodynamic design |
Truck | 0.6-0.9 | Boxy shape |
Bicycle + rider | 0.9 | Upright position |
Human Body | ||
Skydiver (belly-down) | 1.0-1.3 | Maximum drag |
Skydiver (head-down) | 0.7 | Streamlined |
Projectiles | ||
Bullet (supersonic) | 0.295 | Pointed nose |
Artillery shell | 0.15-0.25 | Streamlined |
Basic Usage Example:
# Baseball pitch with realistic drag
result = await calculate_projectile_with_drag(
initial_velocity=40.23, # 90 mph
angle_degrees=10,
mass=0.145,
cross_sectional_area=0.0043, # π × (0.037m)²
drag_coefficient=0.4 # Baseball Cd
)The calculate_projectile_with_drag tool supports optional enhancements for ultra-realistic simulations:
Spin creates a pressure differential that deflects the ball's path. Essential for:
Baseball: Curveballs (topspin drops), fastballs (backspin lifts)
Golf: Backspin increases carry, sidespin causes slices/hooks
Soccer: Bending free kicks around defensive walls
Tennis: Topspin brings ball down faster
# Baseball curveball with topspin
result = await calculate_projectile_with_drag(
initial_velocity=35,
angle_degrees=0,
mass=0.145,
cross_sectional_area=0.0043,
drag_coefficient=0.4,
spin_rate=261.8, # 2500 rpm = 261.8 rad/s
spin_axis=[0, 0, -1] # Topspin (negative z-axis)
)
# Returns lateral_deflection and magnus_force_maxSpin Parameters:
spin_rate: Rotation speed in rad/s (convert from RPM: rpm × 2π/60)
spin_axis: Unit vector [x, y, z] indicating spin direction
[0, 0, 1] = Backspin (lifts)
[0, 0, -1] = Topspin (drops)
[0, 1, 0] = Sidespin (hooks/slices)
Constant wind vector affects trajectory throughout flight:
# Soccer free kick with 5 m/s crosswind
result = await calculate_projectile_with_drag(
initial_velocity=28,
angle_degrees=12,
mass=0.43,
cross_sectional_area=0.0388,
drag_coefficient=0.25,
wind_velocity=[5.0, 0.0] # [horizontal, vertical] in m/s
)
# Returns wind_drift showing total deflectionWind Types:
Tailwind: [+X, 0] - increases range
Headwind: [-X, 0] - decreases range
Crosswind: [X, 0] - lateral deflection
Updraft: [0, +Y] - increases height and flight time
Downdraft: [0, -Y] - decreases height
Air density varies with elevation and temperature, dramatically affecting drag:
# Golf drive in Denver (1600m elevation, 20°C)
result = await calculate_projectile_with_drag(
initial_velocity=70,
angle_degrees=12,
mass=0.0459,
cross_sectional_area=0.00143,
drag_coefficient=0.25,
altitude=1600, # meters above sea level
temperature=20 # Celsius
)
# Returns effective_air_density showing actual density usedReal-World Impact:
Denver (1600m): ~10% longer drives than sea level
Hot day (+20°C): ~2-3% less drag than cold day
Everest Base Camp (5300m): ~50% less air density!
Air Density Formula:
ρ(h,T) = ρ₀ × exp(-Mgh/RT₀) × (T₀/T)Where:
ρ₀ = sea level density (1.225 kg/m³)
h = altitude (meters)
T = temperature (Kelvin)
M = molar mass of air (0.029 kg/mol)
g = gravity (9.81 m/s²)
R = gas constant (8.314 J/(mol·K))
# Golf ball with ALL effects (spin + wind + altitude)
result = await calculate_projectile_with_drag(
initial_velocity=70,
angle_degrees=12,
mass=0.0459,
cross_sectional_area=0.00143,
drag_coefficient=0.25,
spin_rate=200, # Backspin
spin_axis=[0, 0, 1],
wind_velocity=[3, 0], # Tailwind
altitude=1000, # Moderate elevation
temperature=25 # Warm day
)
# All effects combine for maximum realism!See Examples:
examples/sports_projectiles_with_drag.py - Basic drag effects
examples/advanced_projectile_effects.py - Magnus force, wind, altitude
For tumbling objects like footballs, frisbees, and javelins, drag varies dramatically based on orientation. A football in a perfect spiral has 3-6× less drag than when tumbling end-over-end!
Available via Rapier rigid-body simulations using the add_rigid_body tool with orientation-dependent drag parameters.
Objects moving through air experience drag that depends on their orientation:
Football spiral: Streamlined along flight path → low drag (~0.1 Cd)
Football tumbling: Broadside to airflow → high drag (~0.6 Cd)
Frisbee flat: Minimal cross-section → low drag (~0.08 Cd)
Frisbee tilted: Larger cross-section → higher drag
New add_rigid_body Parameters:
drag_coefficient: float # Base Cd value
drag_area: float # Reference cross-sectional area (m²)
drag_axis_ratios: [x, y, z] # Drag variation along body axes
fluid_density: float # Fluid density (air=1.225, water=1000)# Perfect spiral (low drag along Y-axis)
await add_rigid_body(
sim_id,
id="spiral",
shape="capsule",
size=[0.17, 0.28], # diameter, length
mass=0.42,
position=[0, 2, 0],
velocity=[vx, vy, 0],
angular_velocity=[0, 126, 0], # 20 rev/s spin
# Orientation-dependent drag
drag_coefficient=0.1,
drag_area=0.023, # End-on area
drag_axis_ratios=[1.0, 0.2, 1.0], # 5× less drag along Y
fluid_density=1.225
)
# Tumbling (higher drag, averaging all orientations)
await add_rigid_body(
sim_id,
id="tumble",
shape="capsule",
size=[0.17, 0.28],
mass=0.42,
position=[0, 2, 0],
velocity=[vx, vy, 0],
angular_velocity=[31.4, 0, 0], # Tumbling rotation
# Orientation-dependent drag
drag_coefficient=0.6, # Higher base Cd
drag_area=0.048, # Broadside area
drag_axis_ratios=[0.8, 1.0, 0.8], # Less streamlining
fluid_density=1.225
)Result: Spiral can travel 20-40% farther than tumble!
drag_axis_ratios PatternsThe drag_axis_ratios parameter specifies how drag varies along each body-local axis [X, Y, Z]:
Object | Ratios | Streamlined Axis | Use Case |
Football spiral |
| Y (length) | Perfect pass |
Javelin |
| Y (length) | Optimal flight |
Frisbee flat |
| Y (vertical) | Stable throw |
Sphere |
| None | Basketball, etc. |
Disc tumbling |
| Less variation | Wobbly throw |
Physical Meaning:
0.2 = 20% of base drag along that axis (very streamlined)
1.0 = 100% of base drag (normal)
1.5 = 150% of base drag (higher resistance)
⚽ Football Throw (spiral vs tumble):
# Spiral: 45-50 yards typical
# Tumble: 30-35 yards (30-40% loss)🥏 Frisbee (stable vs wobbling):
# Stable (600 rpm spin): 60-80 meters
# Wobbling (slow spin): 30-40 meters (50% loss)🏹 Javelin (optimal vs poor technique):
# Optimal angle: 70-90 meters (Olympic level)
# Poor release: 40-50 meters (45% loss)⚠️ Requires Rapier Service: Orientation-dependent drag calculations are performed by the Rapier physics service (Rust implementation). The Python MCP server defines the API and passes parameters to Rapier.
🎯 When to Use:
Sports simulations (football, frisbee, discus)
Projectile accuracy (javelin, arrows, darts)
Aerospace applications (rocket tumbling, debris)
🔬 Physics: The drag force is calculated in the Rapier service using the body's current orientation (quaternion) to transform body-local drag coefficients into world-space drag forces.
Hybrid Drag Implementation: Rapier uses a hybrid approach to handle extreme drag cases:
Normal drag (ratio < 2.0): Force-based orientation-dependent drag with full anisotropic behavior
Extreme drag (ratio ≥ 2.0): Damping-based drag for stability when drag-to-weight ratio is very high
Automatically activates for objects like ping pong balls (high drag, low mass)
Prevents numerical instabilities while maintaining realistic energy dissipation
Logged as INFO when triggered: "Body 'name' has extreme drag (ratio=X.XX), using damping"
Where drag_ratio = 0.5 * fluid_density * drag_coefficient * drag_area * v_typical^2 / (mass * g)
Measurement Notes:
When analyzing trajectories, use max(x_positions) instead of final_x to measure range. Rapier's solver may occasionally jitter backward slightly near ground impact, but this is a measurement artifact, not a physics error. The drag forces always oppose motion correctly.
See Example:
examples/tumbling_projectiles.py - Football, frisbee, and javelin orientation effects
All Phase 1 features are complete, tested (98% coverage), and deployed to production!
Automatically detect and analyze bounces in ball trajectories with energy loss calculations.
What it does:
Detects bounce events from trajectory data (velocity reversals near ground)
Calculates energy loss percentage for each bounce
Provides before/after velocities and heights
Perfect for answering "how many bounces?" and "when does it stop?"
Tool: record_trajectory_with_events
Example:
# Record a bouncing ball
traj = await record_trajectory_with_events(
sim_id=sim_id,
body_id="ball",
steps=300,
detect_bounces=True,
bounce_height_threshold=0.01 # 1cm = "on ground"
)
print(f"Detected {len(traj.bounces)} bounces")
for bounce in traj.bounces:
print(f"Bounce #{bounce.bounce_number}:")
print(f" Time: {bounce.time:.2f}s")
print(f" Height: {bounce.height_at_bounce:.3f}m")
print(f" Energy loss: {bounce.energy_loss_percent:.1f}%")
print(f" Speed before: {bounce.speed_before:.2f} m/s")
print(f" Speed after: {bounce.speed_after:.2f} m/s")Output:
Detected 5 bounces
Bounce #1: Time: 1.43s, Height: 0.00m, Energy loss: 36.0%, Speed: 14.0→9.0 m/s
Bounce #2: Time: 2.51s, Height: 0.00m, Energy loss: 36.0%, Speed: 8.9→5.7 m/s
Bounce #3: Time: 3.23s, Height: 0.00m, Energy loss: 36.0%, Speed: 5.7→3.6 m/s
...Use Cases:
Sports analytics (basketball arc, tennis serve bounces)
Product testing (phone drop tests, durability simulations)
Game development (realistic ball physics)
Education (demonstrate energy conservation)
See: examples/06_bounce_detection.py for full demo
Real-time collision tracking with detailed contact information from the physics engine.
What it does:
Tracks all contact events between bodies during simulation
Reports contact start, ongoing, and end events
Provides impulse magnitudes, normals, and relative velocities
Essential for collision analysis and force calculations
Included in: All trajectory recordings (record_trajectory, record_trajectory_with_events)
Contact Event Data:
ContactEvent(
time=1.43, # When contact occurred
body_a="ball", # First body
body_b="ground", # Second body
contact_point=[0.0, 0.05, 0.0], # World space position
normal=[0.0, 1.0, 0.0], # Contact normal (from A to B)
impulse_magnitude=14.2, # Collision impulse (N⋅s)
relative_velocity=[0.0, -14.0, 0.0], # Relative velocity
event_type="started" # "started", "ongoing", or "ended"
)Example:
traj = await record_trajectory(sim_id, "ball", steps=300)
# Analyze contacts
for event in traj.contact_events:
if event.event_type == "started":
print(f"Collision at t={event.time:.2f}s")
print(f" Bodies: {event.body_a} ↔ {event.body_b}")
print(f" Impulse: {event.impulse_magnitude:.1f} N⋅s")
print(f" Impact speed: {abs(event.relative_velocity[1]):.1f} m/s")Use Cases:
Collision analysis (car crashes, sports impacts)
Force calculations (derive forces from impulses)
Interaction tracking (which objects touched what)
VFX triggers (spark effects on collisions)
See: examples/07_contact_events.py for full demo
Connect rigid bodies with realistic joints for complex mechanical systems.
What it does:
Create constraints between bodies (hinges, sliders, ball-and-socket, fixed)
Build complex systems (pendulums, chains, ragdolls, machinery)
Realistic mechanical motion (doors, wheels, linkages)
Perfect for simulating articulated structures
Tool: add_joint
Joint Types:
Type | Description | Example Uses |
FIXED | Rigid connection (glue) | Attach hat to head, weld joints |
REVOLUTE | Hinge rotation around axis | Doors, pendulums, wheels |
SPHERICAL | Ball-and-socket rotation | Ragdoll shoulders, gimbal mounts |
PRISMATIC | Sliding along axis | Pistons, elevators, sliders |
Example - Simple Pendulum:
# Create anchor point
await add_rigid_body(
sim_id=sim_id,
body_id="anchor",
body_type="static",
shape="sphere",
size=[0.05],
position=[0.0, 3.0, 0.0]
)
# Create pendulum bob
await add_rigid_body(
sim_id=sim_id,
body_id="bob",
body_type="dynamic",
shape="sphere",
size=[0.2],
mass=1.0,
position=[1.5, 1.5, 0.0] # Start displaced
)
# Connect with revolute joint (hinge)
await add_joint(
sim_id=sim_id,
joint=JointDefinition(
id="hinge",
joint_type=JointType.REVOLUTE,
body_a="anchor",
body_b="bob",
anchor_a=[0.0, 0.0, 0.0], # Center of anchor
anchor_b=[0.0, 0.2, 0.0], # Top of bob
axis=[0.0, 0.0, 1.0] # Rotate around Z-axis
)
)
# Simulate and see realistic pendulum motion!
traj = await record_trajectory(sim_id, "bob", steps=300)Example - Multi-Link Chain:
# Create anchor
await add_rigid_body(sim_id, "anchor", body_type="static", ...)
# Create 3 chain links
for i in range(3):
await add_rigid_body(
sim_id,
f"link{i}",
body_type="dynamic",
shape="box",
size=[0.1, 0.4, 0.1],
position=[0.0, 2.5 - i*0.5, 0.0]
)
# Connect with spherical joints (ball-and-socket)
await add_joint(sim_id, JointDefinition(
id="joint0",
joint_type=JointType.SPHERICAL,
body_a="anchor",
body_b="link0",
anchor_a=[0.0, 0.0, 0.0],
anchor_b=[0.0, 0.2, 0.0]
))
await add_joint(sim_id, JointDefinition(
id="joint1",
joint_type=JointType.SPHERICAL,
body_a="link0",
body_b="link1",
anchor_a=[0.0, -0.2, 0.0],
anchor_b=[0.0, 0.2, 0.0]
))
# ... and so onUse Cases:
Mechanical systems (engines, gears, levers)
Character animation (ragdolls, inverse kinematics)
Vehicle suspension (wheels, shocks)
Architectural simulations (doors, drawbridges)
See: examples/08_pendulum.py for full demo
Realistic energy dissipation through linear and angular damping.
What it does:
Simulates air resistance (linear damping)
Simulates rotational friction (angular damping)
Makes simulations more realistic and stable
Perfect for settling physics and reducing "floaty" motion
Parameters: Added to add_rigid_body tool
Damping Parameters:
await add_rigid_body(
sim_id=sim_id,
body_id="damped_ball",
body_type="dynamic",
shape="sphere",
size=[0.5],
mass=1.0,
position=[0.0, 5.0, 0.0],
# Phase 1.4: Damping
linear_damping=0.5, # 0.0 (none) to 1.0 (high) - like air resistance
angular_damping=0.3 # 0.0 (none) to 1.0 (high) - like rotational friction
)Effect of Linear Damping:
0.0 = No air resistance (vacuum physics)
0.1-0.3 = Light damping (tennis ball in air)
0.5-0.7 = Moderate damping (underwater motion)
0.9+ = Heavy damping (very viscous fluid)
Effect of Angular Damping:
0.0 = Spins forever (vacuum)
0.1-0.3 = Realistic friction (rolling ball)
0.5-0.7 = High friction (rough surface)
0.9+ = Almost no rotation (sticky surface)
Comparison:
# Without damping - bounces forever
await add_rigid_body(..., linear_damping=0.0)
# Result: Ball bounces 20+ times, takes 30+ seconds to settle
# With damping - realistic settling
await add_rigid_body(..., linear_damping=0.5)
# Result: Ball bounces 5 times, settles in ~5 secondsUse Cases:
Realistic object motion (not "floaty" game physics)
Faster settling (less simulation time needed)
Underwater simulations (high damping)
Space simulations (zero damping)
See: examples/09_phase1_complete.py for all Phase 1 features combined
Analytical fluid calculations for drag, buoyancy, and underwater motion.
What it does:
Calculates drag forces (quadratic air/water resistance)
Computes buoyancy using Archimedes' principle
Determines terminal velocity for falling objects
Simulates underwater projectile motion with drag and buoyancy
Tools Available:
calculate_drag_force - Air/Water ResistanceCalculate the force opposing motion through a fluid.
# Ball falling through water
result = await calculate_drag_force(
velocity=[0, -5.0, 0], # 5 m/s downward
cross_sectional_area=0.00785, # π*r² for 10cm diameter
fluid_density=1000, # water (air=1.225)
drag_coefficient=0.47, # sphere (streamlined=0.04)
viscosity=1.002e-3 # optional: water viscosity for accurate Re
)
print(f"Drag force: {result['magnitude']:.1f} N (upward)")
print(f"Reynolds number: {result['reynolds_number']:.0f}")Common drag coefficients:
Sphere: 0.47
Streamlined (torpedo): 0.04
Flat plate: 1.28
Human (standing): 1.0-1.3
Car: 0.25-0.35
Optional viscosity parameter (for accurate Reynolds number):
Water at 20°C: 1.002e-3 Pa·s
Air at 20°C: 1.825e-5 Pa·s
Motor oil: 0.1 Pa·s
If omitted, estimated from density (water-like if >100 kg/m³, else air-like)
calculate_buoyancy - Will it Float?Determine buoyant force and whether objects float or sink.
# Check if 1kg steel ball floats
volume = (4/3) * π * (0.05)**3 # 10cm diameter sphere
result = await calculate_buoyancy(
volume=0.000524, # m³
fluid_density=1000 # water
)
weight = 1.0 * 9.81 # 9.81 N
buoyancy = result['buoyant_force'] # 5.14 N
# weight > buoyancy → SINKScalculate_terminal_velocity - Maximum Fall SpeedCalculate the speed where drag equals weight.
# Skydiver terminal velocity
result = await calculate_terminal_velocity(
mass=70, # kg
cross_sectional_area=0.7, # m² (belly-down)
fluid_density=1.225, # air
drag_coefficient=1.0 # human
)
print(f"Terminal velocity: {result['terminal_velocity']:.1f} m/s")
# Result: ~40 m/s (90 mph)
print(f"Time to 95%: {result['time_to_95_percent']:.1f}s")simulate_underwater_motion - Full Fluid SimulationSimulate motion through fluids with drag and buoyancy forces.
# Torpedo launched underwater
result = await simulate_underwater_motion(
initial_velocity=[20, 0, 0], # 20 m/s forward
mass=100, # kg
volume=0.05, # m³
cross_sectional_area=0.03, # m²
fluid_density=1000, # water
drag_coefficient=0.04, # streamlined
duration=30.0
)
print(f"Distance traveled: {result['total_distance']:.1f}m")
print(f"Final velocity: {result['final_velocity']}")
print(f"Max depth: {result['max_depth']:.1f}m")Use Cases:
Marine engineering: Torpedo trajectories, submarine drag
Aerospace: Skydiving, parachute descent, atmospheric re-entry
Sports: Swimming, diving, underwater ballistics
Product design: Drag optimization, floatation devices
Environmental: Particle settling, pollutant dispersion
Physics Models:
Quadratic drag: F_drag = 0.5 * ρ * v² * C_d * A
Buoyancy: F_b = ρ_fluid * V * g (Archimedes)
Terminal velocity: v_t = √(2mg / ρC_dA)
Numerical integration for complex underwater motion
See: examples/10_fluid_dynamics.py for comprehensive demonstrations
Status: ✅ All features production-ready
Feature | Status | Tool | Coverage |
Bounce Detection | ✅ Shipped |
| 100% |
Contact Events | ✅ Shipped | All trajectory tools | 100% |
Joints & Constraints | ✅ Shipped |
| 100% |
Damping Controls | ✅ Shipped |
| 100% |
Fluid Dynamics | ✅ Shipped |
| 100% |
Test Coverage: 98% (350 tests passing)
Deployment:
🌐 MCP Server: https://physics.chukai.io/mcp
🦀 Rapier Service: https://rapier.chukai.io
Examples: See examples/06_bounce_detection.py through examples/10_fluid_dynamics.py
All Phase 2 features are complete, tested (98% coverage), and deployed to production!
Complete rotational motion calculations including torque, moment of inertia, angular momentum, and rotational kinetic energy.
Tools Available:
Tool | Description | Example Use |
| Calculate torque from force and position (τ = r × F) | "What torque does this wrench apply?" |
| Moment of inertia for common shapes (disk, sphere, rod, etc.) | "What's the rotational inertia?" |
| Angular momentum (L = Iω) | "How much rotational momentum?" |
| Rotational KE (½Iω²) | "Energy in spinning flywheel?" |
| Angular acceleration (α = τ/I) | "How fast does it spin up?" |
Example - Calculate Torque:
result = await calculate_torque(
force_x=50.0,
force_y=0.0,
force_z=0.0,
position_x=0.0,
position_y=0.0,
position_z=0.8 # 80cm wrench
)
# torque magnitude = 40 N⋅mUse Cases:
Mechanical engineering (gear systems, engines)
Robotics (joint torques, motor sizing)
Sports science (bat swings, golf clubs)
Aerospace (satellite attitude control)
Harmonic motion and spring systems with damping effects.
Tools Available:
Tool | Description | Example Use |
| Spring force and potential energy (F = -kx) | "How much force in compressed spring?" |
| Period and frequency of spring-mass system | "How fast does it oscillate?" |
| Position, velocity, acceleration at time t | "Where is the mass at t=2s?" |
| Damped harmonic motion (underdamped, critically damped, overdamped) | "How quickly does it settle?" |
| Period of simple pendulum | "How long is one swing?" |
Example - Spring-Mass System:
result = await calculate_spring_mass_period(
mass=0.5, # 500g mass
spring_constant=20.0 # N/m
)
# period ≈ 0.99s, frequency ≈ 1.01 HzUse Cases:
Mechanical design (suspension systems, vibration isolation)
Seismology (earthquake oscillations)
Electronics (LC circuits, resonance)
Horology (pendulum clocks)
Circular motion, orbital mechanics, and centripetal forces.
Tools Available:
Tool | Description | Example Use |
| Force required for circular motion | "What force keeps car on curve?" |
| Period and velocity for circular orbit | "How long is satellite orbit?" |
| Optimal banking for curved road | "What angle for this turn?" |
| Minimum velocity to escape gravity | "Can rocket escape Earth?" |
| Complete orbital analysis (altitude, period, velocity) | "Analyze ISS orbit" |
Example - Satellite Orbit:
result = await analyze_circular_orbit(
altitude=400000.0, # 400 km above surface
planet_mass=5.972e24, # Earth mass
planet_radius=6.371e6 # Earth radius
)
# orbital_velocity ≈ 7670 m/s
# period ≈ 5530 seconds (92 minutes)Use Cases:
Space missions (orbital calculations, satellite deployment)
Astrophysics (planetary motion, binary stars)
Transportation (highway curve design)
Amusement parks (loop-the-loop, centrifuges)
3D collision calculations with elastic and inelastic collisions.
Tools Available:
Tool | Description | Example Use |
| 3D elastic collision (energy conserved) | "Pool ball collisions in 3D" |
| 3D inelastic collision with restitution | "Car crash with energy loss" |
Example - Car Crash:
result = await calculate_inelastic_collision_3d(
mass1=1500.0,
velocity1=[20.0, 0.0, 0.0],
mass2=1200.0,
velocity2=[-15.0, 0.0, 0.0],
coefficient_of_restitution=0.0 # Perfectly inelastic
)
# final_velocity1 = [1.11, 0, 0]
# final_velocity2 = [1.11, 0, 0] # Stick together
# energy_loss > 0 (deformation energy)Verify and track conservation of energy, momentum, and angular momentum.
Tools Available:
Tool | Description | Example Use |
| Verify total energy is conserved | "Is this collision realistic?" |
| Verify momentum is conserved | "Does this violate physics?" |
| Verify angular momentum conserved | "Is rotation energy conserved?" |
| Track energy loss over trajectory | "Where did the energy go?" |
Example - Validate Collision:
result = await check_energy_conservation(
initial_kinetic_energy=100.0,
final_kinetic_energy=50.0,
initial_potential_energy=0.0,
final_potential_energy=50.0
)
# is_conserved = True (100 = 50 + 50)
# energy_difference ≈ 0Static equilibrium analysis for structures and forces.
Tools Available:
Tool | Description | Example Use |
| Verify ΣF = 0 (force equilibrium) | "Are these forces balanced?" |
| Verify Στ = 0 (torque equilibrium) | "Will this seesaw balance?" |
| Find center of mass for system | "Where is the balance point?" |
| Maximum friction force, will object slip? | "Will box slide down ramp?" |
| Normal force on inclined plane | "What force on ramp?" |
| Complete equilibrium check (force + torque) | "Is structure stable?" |
| Reaction forces for simply supported beam | "What are support forces?" |
Example - Beam Analysis:
result = await calculate_beam_reactions(
beam_length=10.0,
loads=[1000, 500], # Two point loads
load_positions=[3.0, 7.0] # Positions along beam
)
# reaction_left = 800 N
# reaction_right = 700 N
# is_balanced = TrueUse Cases:
Structural engineering (bridges, buildings)
Mechanical design (levers, balances)
Architecture (load analysis)
Safety analysis (stability checks)
Analyze motion data to extract velocities, accelerations, and trajectories.
Tools Available:
Tool | Description | Example Use |
| Derive velocity and acceleration from position data | "Analyze motion capture data" |
| Calculate jerk (rate of change of acceleration) | "How jerky is this motion?" |
| Fit polynomial to trajectory (linear, quadratic, cubic) | "Find trajectory equation" |
| Generate position/velocity/acceleration graphs | "Visualize kinematics" |
| Average speed along path | "What's average speed?" |
| Velocity at specific time with interpolation | "Speed at exact moment?" |
Example - Motion Analysis:
result = await calculate_acceleration_from_position(
times=[0, 1, 2, 3, 4],
positions=[[0,0,0], [5,0,0], [10,0,0], [15,0,0], [20,0,0]]
)
# velocities = [[5,0,0], [5,0,0], ...] # Constant 5 m/s
# average_acceleration ≈ [0,0,0] # No accelerationUse Cases:
Motion capture analysis (sports, biomechanics)
Robotics (trajectory planning, motion smoothness)
Autonomous vehicles (trajectory optimization)
Scientific research (particle tracking)
Extended fluid calculations including lift, Magnus force, Bernoulli, and viscous flow.
Tools Available:
Tool | Description | Example Use |
| Aerodynamic lift (L = ½ρv²C_LA) | "What lift on wing?" |
| Force on spinning ball | "Why does curveball curve?" |
| Bernoulli's equation for flowing fluids | "Pressure in pipe constriction?" |
| Hydrostatic pressure | "Pressure at 30m depth?" |
| Flow regime (laminar/turbulent) | "Is flow turbulent?" |
| Flow through constriction | "Velocity in throat?" |
Example - Aircraft Wing:
result = await calculate_lift_force(
velocity=70, # m/s (~250 km/h)
wing_area=20.0, # m²
lift_coefficient=1.2,
fluid_density=1.225 # air
)
# lift_force ≈ 73,500 NUse Cases:
Aerospace engineering (aircraft design, aerodynamics)
Marine engineering (hull design, submarine motion)
Sports science (ball trajectories, swimming efficiency)
HVAC design (airflow optimization)
Status: ✅ All features production-ready
Feature Area | Tools | Coverage |
Rotational Dynamics | 5 tools | 100% |
Oscillations | 5 tools | 100% |
Circular Motion | 5 tools | 100% |
Advanced Collisions | 2 tools | 100% |
Conservation Laws | 4 tools | 100% |
Statics | 7 tools | 100% |
Kinematics Analysis | 6 tools | 100% |
Advanced Fluids | 6 tools | 100% |
Total Tools: 79 tools across all categories Test Coverage: 98% overall (350 tests passing)
Next Up: Phase 3 - Performance Optimization & Visualization
Batch simulation API for ML training data
Parameter sweep utilities
Enhanced visualization exports
Performance profiling and optimization
User: A golf ball is hit at 70 m/s at 15 degrees. How far does it go and what's the flight time?
LLM: [calls calculate_projectile_motion(70, 15)]
Range ≈ 249.7 m
Time of flight ≈ 3.694 s
Maximum height ≈ 16.73 m
Here are 50 trajectory points for visualization...User: What angle gives maximum range for a cannonball fired at 100 m/s?
LLM: [calls calculate_projectile_motion multiple times with different angles]
The optimal angle is 45°, which gives:
- Maximum range: 1019.4 m
- Flight time: 14.4 s
- Peak height: 254.8 mUser: Two asteroids: one at (0,0,0) moving at 1000 m/s in x direction,
another at (50000, 100, 0) moving at -800 m/s in x. Will they collide?
LLM: [calls check_collision with both objects]
Yes, they will collide!
- Collision time: ~27.8 seconds
- Impact location: (27,778, 100, 0)
- Impact speed: 1,800 m/s
- This would be a devastating impact given the closing speed.User: Two cars 500m apart, one at 60 mph, other at 45 mph heading toward each other.
When do they collide?
LLM: [calls check_collision]
Collision in 10.7 seconds at position 250m from car 1's starting point.
Combined approach speed is 105 mph (46.9 m/s).User: What force is needed to accelerate a 1500 kg car at 3 m/s²?
LLM: [calls calculate_force(1500, 3)]
Force required: 4,500 N (Newtons)
This is about 1,011 pounds of force.User: What's the kinetic energy of a 2000 kg car at 30 m/s (about 67 mph)?
LLM: [calls calculate_kinetic_energy(2000, 30)]
Kinetic energy: 900,000 J (Joules)
That's 900 kJ or 0.25 kWh of energy.
For perspective, this is why car crashes at highway speeds are so dangerous.User: Calculate momentum of a 70 kg runner at 10 m/s
LLM: [calls calculate_momentum(70, 10)]
Momentum: 700 kg⋅m/s
Direction: same as velocity vectorUser: I'm designing a water fountain. Water shoots up at 15 m/s.
How high does it go and when does it come back down?
LLM: [calls calculate_projectile_motion(15, 90)]
The water will:
- Rise to maximum height: 11.47 m
- Take 1.53 seconds to reach peak
- Return to ground level after 3.06 seconds total
- Have the same 15 m/s speed when it lands (just downward)User: A basketball player shoots from 2m high at 7 m/s toward a hoop
3.05m high and 4.6m away. What angles work?
LLM: [calls calculate_projectile_motion with various angles]
Two possible angles work:
1. Low arc: 38° (faster, flatter shot)
2. High arc: 52° (slower, higher shot)
Most players use 50-55° for better chance of going in.User: Create a simulation of a ball dropping from 10 meters and bouncing
LLM: [calls create_simulation(gravity_y=-9.81)]
[calls add_rigid_body for ground plane (static)]
[calls add_rigid_body for ball (dynamic, sphere, position=(0,10,0))]
[calls record_trajectory(steps=200)]
Simulation complete! The ball:
- Hits ground at t=1.43s with velocity 14.0 m/s
- Bounces to 7.5m (with restitution=0.8)
- Makes 5 bounces before settling
Here's the full trajectory data for R3F visualization...User: Simulate 5 boxes stacked, then another box hits them from the side
LLM: [calls create_simulation]
[calls add_rigid_body for ground]
[calls add_rigid_body 5 times for stacked boxes]
[calls add_rigid_body for projectile box with velocity]
[calls step_simulation(300)]
[calls record_trajectory for each box]
The collision causes a realistic toppling effect!
Boxes 1-2 fall left, boxes 3-5 scatter right.
Peak chaos at t=0.8s. All settled by t=3.2s.
Full trajectory data ready for 3D visualization...Copy and paste these into your LLM chat to see the physics tools in action:
A golf ball is hit at 70 m/s at 15 degrees. How far does it go and what's the flight time?
What angle gives maximum range for a cannonball fired at 100 m/s?
If I throw a javelin at 28 m/s from 2 meters high, what angle gives maximum distance?
A basketball player shoots from 2m high at 7 m/s toward a hoop 3.05m high and 4.6m away. What angles work?
Two cars 500m apart, one at 60 mph, other at 45 mph heading toward each other. When do they collide?
Two asteroids: one at (0,0,0) moving at 1000 m/s in x direction, another at (50000, 100, 0) moving at -800 m/s in x. Will they collide?
Spaceship A at (10000,0,0) moving at (-50,0,0) m/s, spaceship B at (-10000,100,0) moving at (45,0,0) m/s. Collision check?
What force is needed to accelerate a 1500 kg car at 3 m/s²?
What's the kinetic energy of a 2000 kg car traveling at 30 m/s?
Calculate the momentum of a 70 kg runner sprinting at 10 m/s
How much energy does a 0.145 kg baseball have when pitched at 45 m/s?
I'm designing a water fountain. Water shoots up at 15 m/s. How high does it go?
A cannon on a 50 meter cliff fires horizontally at 200 m/s. How far from the base does the projectile land?
Two cars crash: Car A (1500kg) at 30 m/s, Car B (1200kg) at 25 m/s. What's the total kinetic energy at impact?
Create a simulation of a ball dropping from 10 meters height and bouncing on the ground
Simulate 5 boxes stacked on top of each other, then have another box hit them from the side
Create a Newton's cradle with 5 spheres and record their motion
Simulate a sphere rolling down a 30-degree ramp
The examples/ directory contains working demonstration scripts:
These examples use the built-in analytic provider and work immediately:
00_quick_start.py - Quick demo of all 5 analytic tools
01_simple_projectile.py - Cannonball trajectories, basketball shots, angle comparisons
02_collision_detection.py - Car crashes, near misses, asteroid collisions
03_force_energy_momentum.py - F=ma, kinetic energy, momentum conservation
04_r3f_visualization.py - Generate React Three Fiber visualization data
# Run any example
python examples/00_quick_start.py
python examples/01_simple_projectile.py
# ... etcThese examples demonstrate rigid-body simulations and Phase 1 features. They need the Rapier service running:
05_rapier_simulation.py - Bouncing balls, collisions, stacking boxes
06_bounce_detection.py - Phase 1.1: Automatic bounce detection and energy analysis
07_contact_events.py - Phase 1.2: Real-time contact tracking and collision events
08_pendulum.py - Phase 1.3: Joints and constraints (pendulums, chains)
09_phase1_complete.py - Phase 1.4: All Phase 1 features (damping, bounces, contacts, joints)
10_fluid_dynamics.py - Phase 1.5: Fluid calculations (drag, buoyancy, terminal velocity)
11_rotational_dynamics.py - Phase 2.1: Torque, angular momentum, gyroscopes
12_oscillations.py - Phase 2.2: Springs, pendulums, harmonic motion, damping
13_circular_motion.py - Phase 2.3: Orbital mechanics, centripetal force
14_statics.py - Phase 2.6: Static equilibrium, force balance, beam analysis
15_kinematics_analysis.py - Phase 2.7: Motion analysis, trajectory fitting
16_roulette_simulation.py - 🎰 Casino Roulette - Complete showcase of multi-body physics, collisions, and energy dissipation
# Option 1: Use public Rapier service (easiest)
export RAPIER_SERVICE_URL=https://rapier.chukai.io
python examples/05_rapier_simulation.py
python examples/06_bounce_detection.py
# ... etc
# Option 2: Run local Rapier service with Docker
docker run -p 9000:9000 chuk-rapier-service
export RAPIER_SERVICE_URL=http://localhost:9000
python examples/05_rapier_simulation.pyNote:
Examples 00-04 work instantly (no external services)
Examples 05-09 showcase advanced rigid-body physics with Rapier
Use the public Rapier service at https://rapier.chukai.io or run your own
# Provider selection
PHYSICS_PROVIDER=analytic # or "rapier"
# Rapier service (only if using Rapier provider)
# The default is automatically determined:
# - On Fly.io: uses https://rapier.chukai.io (public service)
# - Locally: uses http://localhost:9000
#
# Override with:
RAPIER_SERVICE_URL=https://rapier.chukai.io # or http://localhost:9000
# Optional configuration
RAPIER_TIMEOUT=30.0
RAPIER_MAX_RETRIES=3
RAPIER_RETRY_DELAY=1.0Create physics.yaml in your working directory or ~/.config/chuk-mcp-physics/:
default_provider: rapier
providers:
# Override provider per tool type
simulations: rapier
projectile_motion: analytic
rapier:
# Public service (recommended)
service_url: https://rapier.chukai.io
# Or local development
# service_url: http://localhost:9000
timeout: 30.0
max_retries: 3
retry_delay: 1.0Understanding these limits helps prevent timeouts, instabilities, and confusion:
Parameter | Recommended | Maximum | Notes |
Units | meters, kg, seconds | - | SI units throughout |
dt | 0.008 - 0.033 | 0.001 - 0.1 | <0.008 = overkill, >0.033 = unstable |
steps | 100 - 5000 | 10,000 | Depends on dt and complexity |
bodies | 1 - 100 | 1,000 | Performance degrades >100 |
gravity | -20 to 0 m/s² | -100 to +100 | Earth = -9.81 |
velocity | 0 - 100 m/s | 1,000 m/s | Very high speeds may cause tunneling |
mass | 0.1 - 10,000 kg | 1e-6 - 1e6 | Extreme ratios cause instability |
The public Rapier service at https://rapier.chukai.io has these limits:
Max steps per call: 5,000
Max bodies per simulation: 100
Max concurrent simulations: 10 per IP
Request timeout: 30 seconds
Max simulation lifetime: 1 hour (auto-cleanup)
For larger simulations, run your own Rapier service (see RAPIER_SERVICE.md).
Symptoms:
Bodies gain extreme velocities
Objects disappear from view
NaN values in positions
Causes:
dt too large for the forces involved
Very high mass ratios (1g object hitting 1000kg object)
Extreme initial velocities
Solutions:
Reduce dt to 0.008 or lower
Use more similar masses (within 2-3 orders of magnitude)
Limit initial velocities to <100 m/s
Symptoms:
Request takes >10 seconds
Timeout errors
High CPU usage
Causes:
Too many bodies (>100)
Very small dt (<0.005)
Complex mesh colliders
Too many steps (>5000)
Solutions:
Reduce body count or simplify shapes
Increase dt (balance accuracy vs. speed)
Break large step counts into multiple calls
Use primitive shapes (sphere, box) instead of meshes
Symptoms:
Fast-moving objects pass through walls
Collisions not detected
Objects appear inside each other
Causes:
Very high velocities + large dt
Thin colliders (<0.1m)
Disabled continuous collision detection (CCD)
Solutions:
Reduce dt for high-speed scenarios
Thicken colliders (minimum 0.1m recommended)
Reduce velocities
Enable CCD if available (future feature)
Start simple: Test with 2-3 bodies before scaling up
Validate inputs: Check for NaN, Inf, extreme values before simulation
Monitor performance: Track step time, adjust dt/steps accordingly
Cleanup: Always destroy_simulation when done (prevent memory leaks)
Use analytic when possible: For simple scenarios, analytic is faster and exact
# Navigate to project directory
cd chuk-mcp-physics
# Install in development mode
make dev-install
# Run tests
make test
# Run tests with coverage
make test-cov
# Format code
make format
# Run all checks
make check
# Build package
make build# Build image
make docker-build
# Run container
make docker-run
# Access at http://localhost:8000Current Production Services:
MCP Physics Server: https://physics.chukai.io/mcp
Public hosted MCP server endpoint
No local installation required
Pre-configured with Rapier service
Ready to use in Claude Desktop
Rapier Physics Engine: https://rapier.chukai.io
Public API for physics simulations
No authentication required for basic usage
Rate limits may apply
Quick Test:
# Test the public Rapier service
curl https://rapier.chukai.io/health
# Use with chuk-mcp-physics locally
export RAPIER_SERVICE_URL=https://rapier.chukai.io
uvx chuk-mcp-physicsIf you need your own private Rapier service instance:
cd rapier-service
# Login to Fly.io
fly auth login
# Create Redis instance for distributed storage
fly redis create
# Choose: your-rapier-redis, region sjc (or your preferred region), plan 256MB
# Set Redis URL secret (use URL from previous step)
fly secrets set REDIS_URL="redis://default:password@fly-your-rapier-redis.upstash.io"
# Create and deploy the service
fly apps create your-rapier-physics
fly deploy
# Verify Redis connection in logs
fly logs
# Look for: "📦 Initialized RedisStorage backend"
# Add custom domain (optional)
fly certs add rapier.yourdomain.com -a your-rapier-physics
# Verify service is running
curl https://your-rapier-physics.fly.dev/healthRedis Benefits:
✅ Horizontal scaling (multiple service instances share state)
✅ Automatic cleanup (TTL-based simulation expiration)
✅ Distributed coordination across instances
✅ Session persistence within TTL window
Configuration:
The service uses Redis automatically on Fly.io (see rapier-service/fly.toml). For local development, it defaults to in-memory storage.
See rapier-service/FLY_REDIS_SETUP.md for detailed Redis setup guide, monitoring, and troubleshooting.
# Option 1: Environment variable
export RAPIER_SERVICE_URL=https://rapier.yourdomain.com
uvx chuk-mcp-physics
# Option 2: YAML config (physics.yaml)
# rapier:
# service_url: https://rapier.yourdomain.comWhy deploy your own?
🔒 Private instance for production workloads
📈 Custom scaling and resource allocation
🌍 Deploy closer to your users (different regions)
💾 Persistent simulations and custom configurations
See DEPLOYMENT.md for complete deployment guide, scaling strategies, and CI/CD setup.
For full rigid-body simulations, you have several options:
# No setup required - just configure the URL
export RAPIER_SERVICE_URL=https://rapier.chukai.io
uvx chuk-mcp-physics# Using Docker
docker run -p 9000:9000 chuk-rapier-service
# Configure to use local service
export RAPIER_SERVICE_URL=http://localhost:9000
uvx chuk-mcp-physics# Build and run the Rust service
cd rapier-service
cargo run --release
# In another terminal
export RAPIER_SERVICE_URL=http://localhost:9000
uvx chuk-mcp-physicsSee RAPIER_SERVICE.md for:
Complete API specification
Rust implementation guide
Docker deployment details
Testing examples
Feature | Analytic Provider | Rapier Provider |
Projectile motion | ✅ Exact (kinematic eqs) | ✅ Simulated |
Simple collisions | ✅ Exact (sphere-sphere, elastic) | ✅ Simulated |
Force/energy/momentum | ✅ F=ma, KE, PE, momentum, work/power | ✅ Can derive from sim |
Fluid dynamics | ✅ Drag, buoyancy, terminal velocity | ❌ Not supported |
Rigid-body dynamics | ❌ Not supported | ✅ Full 3D/2D physics |
Complex shapes | ❌ Spheres only | ✅ Box, capsule, mesh, etc |
Friction/restitution | ❌ Not modeled | ✅ Full material properties |
Multi-body systems | ❌ Not supported | ✅ Unlimited bodies |
Constraints/joints | ❌ Not supported | ✅ Hinges, sliders, etc |
Performance | ⚡ Instant | 🐇 Fast (Rust) |
Setup | 📦 Built-in | 🦀 Requires Rapier service |
Recommendation:
Use Analytic for simple calculations, education, quick answers
Use Rapier for complex simulations, games, visualizations, multi-body dynamics
Contributions welcome! Please see CONTRIBUTING.md.
Apache License 2.0 - see LICENSE for details.
This is a demonstration project provided as-is for learning and testing purposes.
Rapier - Fast 2D/3D physics engine in Rust
Model Context Protocol - Protocol specification
RAPIER_SERVICE.md - Rapier microservice specification
Examples - Example usage patterns
API Documentation - Detailed tool reference
Add a joint/constraint to connect two rigid bodies.
Joints allow you to constrain the motion between bodies:
- FIXED: Rigid connection (glue objects together)
- REVOLUTE: Hinge rotation around an axis (doors, pendulums)
- SPHERICAL: Ball-and-socket rotation (ragdolls, gimbals)
- PRISMATIC: Sliding along an axis (pistons, elevators)
Args:
sim_id: Simulation identifier
joint: Joint definition with type and parameters
Returns:
joint_id: Unique identifier for the created joint
Example - Simple Pendulum:
# Create fixed anchor point
add_rigid_body(
sim_id=sim_id,
body_id="anchor",
body_type="static",
shape="sphere",
size=[0.05],
position=[0.0, 5.0, 0.0],
)
# Create pendulum bob
add_rigid_body(
sim_id=sim_id,
body_id="bob",
body_type="dynamic",
shape="sphere",
size=[0.1],
mass=1.0,
position=[0.0, 3.0, 0.0],
)
# Connect with revolute joint (hinge)
add_joint(
sim_id=sim_id,
joint=JointDefinition(
id="pendulum_joint",
joint_type="revolute",
body_a="anchor",
body_b="bob",
anchor_a=[0.0, 0.0, 0.0], # Center of anchor
anchor_b=[0.0, 0.1, 0.0], # Top of bob
axis=[0.0, 0.0, 1.0], # Rotate around Z-axis
),
)
| Name | Required | Description | Default |
|---|---|---|---|
| sim_id | Yes | ||
| joint | Yes | Definition for creating a joint between two bodies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes outcome (constrain motion between bodies) and lists joint types, but does not disclose error handling, prerequisites (bodies must exist), or side effects. No annotations provided to compensate.
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?
Well-structured with summary, type descriptions, args/returns, and a detailed example. Every sentence adds value; no wasted words.
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?
Covers the core functionality, joint types, and a full example. Lacks explanation of return values (joint_id) and edge cases, but is sufficient for a creation tool with a complex input schema.
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?
Adds meaning beyond schema by explaining joint types and showing parameter usage in example. Schema coverage is 50% (sim_id lacks description), but the description includes sim_id in example. The nested joint object properties are well-documented.
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?
Clearly states 'Add a joint/constraint to connect two rigid bodies' and lists joint types with descriptions. Differentiates from sibling tools like add_rigid_body by focusing on constraints.
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 explicit guidance on when to use each joint type (FIXED, REVOLUTE, etc.) and includes a complete example. Lacks explicit when-not-to-use or alternative tool mentions, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a rigid body to an existing simulation.
Creates a new physics body (static, dynamic, or kinematic) with specified
shape, mass, and initial conditions. Bodies interact via collisions.
Args:
sim_id: Simulation ID from create_simulation
body_id: Unique identifier for this body (user-defined string)
body_type: "static", "dynamic", or "kinematic"
- static: Never moves (ground, walls)
- dynamic: Affected by forces and collisions
- kinematic: Moves but not affected by forces (scripted motion)
shape: Collider shape: "box", "sphere", "capsule", "cylinder", "plane"
size: Shape dimensions:
- box: [width, height, depth]
- sphere: [radius]
- capsule: [half_height, radius]
- cylinder: [half_height, radius]
- plane: not needed (use normal/offset instead)
mass: Mass in kilograms (for dynamic bodies). Default 1.0
normal: Normal vector [x, y, z] for plane shape. Default [0, 1, 0] (upward)
offset: Offset along normal for plane. Default 0.0
position: Initial position [x, y, z]. Default [0, 0, 0]
orientation: Initial orientation quaternion [x, y, z, w]. Default [0, 0, 0, 1] (identity)
velocity: Initial linear velocity [x, y, z]. Default [0, 0, 0]
angular_velocity: Initial angular velocity [x, y, z]. Default [0, 0, 0]
restitution: Bounciness (0.0 = no bounce, 1.0 = perfect bounce). Default 0.5
friction: Surface friction (0.0 = ice, 1.0 = rubber). Default 0.5
is_sensor: If true, detects collisions but doesn't respond physically. Default false
linear_damping: Linear velocity damping (0.0-1.0) - like air resistance. Default 0.0
angular_damping: Angular velocity damping (0.0-1.0) - like rotational friction. Default 0.0
drag_coefficient: Base drag coefficient (Cd) for orientation-dependent drag. Optional
drag_area: Reference cross-sectional area (m²) for drag calculation. Optional
drag_axis_ratios: Drag variation along body axes [x, y, z]. E.g., [1.0, 0.2, 1.0] for streamlined along Y. Optional
fluid_density: Fluid density (kg/m³). Air=1.225, Water=1000. Default 1.225
Returns:
body_id (echo of the input ID)
Tips for LLMs:
- Create ground FIRST: body_type="static", shape="plane", normal=[0, 1, 0]
- Box size is full width/height/depth (not half-extents)
- Sphere size is [radius] (array with one element)
- Quaternions: identity = [0, 0, 0, 1] (no rotation)
- Common restitution: steel=0.8, wood=0.5, clay=0.1
- Common friction: ice=0.05, wood=0.4, rubber=1.0
Example:
# Add a ground plane
await add_rigid_body(
sim_id=sim_id,
body_id="ground",
body_type="static",
shape="plane",
normal=[0, 1, 0]
)
# Add a bouncing ball
await add_rigid_body(
sim_id=sim_id,
body_id="ball",
body_type="dynamic",
shape="sphere",
size=[0.5], # radius = 0.5m
mass=1.0,
position=[0, 10, 0],
restitution=0.7
)
# Add a falling box
await add_rigid_body(
sim_id=sim_id,
body_id="box",
body_type="dynamic",
shape="box",
size=[1.0, 1.0, 1.0],
mass=10.0,
position=[0.0, 5.0, 0.0]
)
| Name | Required | Description | Default |
|---|---|---|---|
| sim_id | Yes | ||
| body_id | Yes | ||
| body_type | Yes | ||
| shape | Yes | ||
| size | No | ||
| mass | No | ||
| normal | No | ||
| offset | No | ||
| position | No | ||
| orientation | No | ||
| velocity | No | ||
| angular_velocity | No | ||
| restitution | No | ||
| friction | No | ||
| is_sensor | No | ||
| linear_damping | No | ||
| angular_damping | No | ||
| drag_coefficient | No | ||
| drag_area | No | ||
| drag_axis_ratios | No | ||
| fluid_density | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It explains how body types behave, collision interactions, sensor mode, drag physics, default values, and return value. It also clarifies nuances like box size being full extents and plane shape not needing size. Extremely transparent.
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 well-structured: summary, parameter list, tips, examples. It is front-loaded with purpose. However, it is somewhat verbose—each parameter has a sentence explaining its default—but this is justified by the complexity (21 parameters). A minor improvement would be to group defaults more succinctly.
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, the description still explains the return value (body_id). It covers all parameters, prerequisites, behavioral nuances (collisions, sensor mode, drag), and provides multiple examples. For a 21-parameter tool, this is highly complete. Missing error handling info, but acceptable.
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 must (and does) provide all parameter details. It explains each parameter's meaning, valid values, defaults, and inter-dependencies (e.g., plane uses normal/offset). Examples illustrate usage. This adds immense value beyond the raw 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 clearly states it adds a rigid body to an existing simulation, with detailed subtypes (static, dynamic, kinematic). It distinguishes from siblings like create_simulation (creates the simulation) and add_joint (adds constraints). The example usage makes its purpose unmistakable.
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 the simulation must already exist (prerequisite). It provides tips like creating ground first and shows common use cases in examples. However, it does not explicitly exclude alternative tools or state when not to use this tool (e.g., for modifying existing bodies). But the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze circular orbit at given altitude above planet surface.
Comprehensive orbital analysis combining period, velocity, and acceleration.
Args:
altitude: Altitude above surface in meters
planet_mass: Planet mass in kg
planet_radius: Planet radius in meters
gravitational_constant: G in m³/(kg⋅s²) (default 6.674e-11)
Returns:
Dict containing:
- orbital_radius: r from planet center in meters
- orbital_velocity: v in m/s
- period_seconds: Orbital period in seconds
- period_minutes: Orbital period in minutes
- centripetal_acceleration: a_c in m/s²
Example - LEO satellite at 400km altitude:
result = await analyze_circular_orbit(
altitude=400000, # 400 km
planet_mass=5.972e24, # Earth
planet_radius=6.371e6 # Earth
)
# v ≈ 7,670 m/s, T ≈ 92.6 min
| Name | Required | Description | Default |
|---|---|---|---|
| altitude | Yes | ||
| planet_mass | Yes | ||
| planet_radius | Yes | ||
| gravitational_constant | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description effectively discloses the output structure (dict with orbital radius, velocity, period, acceleration) and the default gravitational constant. It lacks mention of error handling or constraints (e.g., altitude must be positive), but it is largely transparent for a physics computation 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 well-structured with distinct sections for purpose, arguments, returns, and example. Every sentence adds value and there is no redundancy. It is concise yet informative.
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 absence of an output schema, the description fully enumerates return keys. It includes a helpful example. However, it could be more complete by mentioning assumptions (e.g., circular orbit, no atmospheric drag) and ensuring consistency in units. Still, it is largely adequate.
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 fully compensates by defining each parameter with units and providing a concrete example. This adds significant meaning beyond the minimal 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 clearly states the tool analyzes a circular orbit at a given altitude, combining period, velocity, and acceleration. This distinguishes it from sibling tools like calculate_orbital_period or calculate_centripetal_force which compute single quantities.
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?
No explicit guidance on when to use this tool versus alternatives (e.g., using individual calculation tools). The example hints at a typical use case but does not state when this combined analysis is preferred or not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate acceleration by numerical differentiation of position data.
Uses central differences for numerical differentiation:
v[i] ≈ (r[i+1] - r[i-1]) / (2Δt)
a[i] ≈ (v[i+1] - v[i-1]) / (2Δt)
Args:
times: Time values in seconds (or JSON string)
positions: Position vectors [[x,y,z], ...] in meters (or JSON string)
Returns:
Dict containing:
- velocities: Velocity vectors [[x,y,z], ...] in m/s
- accelerations: Acceleration vectors [[x,y,z], ...] in m/s²
- average_velocity: Average velocity [x,y,z] in m/s
- average_acceleration: Average acceleration [x,y,z] in m/s²
Example - Analyze recorded position data:
result = await calculate_acceleration_from_position(
times=[0, 1, 2, 3],
positions=[[0,0,0], [5,0,0], [10,0,0], [15,0,0]]
)
| Name | Required | Description | Default |
|---|---|---|---|
| times | Yes | ||
| positions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full responsibility. It details the numerical method (central differences), explains input format flexibility (arrays or JSON strings), and outlines the return structure. However, it does not discuss edge cases like non-uniform time steps, insufficient data points, or error handling.
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 well-structured with separate sections for purpose, formulas, arguments, return values, and an example. Every sentence adds value without redundancy, making it efficient and easy to parse.
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 moderate complexity (numerical differentiation), the description covers the core method, input/output details, and an example. It is nearly complete, though it could mention the minimum number of time points required (at least 3 for central differences) and whether uniform time steps are assumed.
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 input schema has 0% description coverage, but the description compensates fully by explaining that 'times' are time values in seconds (or JSON string) and 'positions' are position vectors in meters (or JSON string), with a concrete example demonstrating the expected format.
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 calculates acceleration from position data via numerical differentiation using central differences. It specifies the formulas and distinguishes itself from sibling tools like calculate_instantaneous_velocity and calculate_jerk by focusing on acceleration from position history.
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 provides an example usage for analyzing recorded position data. It implies the tool is for discrete time-series data but does not explicitly exclude other use cases or mention alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate angular acceleration: α = τ / I.
Angular acceleration is the rotational equivalent of linear acceleration.
Determined by net torque and moment of inertia.
Args:
torque: Torque magnitude in N⋅m
moment_of_inertia: Moment of inertia in kg⋅m²
Returns:
Dict containing:
- angular_acceleration: α in rad/s²
Tips for LLMs:
- Rotational version of F = ma → τ = Iα
- Larger I means slower angular acceleration for same torque
- Use for: motor acceleration, spinning up flywheels
Example - Motor accelerating a wheel:
result = await calculate_angular_acceleration(
torque=10.0, # N⋅m
moment_of_inertia=0.5 # kg⋅m²
)
# α = 20 rad/s²
| Name | Required | Description | Default |
|---|---|---|---|
| torque | Yes | ||
| moment_of_inertia | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully explains the tool as a pure calculation with no side effects. It clearly states inputs, formula, and output. Lacks mention of edge cases or potential errors (e.g., zero moment of inertia).
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?
Well-structured with sections: formula, description, args, returns, tips, example. Front-loaded with key formula. Every sentence adds value; no redundancy.
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 only two numeric parameters and no output schema, the description fully explains input semantics, output format, and provides an example. Tips add educational value. Complete for the tool's simplicity.
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?
Input schema has 0% coverage for descriptions, but the description compensates by providing units ('N⋅m', 'kg⋅m²') and an example with concrete values, adding 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?
Description clearly states 'Calculate angular acceleration' with formula α = τ / I, using specific verb and resource. It distinguishes from siblings like 'calculate_torque' and 'calculate_momentum' by focusing on rotational dynamics.
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 explicit usage context: 'Use for: motor acceleration, spinning up flywheels' and includes an example. However, it does not mention when not to use or contrast with alternatives like 'calculate_torque' or 'calculate_angular_momentum'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate angular momentum: L = I × ω.
Angular momentum is the rotational equivalent of linear momentum.
It's conserved in the absence of external torques (like ice skater spinning).
Args:
moment_of_inertia: Moment of inertia in kg⋅m²
angular_velocity_x: X component of angular velocity in rad/s
angular_velocity_y: Y component of angular velocity in rad/s
angular_velocity_z: Z component of angular velocity in rad/s
Returns:
Dict containing:
- angular_momentum: L vector [x, y, z] in kg⋅m²/s
- magnitude: L magnitude in kg⋅m²/s
Tips for LLMs:
- Angular momentum is conserved when no external torques act
- Ice skater pulls arms in → I decreases → ω increases (L constant)
- Gyroscopes resist changes in angular momentum direction
Example - Spinning figure skater:
# Arms extended: I = 3.0 kg⋅m², ω = 5 rad/s
result = await calculate_angular_momentum(
moment_of_inertia=3.0,
angular_velocity_x=0.0,
angular_velocity_y=5.0,
angular_velocity_z=0.0
)
# L = 15 kg⋅m²/s (conserved when arms pulled in)
| Name | Required | Description | Default |
|---|---|---|---|
| moment_of_inertia | Yes | ||
| angular_velocity_x | Yes | ||
| angular_velocity_y | Yes | ||
| angular_velocity_z | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return format (vector and magnitude) and provides an example, but does not mention side effects, error conditions, or behavior for edge cases like zero moment of inertia. The conservation context is informative but not behavioral.
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 somewhat verbose, including educational tips and a detailed example that could be shortened. However, it is well-structured with sections for Args, Returns, Tips, and Example, aiding readability.
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 lack of output schema and annotations, the description provides sufficient context: parameter details, return format, a concrete example, and educational notes on conservation. It covers most aspects needed to use the tool correctly, though error handling and precision are not addressed.
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 has 0% description coverage, so the description compensates by listing each parameter with units (e.g., 'Moment of inertia in kg⋅m²', 'angular velocity components in rad/s'). This adds meaningful context beyond the schema types and is essential for correct usage.
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 'Calculate angular momentum' and provides the formula L = I × ω, effectively communicating the tool's purpose. While it distinguishes from linear momentum through the formula, it does not explicitly differentiate from sibling rotational tools like calculate_torque or calculate_moment_of_inertia.
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 the tool's function and includes conservation tips, but lacks explicit guidance on when to use this tool versus alternatives such as calculate_momentum (linear) or calculate_angular_acceleration. The usage is implied by the name and formula, but no when-not-to-use conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate average speed along a path.
Average speed = total distance / total time
(Distance is path length, not displacement)
Args:
positions: Position vectors [[x,y,z], ...] in meters (or JSON string)
times: Time values in seconds (or JSON string)
Returns:
Dict containing:
- average_speed: Average speed in m/s
- total_distance: Total path length in meters
- total_time: Total elapsed time in seconds
- displacement_magnitude: Straight-line displacement in meters
- displacement: Displacement vector [x,y,z] in meters
Example - Car on winding road:
result = await calculate_average_speed(
positions=[[0,0,0], [10,5,0], [20,10,0], [15,20,0]],
times=[0, 10, 20, 30]
)
| Name | Required | Description | Default |
|---|---|---|---|
| positions | Yes | ||
| times | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully assumes the burden. It explains the calculations and return dictionary fields. It does not mention side effects or permissions, but for a stateless calculation tool this is sufficient.
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 concise, front-loaded with purpose, and uses a clear structure with Args, Returns, and an Example section. Every sentence adds 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?
Despite lacking an output schema, the description comprehensively details all return fields. Given the tool's simplicity and the presence of many similar sibling tools, the description is 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?
With 0% schema description coverage, the description fully compensates by explaining that positions are position vectors and times are time values, including units and acceptable formats (list or JSON string). The example further clarifies usage.
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 'Calculate average speed along a path' and provides the formula. It distinguishes from sibling tools like calculate_instantaneous_velocity by focusing on average over a segment.
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 includes the formula and return values but does not explicitly advise when to use this tool versus alternatives like calculate_instantaneous_velocity. Usage is implied but not contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate ideal banking angle: θ = arctan(v² / (rg)).
For a banked curve, the ideal angle where no friction is needed
to maintain the turn at a given speed.
Args:
velocity: Speed in m/s
radius: Turn radius in meters
gravity: Gravitational acceleration in m/s² (default 9.81)
Returns:
Dict containing:
- angle_radians: Banking angle in radians
- angle_degrees: Banking angle in degrees
Tips for LLMs:
- Faster speed → steeper banking angle
- Tighter turn → steeper banking angle
- NASCAR tracks banked ~30° for high-speed turns
- At ideal angle, normal force provides all centripetal force
Example - Highway exit ramp:
result = await calculate_banking_angle(
velocity=25, # m/s (90 km/h)
radius=100 # meter radius turn
)
# θ ≈ 32.5°
| Name | Required | Description | Default |
|---|---|---|---|
| velocity | Yes | ||
| radius | Yes | ||
| gravity | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: it calculates the ideal banking angle using the given formula and returns a dict with angle in radians and degrees. It explains the physics concept and includes practical tips, leaving no ambiguity about the tool's 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?
The description is well-structured with sections for formula, args, returns, tips, and an example. It is somewhat lengthy but each part adds value. Minor redundancy in the formula repetition could 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?
Given the simple input schema and no output schema, the description provides adequate coverage: formula, parameter explanations, return structure, and a concrete example. It does not discuss edge cases (e.g., invalid inputs) but this is acceptable for a straightforward physics calculator.
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 input schema has 0% description coverage, so the description must and does provide full semantics: velocity in m/s, radius in meters, gravity in m/s² with default 9.81. This adds critical meaning beyond the bare schema types.
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 'Calculate ideal banking angle' and provides the formula θ = arctan(v² / (rg)). It is specific to banking angle calculation, distinguishing it from sibling tools that handle other physics computations.
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 does not explicitly state when to use this tool versus alternatives. While it provides tips and an example, it lacks comparative guidance with sibling tools for similar calculations (e.g., centripetal force). Usage context is implied but not clearly delineated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate reaction forces for a simply supported beam.
Uses moment equilibrium about supports to find reaction forces.
Args:
beam_length: Beam length in meters
loads: Point loads in Newtons (downward positive) (or JSON string)
load_positions: Positions of loads from left end in meters (or JSON string)
Returns:
Dict containing:
- reaction_left: Reaction force at left support in Newtons
- reaction_right: Reaction force at right support in Newtons
- total_load: Total downward load in Newtons
- is_balanced: Whether reactions balance loads
Example - Beam with two loads:
result = await calculate_beam_reactions(
beam_length=10.0,
loads=[1000, 500],
load_positions=[3.0, 7.0]
)
| Name | Required | Description | Default |
|---|---|---|---|
| beam_length | Yes | ||
| loads | Yes | ||
| load_positions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description carries full burden. It mentions downward positive loads and returns a dict, but lacks edge case handling (e.g., invalid inputs, distributed loads). Partially transparent.
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?
Structured with Args, Returns, and Example. Informative but slightly verbose; could be trimmed without losing clarity.
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, so description includes return dict. Covers basic beam reaction calculation. Missing error handling and units consistency, but sufficient for simple use.
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?
Adds meaning beyond schema: loads and load_positions are described as point loads in Newtons and positions in meters, with 'or JSON string'. beam_length only gets 'in meters'. Schema coverage 0% makes this valuable.
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?
Description clearly states 'Calculate reaction forces for a simply supported beam', which is a specific verb+resource. It distinguishes from sibling tools like calculate_force or calculate_torque.
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 an example and explains the method (moment equilibrium). Does not explicitly state when not to use or alternatives, but the tool is unique among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate Bernoulli's equation: P + (1/2)ρv² + ρgh = constant.
Energy conservation for flowing fluids.
Args:
pressure1: Pressure at point 1 in Pascals
velocity1: Flow velocity at point 1 in m/s
height1: Height at point 1 in meters
velocity2: Flow velocity at point 2 in m/s (optional)
height2: Height at point 2 in meters (optional)
fluid_density: Fluid density in kg/m³ (default 1000 for water)
gravity: Gravitational acceleration in m/s² (default 9.81)
Returns:
Dict containing:
- total_pressure_1: Total pressure at point 1
- static_pressure_1: Static pressure component
- dynamic_pressure_1: Dynamic pressure component
- hydrostatic_pressure_1: Hydrostatic pressure component
- pressure2: Pressure at point 2 (if velocity2/height2 given)
Example - Water tank with outlet:
result = await calculate_bernoulli(
pressure1=101325, # Atmospheric at top
velocity1=0, # Still water
height1=10, # 10m height
velocity2=14, # Exit velocity
height2=0, # Ground level
fluid_density=1000
)
| Name | Required | Description | Default |
|---|---|---|---|
| pressure1 | Yes | ||
| velocity1 | Yes | ||
| height1 | Yes | ||
| velocity2 | No | ||
| height2 | No | ||
| fluid_density | No | ||
| gravity | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It thoroughly explains the parameters, units, default values, and return structure. However, it does not mention error handling, units conversion, or performance characteristics, which is acceptable for a pure calculation 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 well-structured with formula, parameter list, return keys, and an example. It is slightly lengthy but each part adds value. The use of docstring-style formatting aids readability. Could be trimmed slightly, but overall efficient for the complexity.
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 output schema, the description explains the return dictionary keys and their meaning. The example is realistic and covers typical usage. All parameters are documented. The tool has moderate complexity with 7 parameters, and the description provides sufficient context for an agent to use it 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%, but the description adds full semantics: each parameter has units, explanation, and context (e.g., 'pressure1: Pressure at point 1 in Pascals'). The default values and optional nature of velocity2/height2 are clearly stated. This fully compensates for the missing schema descriptions.
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 it calculates Bernoulli's equation and provides the formula. The title is null but the name 'calculate_bernoulli' combined with the equation and explanation leaves no ambiguity about the tool's purpose. It is distinct from the many other physics calculation tools by focusing on Bernoulli's principle for fluid flow.
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 includes an example but does not explicitly state when to use this tool versus alternatives like calculate_venturi_effect or calculate_pressure_at_depth. Usage is implied by the equation's domain but no when-not-to-use or comparison to siblings is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate buoyancy force using Archimedes' principle.
The buoyant force equals the weight of displaced fluid:
F_b = ρ_fluid * V_submerged * g
Args:
volume: Object volume in m³
fluid_density: Fluid density in kg/m³ (water=1000, air=1.225)
gravity: Gravitational acceleration in m/s² (default 9.81)
submerged_fraction: Fraction submerged 0.0-1.0 (default 1.0 = fully submerged)
Returns:
Buoyant force (upward) and displaced mass
Example - Checking if a 1kg ball will float:
# 10cm diameter sphere: V = (4/3)πr³ = 0.000524 m³
result = await calculate_buoyancy(
volume=0.000524,
fluid_density=1000 # water
)
# buoyant_force = 5.14 N
# If weight (mg) < buoyant force, it floats
# 1kg * 9.81 = 9.81 N > 5.14 N, so it sinks
| Name | Required | Description | Default |
|---|---|---|---|
| volume | Yes | ||
| fluid_density | Yes | ||
| gravity | No | ||
| submerged_fraction | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully explains the calculation (buoyant force = displaced fluid weight) and returns: buoyant force and displaced mass. It does not mention side effects, auth, or rate limits (not needed), but it provides clear behavioral context for a calculation 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 well-structured with a formula, parameter explanations, return values, and a concrete example. It is concise yet covers all necessary information without extra fluff.
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 complexity (4 parameters, no output schema), the description is complete: it explains parameters, return values, and provides an example usage. The example ties everything together for practical understanding.
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 compensates fully. It explains each parameter: volume in m³, fluid_density with typical values (water=1000, air=1.225), gravity default (9.81), and submerged_fraction range (0.0-1.0) and default (1.0). Adds units and examples.
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 it calculates buoyancy force using Archimedes' principle, with a specific formula. It distinguishes itself from sibling physics calculation tools by focusing on buoyancy, and the example further clarifies its purpose.
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 when to use the tool (calculating buoyancy force) and provides an example showing how to apply it to real-world scenarios like checking if an object floats. However, it lacks explicit guidance on when not to use it or comparisons with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate center of mass for a system of point masses.
Formula: r_cm = Σ(m_i × r_i) / Σm_i
Args:
masses: List of masses in kg (or JSON string)
positions: List of positions [[x,y,z], ...] in meters (or JSON string)
Returns:
Dict containing:
- center_of_mass: Position [x, y, z] in meters
- total_mass: Total system mass in kg
Example - Three-mass system:
result = await calculate_center_of_mass(
masses=[1.0, 2.0, 3.0],
positions=[[0,0,0], [1,0,0], [2,0,0]]
)
# center_of_mass ≈ [1.5, 0, 0]
| Name | Required | Description | Default |
|---|---|---|---|
| masses | Yes | ||
| positions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the calculation formula, expected input units (kg, meters), and the return structure including center_of_mass and total_mass. Since no annotations are provided, the description carries the full burden and does so effectively, though missing potential error conditions.
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 well-organized with sections for formula, args, returns, and an example. Every sentence adds value, and there is no redundancy or wasted text.
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 is complete for a calculation tool: it explains inputs, units, outputs, and provides an example. Minor gaps exist, such as error handling for empty lists or mismatched dimensions, but overall it is sufficient.
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 input schema only specifies types as 'string', but the description explains that masses should be a list of floats in kg and positions a list of coordinates in meters, optionally as JSON strings. This adds essential meaning 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?
The description explicitly states 'Calculate center of mass for a system of point masses' and provides the formula, clearly differentiating it from sibling tools that calculate other physical quantities.
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?
While the purpose is clear, the description does not provide explicit guidance on when to use this tool versus alternatives like calculate_moment_of_inertia. The example offers usage context but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate centripetal force: F_c = m v² / r.
Force required to keep an object moving in a circle.
Always points toward the center of the circular path.
Args:
mass: Mass in kg
velocity: Speed (velocity magnitude) in m/s
radius: Radius of circular path in meters
Returns:
Dict containing:
- centripetal_force: F_c in Newtons
- centripetal_acceleration: a_c in m/s²
Tips for LLMs:
- Not a new force - it's the net inward force (tension, friction, gravity)
- Faster speed → much more force needed (v² relationship)
- Tighter turn → more force needed
- Use for: car turns, satellite orbits, centrifuges
Example - Car turning:
result = await calculate_centripetal_force(
mass=1500, # kg
velocity=20, # m/s (72 km/h)
radius=50 # meter turn radius
)
# F_c = 12000 N (provided by friction between tires and road)
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | ||
| velocity | Yes | ||
| radius | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses that it returns a dict with centripetal force and acceleration, explains physics behavior (v² relationship, direction). Lacks explicit statement that it's a pure calculation without 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?
Well-structured with formula, explanation, args, returns, tips, and example. Every sentence adds value, front-loaded with essential information.
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 output schema, the description explains the return dict structure. Covers key physics context, examples, and tips. No missing elements for a calculation 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?
Schema description coverage is 0%, but the description defines each parameter's units and meaning (mass in kg, velocity in m/s, radius in meters). Provides an example with real values, compensating fully for schema's lack of description.
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 purpose: calculate centripetal force using the formula F_c = m v² / r. It distinguishes from sibling tools like calculate_force and other specific forces by focusing on circular motion.
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 tips on when to use (car turns, satellite orbits, centrifuges) and explains it's the net inward force, not a new force. Could be improved by explicitly stating when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate damped oscillation with friction/resistance.
Real oscillators lose energy over time due to damping (air resistance,
friction). Three regimes: underdamped, critically damped, overdamped.
Args:
mass: Mass in kg
spring_constant: k in N/m
damping_coefficient: b in kg/s (damping strength)
time: Time t in seconds
initial_position: Initial position in meters (default 1.0)
initial_velocity: Initial velocity in m/s (default 0.0)
Returns:
Dict containing:
- position: x(t) in meters
- velocity: v(t) in m/s
- damping_ratio: ζ (zeta) = b/(2√(mk))
- regime: "underdamped", "critically_damped", or "overdamped"
Damping regimes:
- ζ < 1: Underdamped (oscillates, gradually decays)
- ζ = 1: Critically damped (returns fastest without oscillating)
- ζ > 1: Overdamped (slow return, no oscillation)
Example - Car suspension:
result = await calculate_damped_oscillation(
mass=300, # kg (quarter car mass)
spring_constant=20000, # N/m
damping_coefficient=2000, # kg/s
time=1.0
)
# Should be slightly underdamped for comfort
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | ||
| spring_constant | Yes | ||
| damping_coefficient | Yes | ||
| time | Yes | ||
| initial_position | No | ||
| initial_velocity | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully describes the tool's behavior: it returns position, velocity, damping ratio, and regime, and explains the three damping regimes. It does not mention side effects or performance, but for a calculation tool this is sufficient.
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 well-structured with sections for Args, Returns, Damping regimes, and an Example. It is slightly verbose but every sentence adds value. Front-loaded with core purpose. Could be more concise by merging some explanations.
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 tool's complexity (physics of damped oscillations) and the absence of an output schema, the description is complete. It explains all output fields, the damping ratio calculation, and the three regimes. The example further clarifies usage.
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 input schema has no descriptions (0% coverage), but the description thoroughly explains each parameter with units and default values. It adds critical meaning beyond the schema, such as 'mass in kg' and 'damping_coefficient: damping strength', making it very helpful.
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 calculates damped oscillation with friction/resistance, defines three damping regimes, and provides an example. It distinguishes itself from siblings like calculate_simple_harmonic_motion by focusing on damping.
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 does not explicitly state when to use this tool versus alternatives like calculate_simple_harmonic_motion or calculate_projectile_with_drag. However, its detailed explanation of damping regimes implies the specific context of damped oscillators.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate drag force for an object moving through a fluid.
The drag force opposes motion and is given by:
F_drag = 0.5 * ρ * v² * C_d * A
Common drag coefficients:
- Sphere: 0.47
- Streamlined shape: 0.04
- Flat plate (perpendicular): 1.28
- Human (standing): 1.0-1.3
- Car: 0.25-0.35
Args:
velocity: Velocity vector [x, y, z] in m/s (or JSON string)
cross_sectional_area: Area perpendicular to flow in m²
fluid_density: Fluid density in kg/m³ (water=1000, air=1.225)
drag_coefficient: Drag coefficient (default 0.47 for sphere)
viscosity: Dynamic viscosity in Pa·s (water=1.002e-3, air=1.825e-5, oil=0.1).
If not provided, estimated from fluid_density for Reynolds number calculation.
Returns:
Drag force vector, magnitude, and Reynolds number
Example - Ball falling through water:
result = await calculate_drag_force(
velocity=[0, -5.0, 0],
cross_sectional_area=0.00785, # π * (0.05m)² for 10cm diameter
fluid_density=1000, # water
drag_coefficient=0.47,
viscosity=1.002e-3 # water viscosity for accurate Reynolds number
)
# Returns upward drag force opposing downward motion
Example - Ball falling through motor oil:
result = await calculate_drag_force(
velocity=[0, -2.0, 0],
cross_sectional_area=0.00785,
fluid_density=900, # oil
drag_coefficient=0.47,
viscosity=0.1 # motor oil is much more viscous
)
| Name | Required | Description | Default |
|---|---|---|---|
| velocity | Yes | ||
| cross_sectional_area | Yes | ||
| fluid_density | Yes | ||
| drag_coefficient | No | ||
| viscosity | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses the formula, return values (drag force vector, magnitude, Reynolds number), and behavioral details like viscosity estimation when omitted. No contradictions.
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 formula and purpose, and provides structured examples. It is detailed but somewhat long; every sentence contributes value, though minor redundancy exists.
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?
Despite lacking an output schema, the description explains return values and covers all parameters comprehensively. Examples illustrate usage in different scenarios, making the tool fully understandable.
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?
Input schema has 0% description coverage, but the description compensates thoroughly by explaining each parameter with units, defaults, and typical values (e.g., 'velocity: Velocity vector [x, y, z] in m/s').
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 'Calculate drag force for an object moving through a fluid', uses a specific verb-resource pair, and the formula and context distinguish it from siblings like lift force or buoyancy.
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 includes common drag coefficients and examples for different fluids, which imply typical use cases, but it does not explicitly state when to use this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate final velocities after a 1D elastic collision.
Uses conservation of momentum and energy to solve for final velocities.
Assumes perfectly elastic collision (no energy loss).
Args:
mass1: Mass of first object in kg
velocity1: Initial velocity of first object in m/s (1D)
mass2: Mass of second object in kg
velocity2: Initial velocity of second object in m/s (1D)
Returns:
Dict containing:
- final_velocity1: Final velocity of object 1 in m/s
- final_velocity2: Final velocity of object 2 in m/s
- initial_kinetic_energy: Total KE before (J)
- final_kinetic_energy: Total KE after (J) - should equal initial
- initial_momentum: Total momentum before (kg⋅m/s)
- final_momentum: Total momentum after (kg⋅m/s) - should equal initial
Example - Pool ball collision:
result = await calculate_elastic_collision(
mass1=0.17, # kg (pool ball)
velocity1=2.0, # m/s (moving right)
mass2=0.17, # kg (pool ball)
velocity2=0.0 # m/s (stationary)
)
# Result: ball 1 stops, ball 2 moves at 2.0 m/s
| Name | Required | Description | Default |
|---|---|---|---|
| mass1 | Yes | ||
| velocity1 | Yes | ||
| mass2 | Yes | ||
| velocity2 | Yes |
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 discloses the physics assumptions (perfectly elastic, 1D) and the full set of return values. It does not discuss edge cases or potential errors, but for a pure calculation tool, it is reasonably transparent.
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 well-structured with clear sections for Args, Returns, and Example. Some redundancy exists (e.g., repeating 'conservation of momentum and energy'), but overall it is efficient and front-loaded.
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 output schema, the description thoroughly explains the return dict and includes a concrete example. It partially covers parameter semantics (units). Missing constraints like positive mass, but for a physics tool it is fairly complete among many sibling tools.
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% with 4 parameters lacking descriptions. The description adds units (kg, m/s) and clarifies that velocities are 1D. It does not specify allowed ranges (e.g., mass > 0), but the provided information is meaningful 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?
The description clearly states it calculates final velocities after a 1D elastic collision using conservation of momentum and energy. It distinguishes itself from siblings like calculate_inelastic_collision_3d by specifying 'elastic' and '1D'.
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 specifies it's for perfectly elastic collisions in 1D, with an example of pool ball collision. It does not explicitly mention when not to use it or contrast with 3D version, but the context is clear enough for an agent to select the appropriate tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate 3D elastic collision (perfect energy conservation).
Special case of collision where no kinetic energy is lost (e = 1.0).
Both momentum and energy are conserved.
Args:
mass1: Mass of object 1 in kg
velocity1: Velocity of object 1 [x, y, z] in m/s (or JSON string)
mass2: Mass of object 2 in kg
velocity2: Velocity of object 2 [x, y, z] in m/s (or JSON string)
Returns:
Dict containing:
- final_velocity1: Final velocity [x, y, z] in m/s
- final_velocity2: Final velocity [x, y, z] in m/s
- initial_momentum: Total momentum [x, y, z]
- final_momentum: Total momentum [x, y, z]
- initial_kinetic_energy: Total KE in Joules
- final_kinetic_energy: Total KE in Joules
Tips for LLMs:
- Ideal approximation for billiard balls, Newton's cradle
- Both momentum and energy conserved
- Equal masses + head-on → velocities exchange
- Use for educational examples, idealized systems
Example - Pool balls:
result = await calculate_elastic_collision_3d(
mass1=0.17, # kg (pool ball)
velocity1=[2, 0, 0], # 2 m/s
mass2=0.17, # kg
velocity2=[0, 0, 0] # stationary
)
# Result: ball 1 stops, ball 2 moves at 2 m/s
| Name | Required | Description | Default |
|---|---|---|---|
| mass1 | Yes | ||
| velocity1 | Yes | ||
| mass2 | Yes | ||
| velocity2 | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: it conserves both momentum and energy, returns final velocities and verification quantities. The example demonstrates expected behavior (ball 1 stops, ball 2 moves). No hidden side effects or destructive actions.
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 well-structured with clear sections (Args, Returns, Tips, Example). Every sentence adds value—no fluff. Front-loaded with main purpose, then details. Appropriate length for a physics tool with multiple parameters and a complex output.
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 output schema, the description fully specifies return values (two velocity arrays, two momentum vectors, two energy values). It includes an example with realistic values and expected outcome, covering all necessary context for an AI agent to understand and use the 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?
All four parameters are explained with units, types, and input formats (list or JSON string). The schema has 0% description coverage, so the description compensates fully, adding meaning beyond bare schema like 'velocity of object 1 [x, y, z] in m/s (or JSON string)'.
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's function with specific verb and resource: 'Calculate 3D elastic collision (perfect energy conservation).' It distinguishes from siblings by explicitly noting it's the elastic version (e=1.0) and hints at 3D specificity, differentiating from potentially 2D siblings like 'calculate_elastic_collision'.
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 provides when-to-use tips (e.g., 'Ideal approximation for billiard balls, Newton's cradle') and key physics behavior (equal masses exchange velocities). It does not explicitly mention when not to use or compare to inelastic version, but the special case note and example imply appropriate contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate escape velocity: v_escape = √(2GM/r).
Minimum speed needed to escape a celestial body's gravitational pull.
Independent of the escaping object's mass.
Args:
mass: Mass of celestial body in kg
radius: Radius of celestial body in meters
gravitational_constant: G in m³/(kg⋅s²) (default 6.674e-11)
Returns:
Dict containing:
- escape_velocity: v_escape in m/s
- escape_velocity_kmh: v_escape in km/h (for convenience)
Tips for LLMs:
- Earth: v_escape ≈ 11,200 m/s (40,320 km/h)
- Moon: v_escape ≈ 2,380 m/s
- Sun: v_escape ≈ 617,500 m/s
- Independent of escape direction or mass of escaping object
Example - Earth escape velocity:
result = await calculate_escape_velocity(
mass=5.972e24, # Earth mass (kg)
radius=6.371e6 # Earth radius (meters)
)
# v_escape ≈ 11,186 m/s
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | ||
| radius | Yes | ||
| gravitational_constant | No |
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 discloses the formula, key properties (independence of mass), default gravitational constant, and expected behavior. No contradictions.
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 well-structured with formula, key facts, parameter list, return info, tips, and an example. Every sentence is informative and efficient, with no redundancy.
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 output schema, the description details the return format (dictionary with two velocity fields including units) and provides an example result. It is fully complete for a physics calculation 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?
Schema description coverage is 0%, but the description explains each parameter (mass, radius, gravitational_constant with units and default). This adds essential 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?
The description clearly states the tool calculates escape velocity with the formula v_escape = √(2GM/r). It specifies the inputs and outputs, distinguishing it from sibling physics calculation tools by its specific purpose.
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 tips with example values for Earth, Moon, Sun and notes independence of escape direction and mass. However, it does not explicitly contrast with sibling tools or state when to use this over alternatives like calculate_orbital_period.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate force from mass and acceleration using Newton's Second Law (F = ma).
Computes the force vector required to produce a given acceleration on a mass.
Fundamental for dynamics, engineering, and understanding motion.
Args:
mass: Mass in kilograms (must be positive)
acceleration_x: X component of acceleration in m/s²
acceleration_y: Y component of acceleration in m/s²
acceleration_z: Z component of acceleration in m/s²
Returns:
ForceCalculationResponse containing:
- force: Force vector [x, y, z] in Newtons
- magnitude: Force magnitude in Newtons
Tips for LLMs:
- 1 Newton = force to accelerate 1 kg at 1 m/s²
- On Earth, weight force = mass × 9.81 N (vertical)
- Use magnitude to compare total force regardless of direction
- Common accelerations: car braking ~10 m/s², elevator ~2 m/s²
Example:
# Force to accelerate a 1500kg car at 3 m/s² forward
result = await calculate_force(
mass=1500.0,
acceleration_x=3.0,
acceleration_y=0.0,
acceleration_z=0.0
)
print(f"Required force: {result.magnitude:.0f} N")
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | ||
| acceleration_x | Yes | ||
| acceleration_y | Yes | ||
| acceleration_z | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully covers behavior: it computes a force vector and magnitude, and provides tips about Earth's gravity and common accelerations. No destructive side effects exist, so this is transparent.
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 well-structured with Args, Returns, Tips, and Example, but the Tips section is somewhat verbose for an LLM. Overall, it is clear and front-loaded, with minimal redundancy.
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 provides complete information: parameters, return value details, and a worked example, ensuring the agent can invoke it 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%, but the description adds detailed semantics: mass must be positive, acceleration components in m/s², and the formula. This compensates fully for the lack of schema descriptions.
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 explicitly states 'Calculate force from mass and acceleration using Newton's Second Law (F = ma)', with a specific verb and resource. It distinguishes from sibling tools like calculate_drag_force or calculate_angular_acceleration by focusing on the fundamental F=ma relation.
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 'Fundamental for dynamics, engineering, and understanding motion', implying it is the default choice for basic force calculations. It does not explicitly mention when not to use or alternatives, but the context of being fundamental provides adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate spring force using Hooke's Law: F = -kx.
The restoring force is proportional to displacement from equilibrium.
Fundamental for springs, elastic materials, and simple harmonic motion.
Args:
spring_constant: Spring constant k in N/m (stiffness)
displacement: Displacement from equilibrium in meters
Returns:
Dict containing:
- force: Restoring force magnitude in Newtons
- potential_energy: Elastic potential energy in Joules
Tips for LLMs:
- Stiffer spring → larger k → more force for same displacement
- Potential energy stored in spring: PE = (1/2)kx²
- Negative sign in F = -kx means force opposes displacement
Example - Compressing a car spring:
result = await calculate_hookes_law(
spring_constant=10000, # N/m (stiff car spring)
displacement=0.05 # 5cm compression
)
# Force = 500 N, PE = 12.5 J
| Name | Required | Description | Default |
|---|---|---|---|
| spring_constant | Yes | ||
| displacement | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: the formula, parameter meanings, return values, and even the negative sign implication. It is completely transparent.
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 concise yet comprehensive, with a clear structure: formula, explanation, parameter details, return, tips, and example. No wasted words.
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 is complete for a simple 2-param tool without output schema. It covers purpose, physics, parameters, return values, and provides an example.
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 coverage, the description compensates fully by explaining each parameter's units and meaning, and also describes the return structure.
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 it calculates spring force using Hooke's Law, with a clear verb and resource. It distinguishes from siblings like calculate_force by specifying the exact law and application.
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 provides context for when to use (springs, elastic materials, SHM) and includes tips, but does not explicitly state when not to use or compare to similar tools like calculate_elastic_collision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate 3D collision with coefficient of restitution.
Models realistic collisions where some kinetic energy is lost.
Coefficient of restitution (e) determines how much energy is retained.
Args:
mass1: Mass of object 1 in kg
velocity1: Velocity of object 1 [x, y, z] in m/s (or JSON string)
mass2: Mass of object 2 in kg
velocity2: Velocity of object 2 [x, y, z] in m/s (or JSON string)
coefficient_of_restitution: e (0.0 = perfectly inelastic, 1.0 = perfectly elastic)
Returns:
Dict containing:
- final_velocity1: Final velocity [x, y, z] in m/s
- final_velocity2: Final velocity [x, y, z] in m/s
- initial_momentum: Total initial momentum [x, y, z]
- final_momentum: Total final momentum [x, y, z]
- initial_kinetic_energy: Total initial KE in Joules
- final_kinetic_energy: Total final KE in Joules
- energy_loss: Energy lost in Joules
- energy_loss_percent: % of energy lost
Coefficient of restitution values:
- e = 0.0: Perfectly inelastic (clay, putty) - objects stick
- e = 0.5: Very inelastic (wet clay)
- e = 0.7: Moderately elastic (basketball)
- e = 0.9: Highly elastic (Super Ball)
- e = 1.0: Perfectly elastic (ideal, no energy loss)
Tips for LLMs:
- Momentum is always conserved (regardless of e)
- Energy lost = (1 - e²) × initial KE in center-of-mass frame
- Use e=1.0 for billiard balls, e=0.0 for car crashes
Example - Car crash:
result = await calculate_inelastic_collision_3d(
mass1=1500, # kg
velocity1=[20, 0, 0], # 20 m/s east
mass2=1200, # kg
velocity2=[-15, 0, 0], # 15 m/s west
coefficient_of_restitution=0.1 # very inelastic
)
# Massive energy loss, objects nearly stick together
| Name | Required | Description | Default |
|---|---|---|---|
| mass1 | Yes | ||
| velocity1 | Yes | ||
| mass2 | Yes | ||
| velocity2 | Yes | ||
| coefficient_of_restitution | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that momentum is always conserved and explains energy loss behavior with the coefficient. It does not mention any side effects, limitations, or edge cases, but the core behavioral traits are well-covered.
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 thorough but somewhat lengthy. It is well-structured with sections (Args, Returns, Tips, Example), which aids clarity. However, some parts (like Tips for LLMs) add valuable context but could be more concise.
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 absence of output schema and sparse input schema, the description fully compensates by detailing all parameters, return values, and physical context. It is complete for an agent to invoke the 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?
With 0% schema description coverage, the description adds extensive meaning: units (kg, m/s), format of velocity (array or JSON string), range and defaults for coefficient, and full return fields. This is far 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?
The description clearly states it calculates 3D inelastic collisions with a coefficient of restitution, differentiating it from sibling tools like calculate_elastic_collision_3d. The verb 'calculate' and resource '3D collision' are specific, and the context of energy loss is explicit.
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 provides explicit guidance on when to use the tool, including coefficient of restitution values and example use cases (e.g., billiard balls vs. car crashes). It also clarifies momentum conservation and offers tips for LLMs, leaving little ambiguity about appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate instantaneous velocity at a specific time.
Uses interpolation if target_time is between data points,
otherwise uses numerical differentiation.
Args:
positions: Position vectors [[x,y,z], ...] in meters (or JSON string)
times: Time values in seconds (or JSON string)
target_time: Time at which to calculate velocity in seconds
Returns:
Dict containing:
- velocity: Velocity vector [x,y,z] in m/s
- speed: Speed magnitude in m/s
- interpolated: Whether interpolation was used
- time: Target time (echo)
Example:
result = await calculate_instantaneous_velocity(
positions=[[0,0,0], [3,4,0], [6,8,0]],
times=[0, 1, 2],
target_time=1.0
)
# speed = 5 m/s
| Name | Required | Description | Default |
|---|---|---|---|
| positions | Yes | ||
| times | Yes | ||
| target_time | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the algorithm (interpolation/differentiation) and the return structure, including fields like 'interpolated'. Despite no annotations, it is transparent about key behaviors. It lacks details on error handling or assumptions.
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 well-structured with sections for args, returns, and an example. It is concise yet informative, though the example adds length.
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 output schema and sparse input schema, the description provides complete context: purpose, method, all parameters, return values, and a concrete example. It leaves no major 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 coverage, the description adds significant meaning: it explains positions as vectors in meters or JSON string, times as seconds, and target_time as time. This compensates well for the sparse 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 explicitly states 'Calculate instantaneous velocity at a specific time' and distinguishes it from siblings like calculate_average_speed by detailing the method (interpolation vs differentiation).
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 when interpolation or numerical differentiation is used, providing clear context. However, it does not explicitly state when to use this tool over alternatives or exclude cases where it should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate jerk (rate of change of acceleration).
Jerk = da/dt is important for comfort in vehicles and mechanical design.
Args:
times: Time values in seconds (or JSON string)
accelerations: Acceleration vectors [[x,y,z], ...] in m/s² (or JSON string)
Returns:
Dict containing:
- jerks: Jerk vectors [[x,y,z], ...] in m/s³
- average_jerk: Average jerk [x,y,z] in m/s³
- max_jerk_magnitude: Maximum jerk magnitude in m/s³
Example:
result = await calculate_jerk(
times=[0, 1, 2, 3],
accelerations=[[0,0,0], [2,0,0], [4,0,0], [6,0,0]]
)
# jerk_x ≈ 2 m/s³ (constant)
| Name | Required | Description | Default |
|---|---|---|---|
| times | Yes | ||
| accelerations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does well by explaining the calculation formula, input requirements (times in seconds, accelerations in m/s²), and the detailed return structure. However, it does not disclose potential error conditions or input validation.
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 well-structured with a concise definition, parameter explanation, return format, and a clear code example. Every sentence adds value without redundancy.
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 purpose, parameters, and returns in sufficient detail for a pure calculation tool. It lacks output schema but compensates by explicitly listing returned fields. Minor omission: no mention of error handling or input constraints.
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 only specifies type 'string' for both parameters, leaving 0% coverage. The description adds essential meaning: times are in seconds, accelerations are vector arrays in m/s², and both can be passed as JSON strings. This vastly compensates for 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?
The description clearly states 'Calculate jerk (rate of change of acceleration)' with a specific verb and resource. It explains the physical importance and differentiates from sibling tools like calculate_angular_acceleration by focusing on linear jerk in 3D.
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 provides context with an example but lacks explicit guidance on when to use this tool versus alternatives like calculate_acceleration_from_position. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate kinetic energy from mass and velocity (KE = ½mv²).
Computes the energy of motion for a moving object. Energy is scalar
(direction doesn't matter, only speed). Useful for collision analysis,
vehicle safety, and understanding energy transfer.
Args:
mass: Mass in kilograms (must be positive)
velocity_x: X component of velocity in m/s
velocity_y: Y component of velocity in m/s
velocity_z: Z component of velocity in m/s
Returns:
KineticEnergyResponse containing:
- kinetic_energy: Energy in Joules (J)
- speed: Velocity magnitude in m/s
Tips for LLMs:
- 1 Joule = 1 kg⋅m²/s² = energy to lift 102g by 1m on Earth
- Kinetic energy doubles mass → doubles energy, doubles speed → 4× energy
- Car at highway speed (~30 m/s, 1500 kg) ≈ 675,000 J
- Use to compare impact severity or stopping distances
Example:
# Energy of a 0.145kg baseball at 40 m/s
result = await calculate_kinetic_energy(
mass=0.145,
velocity_x=40.0,
velocity_y=0.0,
velocity_z=0.0
)
print(f"Kinetic energy: {result.kinetic_energy:.1f} J")
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | ||
| velocity_x | Yes | ||
| velocity_y | Yes | ||
| velocity_z | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses behavior: kinetic energy is scalar, mass must be positive, velocity components in m/s, returns kinetic energy and speed. Comprehensive 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?
Well-structured with sections: description, args, returns, tips, example. Each section adds value, no fluff. Front-loaded with formula and purpose.
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?
Complete description for a 4-parameter tool with no output schema. Explains formula, units, scalar nature, tips, example, and return values thoroughly.
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 has 0% coverage, but the description explains each parameter (mass in kg, positive; velocity components in m/s) and provides an example and tips, adding significant meaning.
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?
Clearly states 'Calculate kinetic energy from mass and velocity (KE = ½mv²)' with a specific verb and resource. Distinguishes from sibling tools by focusing on kinetic energy.
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 context for use (collision analysis, vehicle safety, energy transfer) but does not explicitly state when not to use or differentiate from other energy tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate lift force using: L = (1/2) ρ v² C_L A.
Based on Bernoulli's principle and wing aerodynamics.
Args:
velocity: Flow velocity in m/s
wing_area: Wing area in m²
lift_coefficient: Lift coefficient C_L (dimensionless)
fluid_density: Fluid density in kg/m³ (air=1.225)
Returns:
Dict containing:
- lift_force: Lift force in Newtons
- dynamic_pressure: Dynamic pressure (q) in Pascals
Example - Aircraft wing:
result = await calculate_lift_force(
velocity=70, # m/s (~250 km/h)
wing_area=20.0, # m²
lift_coefficient=1.2,
fluid_density=1.225
)
| Name | Required | Description | Default |
|---|---|---|---|
| velocity | Yes | ||
| wing_area | Yes | ||
| lift_coefficient | Yes | ||
| fluid_density | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It clearly explains the calculation, input parameters with units, and return value structure (lift_force and dynamic_pressure). It does not mention side effects, but as a pure computational tool, this is appropriate. The transparency is high for a calculation 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 well-structured: formula, Args, Returns, and Example. Each sentence serves a purpose, and the brevity is appropriate for the complexity of the calculation. No redundant text, and the example aids understanding without being overly verbose.
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 no output schema, but the description fully specifies the return dict with fields lift_force and dynamic_pressure, including units. The example also shows expected results. Given the simplicity of the tool (pure calculation), the description provides complete information for correct usage.
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 input schema has no parameter descriptions (0% coverage), but the description compensates excellently by detailing each parameter with units and a default for fluid_density. The Args section lists velocity, wing_area, lift_coefficient, and fluid_density with explanations, and the example provides concrete values. This adds significant meaning 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?
The description clearly states the tool calculates lift force using the standard formula L = (1/2) ρ v² C_L A and references Bernoulli's principle and wing aerodynamics. It distinguishes itself from sibling tools like calculate_drag_force by focusing on lift, making its purpose 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 implies usage for lift force calculations through its formula and example, but it does not explicitly state when to use this tool versus alternatives (e.g., calculate_drag_force) or when not to use it. However, the example provides context for typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate Magnus force on a spinning ball.
The Magnus force is perpendicular to both velocity and spin axis.
Causes curve balls in sports.
Args:
velocity: Ball velocity [x, y, z] in m/s (or JSON string)
angular_velocity: Angular velocity [x, y, z] in rad/s (or JSON string)
radius: Ball radius in meters
fluid_density: Fluid density in kg/m³ (air=1.225)
Returns:
Dict containing:
- magnus_force: Magnus force vector [x, y, z] in Newtons
- magnus_force_magnitude: Force magnitude in Newtons
- spin_rate: Spin rate (angular velocity magnitude) in rad/s
Example - Soccer ball curve:
result = await calculate_magnus_force(
velocity=[20, 0, 0], # 20 m/s forward
angular_velocity=[0, 0, 50], # 50 rad/s topspin
radius=0.11, # Soccer ball
fluid_density=1.225
)
| Name | Required | Description | Default |
|---|---|---|---|
| velocity | Yes | ||
| angular_velocity | Yes | ||
| radius | Yes | ||
| fluid_density | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explains that the Magnus force is perpendicular to velocity and spin axis, describes the return dict structure, and provides units. It lacks details on error handling or side effects, but for a calculation tool this is adequate.
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 well-structured with a summary line, physics explanation, parameter list, returns, and an example. It is longer than necessary but every section adds value. The front-loading with the core purpose is effective.
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?
Despite lacking an output schema, the description fully documents the return structure and includes an example. It covers the essential aspects of the tool: input format, output, and physical principle. Minor omissions like error conditions are acceptable given the tool's simplicity.
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 input schema only defines types (string, number), but the description adds critical meaning: velocity and angular_velocity are arrays in m/s or rad/s (or JSON strings), radius in meters, fluid density with default. The example further clarifies usage, compensating for the schema's lack of descriptions.
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 calculates Magnus force on a spinning ball, a specific physics calculation. It distinguishes itself from sibling tools by specifying the unique physics phenomenon, and the example reinforces its use for sports balls.
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 provides context for use (spinning ball, sports) but does not explicitly state when to use this tool versus alternatives or when not to use it. The example implies typical usage, but no comparative guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate moment of inertia for various shapes.
Moment of inertia (I) is the rotational equivalent of mass. It determines
how difficult it is to change an object's rotation. Depends on both mass
distribution and rotation axis.
Args:
shape: Shape type - "sphere", "solid_sphere", "hollow_sphere", "rod", "disk", "cylinder", "box"
mass: Mass in kilograms
radius: Radius for sphere/disk/cylinder (meters)
length: Length for rod (meters)
width: Width for box (meters)
height: Height for box/cylinder (meters)
depth: Depth for box (meters)
axis: Rotation axis - "center", "end" (for rod), "x", "y", "z" (for box)
Returns:
Dict containing:
- moment_of_inertia: I in kg⋅m²
- shape: Shape type
- axis: Rotation axis
Common formulas:
- Solid sphere (center): I = (2/5)mr²
- Hollow sphere (center): I = (2/3)mr²
- Rod (center): I = (1/12)mL²
- Rod (end): I = (1/3)mL²
- Disk (center): I = (1/2)mr²
Example - Spinning wheel:
result = await calculate_moment_of_inertia(
shape="disk",
mass=5.0, # 5kg wheel
radius=0.3 # 30cm radius
)
# I = 0.225 kg⋅m²
| Name | Required | Description | Default |
|---|---|---|---|
| shape | Yes | ||
| mass | Yes | ||
| radius | No | ||
| length | No | ||
| width | No | ||
| height | No | ||
| depth | No | ||
| axis | No | center |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the concept of moment of inertia, lists formulas, and provides an example. However, it does not disclose behavior for invalid inputs, edge cases, or how missing parameters are handled (e.g., when shape requires length but not provided).
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 thorough but lengthy, including a general definition of moment of inertia that may be unnecessary. It is front-loaded with purpose, but later sections (formulas, example) could be abbreviated without losing clarity.
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 8 parameters and no output schema, the description explains inputs thoroughly and provides a minimal output dict. It lacks error handling details and behavior for invalid combinations (e.g., rod without length), but overall covers most aspects adequately.
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 input schema has 0% description coverage, so the description must compensate, and it does excellently. Each parameter is explained with context (units, allowed values, dependencies on shape). Common formulas show how parameters relate, adding significant meaning beyond schema names.
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 calculates moment of inertia for various shapes. It lists specific shapes and provides formulas, making its purpose unambiguous and distinguishable from sibling tools that perform other physics calculations.
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 usage for rotational inertia problems but does not explicitly state when to use this tool versus others like calculate_torque or calculate_angular_momentum. No exclusion criteria or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate momentum from mass and velocity (p = mv).
Computes the momentum vector, which represents "quantity of motion."
Momentum is conserved in collisions, making it crucial for analyzing
impacts, explosions, and rocket propulsion.
Args:
mass: Mass in kilograms (must be positive)
velocity_x: X component of velocity in m/s
velocity_y: Y component of velocity in m/s
velocity_z: Z component of velocity in m/s
Returns:
MomentumResponse containing:
- momentum: Momentum vector [x, y, z] in kg⋅m/s
- magnitude: Momentum magnitude in kg⋅m/s
Tips for LLMs:
- Momentum is a vector (has direction), unlike kinetic energy
- Total momentum before collision = total momentum after (conservation)
- Large mass × small velocity can equal small mass × large velocity
- Use to analyze: collisions, recoil, rocket thrust
Example:
# Momentum of a 70kg person running at 5 m/s
result = await calculate_momentum(
mass=70.0,
velocity_x=5.0,
velocity_y=0.0,
velocity_z=0.0
)
print(f"Momentum: {result.magnitude:.1f} kg⋅m/s")
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | ||
| velocity_x | Yes | ||
| velocity_y | Yes | ||
| velocity_z | Yes |
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 describes the computation, the vector nature, and conservation, but does not explicitly state that it is a stateless, non-destructive operation. This is a minor gap.
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 well-structured with Args, Returns, Tips, and Example sections. It is front-loaded with the formula, every sentence adds value, and there is no redundancy.
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 explains the return structure (momentum vector and magnitude) and provides physics context. Minor omissions include no error handling guidance (e.g., negative mass) and implicit units for momentum (shown in example but not explicitly in description).
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 input schema has 0% description coverage. The description compensates excellently by explaining each parameter (mass must be positive, velocity components in m/s) and providing an example. This adds significant 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?
The description explicitly states 'Calculate momentum from mass and velocity (p = mv)', clearly specifying the verb, resource, and formula. It distinguishes itself from sibling tools like calculate_force or calculate_kinetic_energy by directly naming momentum.
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 provides context on when to use the tool (e.g., analyzing impacts, explosions, rocket propulsion) and mentions conservation of momentum. However, it does not explicitly state when not to use it or compare it to alternative tools for collisions among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate normal force on an inclined plane.
On an incline at angle θ:
- N = mg cos(θ) + F_additional
- Weight component perpendicular: mg cos(θ)
- Weight component parallel: mg sin(θ)
Args:
mass: Object mass in kg
gravity: Gravitational acceleration in m/s² (default 9.81)
angle_degrees: Incline angle in degrees (0 = horizontal)
additional_force: Additional perpendicular force in Newtons (optional)
Returns:
Dict containing:
- normal_force: Normal force in Newtons
- weight_component_perpendicular: Weight component ⊥ to surface
- weight_component_parallel: Weight component ∥ to surface
Example - Box on 30° ramp:
result = await calculate_normal_force(
mass=10.0,
angle_degrees=30.0
)
# normal_force ≈ 84.9 N
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | ||
| gravity | No | ||
| angle_degrees | No | ||
| additional_force | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description explains the calculation, includes formulas, default values, and return values. It is transparent but could mention limitations like angle ranges.
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 well-structured with formulas, parameter descriptions, return dict, and an example. Every sentence adds value without being verbose.
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 formula-based physics tool with no output schema, the description is complete: it explains formulas, parameters, return values, and includes an example.
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 coverage, the description fully compensates by detailing each parameter (mass, gravity, angle_degrees, additional_force), including units, defaults, and formula relation.
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 it calculates normal force on an inclined plane, provides the formula, and distinguishes from sibling tools by specific context (inclined plane).
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 use for inclined plane normal force but lacks explicit guidance on when to use vs alternative tools or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate orbital period: T = 2π√(r³/GM).
Kepler's Third Law for circular orbits. Period depends on orbital
radius and central body mass.
Args:
orbital_radius: Orbital radius in meters (from center of central body)
central_mass: Mass of central body in kg
gravitational_constant: G in m³/(kg⋅s²) (default 6.674e-11)
Returns:
Dict containing:
- period: Orbital period in seconds
- orbital_velocity: v in m/s
- period_hours: Period in hours (for convenience)
- period_days: Period in days (for convenience)
Tips for LLMs:
- Higher orbit → longer period
- More massive central body → shorter period
- Earth: M = 5.972e24 kg, R = 6.371e6 m
- Moon orbit: r ≈ 384,400 km, T ≈ 27.3 days
- ISS orbit: r ≈ 6,771 km (altitude 400 km), T ≈ 90 minutes
Example - ISS orbit:
result = await calculate_orbital_period(
orbital_radius=6.771e6, # meters
central_mass=5.972e24 # Earth mass (kg)
)
# T ≈ 5,558 seconds ≈ 92.6 minutes
| Name | Required | Description | Default |
|---|---|---|---|
| orbital_radius | Yes | ||
| central_mass | Yes | ||
| gravitational_constant | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description carries full burden. It fully discloses the formula, all parameters, return values, and limitations (circular orbits only). Tips and examples further clarify behavior.
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 well-structured with formula, Args, Returns, Tips, and Example sections, but is somewhat verbose. Could be slightly more concise without losing key information.
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 output schema and no annotations, the description is remarkably complete: it explains purpose, all parameters, full return dictionary with four fields, helpful tips, and a worked example. No gaps for an LLM to infer.
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 input schema has 0% description coverage, but the description explains each parameter in detail, including units, default for gravitational_constant, and provides concrete examples with values.
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 it calculates orbital period using Kepler's Third Law for circular orbits, with specific verb 'Calculate orbital period' and equation. It is distinct from sibling tools like 'analyze_circular_orbit' which likely does more comprehensive analysis.
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 provides clear context for when to use this tool (calculating orbital period for circular orbits) but does not explicitly mention when not to use it or compare to alternatives like 'analyze_circular_orbit'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate pendulum period: T = 2π√(L/g).
Period of a simple pendulum depends only on length and gravity
(for small amplitudes). Includes correction for large amplitudes.
Args:
length: Pendulum length in meters (pivot to center of mass)
gravity: Gravitational acceleration in m/s² (default 9.81)
amplitude_degrees: Amplitude in degrees (optional, for large angle correction)
Returns:
Dict containing:
- period: T in seconds
- frequency: f in Hz
- angular_frequency: ω in rad/s
- small_angle_approximation: Whether small angle formula was used
Tips for LLMs:
- Period independent of mass (Galileo's discovery)
- Period independent of amplitude (for small angles < 15°)
- Longer pendulum → longer period
- Use for: clocks, playground swings, seismometers
Example - Grandfather clock:
result = await calculate_pendulum_period(
length=0.994, # meters (for 2-second period)
gravity=9.81
)
# T = 2.0 seconds
| Name | Required | Description | Default |
|---|---|---|---|
| length | Yes | ||
| gravity | No | ||
| amplitude_degrees | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: formula, dependence only on length and gravity, large-angle correction, and return structure including small_angle_approximation flag. No contradictions.
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 well-structured with formula, args, returns, tips, and example. It is slightly lengthy but every section adds value. Front-loaded with the formula.
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 output schema, the description fully specifies the return dict. It covers theory, parameters, output, and includes an example. Complete for a simple physics 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?
Schema coverage is 0%, but the description explains each parameter in detail: length in meters from pivot to center of mass, gravity default 9.81 m/s², optional amplitude_degrees for correction. It also describes the return dict.
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 it calculates the pendulum period using the formula T = 2π√(L/g). The verb 'calculate' and resource 'pendulum period' are specific. It is distinct from sibling tools like calculate_orbital_period or calculate_spring_mass_period.
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 provides implicit usage context through tips (e.g., independence of mass, small angle approximation) and an example. However, it does not explicitly state when to use this tool over siblings like calculate_simple_harmonic_motion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate gravitational potential energy.
Computes PE = mgh (mass × gravity × height).
Also returns the equivalent velocity if the object falls from that height.
Args:
mass: Object mass in kilograms
height: Height above reference point in meters
gravity: Gravitational acceleration in m/s² (default 9.81 for Earth)
Returns:
Dict containing:
- potential_energy: PE in Joules
- equivalent_kinetic_velocity: Speed if dropped from height (m/s)
Example - Object at 10m height:
result = await calculate_potential_energy(mass=2.0, height=10.0)
# PE = 196.2 J
# Velocity if dropped = 14.0 m/s
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | ||
| height | Yes | ||
| gravity | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for transparency. It clearly states the formula, default gravity value, and that an additional derived value (equivalent kinetic velocity) is returned. It does not mention side effects or destruction, but as a calculation tool, that is appropriate.
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 moderately long but well-structured with sections (description, args, returns, example). It front-loads the core formula and then details parameters and output. A minor improvement could be trimming the example explanation, but overall it is clear and efficient.
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 output schema, the description fully describes the return values (potential_energy in Joules, equivalent_kinetic_velocity in m/s). With only 3 parameters, all documented, and no constraints or enums, the description covers all necessary context for 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?
Schema description coverage is 0%, yet the description fully explains each parameter: mass (kg), height (m), gravity (default 9.81 m/s²). It provides units, defaults, and an example that illustrates usage. The schema only provides types and defaults without descriptions, so the description adds essential meaning.
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 it calculates gravitational potential energy using the formula PE = mgh, and explicitly distinguishes from siblings by specifying the formula and that it also returns equivalent kinetic velocity. The verb 'calculate' and resource 'potential energy' are specific, and the addition of 'gravitational' reinforces the scope.
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 does not provide explicit guidance on when to use this tool versus alternatives like calculate_kinetic_energy or other potential energy forms. The example and formula imply its use case, but no 'when not to use' or comparative statements are given. Given many siblings, this is a gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate pressure at depth: P = P_atm + ρgh.
Hydrostatic pressure increases with depth.
Args:
depth: Depth below surface in meters
fluid_density: Fluid density in kg/m³ (water=1000, seawater=1025)
atmospheric_pressure: Pressure at surface in Pascals (default 101325)
gravity: Gravitational acceleration in m/s² (default 9.81)
Returns:
Dict containing:
- total_pressure: Total pressure in Pascals
- gauge_pressure: Pressure above atmospheric in Pascals
- pressure_atmospheres: Pressure in atmospheres (1 atm = 101325 Pa)
Example - Scuba diving at 30m:
result = await calculate_pressure_at_depth(
depth=30, # meters
fluid_density=1025, # seawater
atmospheric_pressure=101325
)
# Result: ~4 atmospheres
| Name | Required | Description | Default |
|---|---|---|---|
| depth | Yes | ||
| fluid_density | Yes | ||
| atmospheric_pressure | No | ||
| gravity | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries full burden. It clearly explains the mathematical relationship and return fields, though it does not disclose edge cases or error handling (e.g., negative depth). The behavior is largely transparent for a simple calculation 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 well-structured with formula, args, returns, and an example. Every sentence provides essential information without redundancy. It is front-loaded with the core formula and promptly details parameters.
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 tool's simplicity, no output schema, and no annotations, the description is complete. It covers all parameters, return fields, and provides a realistic example. The sibling tools are all physics calculations, and this description is adequate for differentiation and usage.
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 input schema has no descriptions (0% coverage). The description compensates fully by explaining each parameter, providing typical values, defaults, and a complete example. It adds crucial meaning beyond the schema's raw type definitions.
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 explicitly states 'Calculate pressure at depth' with the formula P = P_atm + ρgh, clearly identifying the tool's purpose. It is distinct from siblings like calculate_buoyancy and calculate_drag_force, which focus on other physical phenomena.
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 provides a concrete scuba diving example, implying usage scenarios, but does not explicitly guide when to use this tool versus related siblings like calculate_buoyancy or calculate_bernoulli. It lacks 'when not to use' or alternative tool recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate projectile motion trajectory using kinematic equations.
Computes the complete trajectory of a projectile launched at an angle,
including maximum height, range, time of flight, and sample trajectory points.
Perfect for ballistics, sports analysis, or educational demonstrations.
Args:
initial_velocity: Initial velocity in meters per second (m/s). Must be positive.
angle_degrees: Launch angle in degrees from horizontal (0-90).
0° = horizontal, 45° = maximum range, 90° = straight up
initial_height: Initial height above ground in meters. Default 0.0 (ground level).
gravity: Gravitational acceleration in m/s². Default 9.81 (Earth surface).
Use 1.62 for Moon, 3.71 for Mars, etc.
Returns:
ProjectileMotionResponse containing:
- max_height: Maximum height reached (meters)
- range: Horizontal distance traveled (meters)
- time_of_flight: Total time in air (seconds)
- trajectory_points: List of [x, y] sample points for plotting
Tips for LLMs:
- 45° gives maximum range on flat ground (no air resistance)
- For R3F visualization: convert trajectory_points to 3D by adding z=0
- trajectory_points are evenly spaced in time (50 samples)
- Air resistance is NOT modeled - this is ideal ballistic motion
- Use for: cannon balls, baseballs, basketball shots, water fountains
Example:
# Calculate trajectory of a cannonball fired at 50 m/s at 30°
result = await calculate_projectile_motion(
initial_velocity=50.0,
angle_degrees=30.0,
initial_height=2.0
)
print(f"Range: {result.range:.1f}m, Max height: {result.max_height:.1f}m")
| Name | Required | Description | Default |
|---|---|---|---|
| initial_velocity | Yes | ||
| angle_degrees | Yes | ||
| initial_height | No | ||
| gravity | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it models ideal ballistic motion without air resistance, describes parameters and their constraints, and details the return structure. There are no contradictions.
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 well-structured with clear sections (summary, Args, Returns, Tips, Example). It is thorough without being verbose; every sentence adds 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?
Given no output schema, the description covers return fields in detail. All four parameters are explained, and usage context is provided. The example and tips ensure completeness for an LLM.
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%, but the description provides detailed parameter semantics: initial_velocity must be positive, angle_degrees range 0-90 with explanation, default values for initial_height and gravity, and alternative gravity values. This fully compensates.
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 calculates projectile motion using kinematic equations, listing outputs like max height, range, time of flight, and trajectory points. It distinguishes itself from sibling tools like calculate_projectile_with_drag by explicitly specifying that air resistance is not modeled.
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 provides use cases (ballistics, sports, education) and tips (45° for max range, conversion to 3D). It implies when not to use (when air resistance matters) but does not explicitly name alternative tools. This is clear enough but could be more direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate projectile motion including air resistance (drag).
Uses numerical integration (RK4) to solve motion equations with:
- Quadratic drag force: F_drag = 0.5 * ρ * v² * Cd * A
- Magnus force (spin effects): F_magnus = 0.5 * ρ * Cl * A * ω * r * v
- Wind effects (constant wind vector)
- Variable air density (altitude and temperature effects)
This provides REALISTIC trajectories for sports balls, projectiles,
and other objects moving through air or water. Compare with
calculate_projectile_motion (no drag) to see dramatic differences!
Common drag coefficients (Cd):
- Sphere: 0.47 (default)
- Baseball: 0.4
- Golf ball: 0.25 (dimples reduce drag)
- Football (American): 0.05-0.15 (orientation-dependent)
- Basketball: 0.55
- Soccer ball: 0.25
- Skydiver (belly-down): 1.0-1.3
- Streamlined car: 0.25-0.35
Args:
initial_velocity: Launch velocity in m/s
angle_degrees: Launch angle in degrees (0-90)
mass: Object mass in kg
cross_sectional_area: Cross-section perpendicular to motion in m²
initial_height: Launch height in meters (default 0)
drag_coefficient: Drag coefficient Cd (default 0.47 for sphere)
fluid_density: Fluid density in kg/m³ (air=1.225, water=1000)
gravity: Gravitational acceleration m/s² (default 9.81)
time_step: Integration time step in seconds (default 0.01)
max_time: Maximum simulation time in seconds (default 30)
spin_rate: Spin rate in rad/s for Magnus force (default 0, no spin)
spin_axis: Spin axis unit vector [x, y, z] (default [0, 0, 1] = vertical)
wind_velocity: Wind velocity [vx, vy] in m/s (default [0, 0], no wind)
altitude: Altitude above sea level in meters (default 0, affects air density)
temperature: Air temperature in Celsius (default 15, affects air density)
Returns:
Dict containing:
- max_height: Maximum altitude reached (m)
- range: Horizontal distance traveled (m)
- time_of_flight: Total flight time (s)
- impact_velocity: Speed at landing (m/s)
- impact_angle: Angle at landing (degrees below horizontal)
- trajectory_points: [[x, y], ...] for plotting
- energy_lost_to_drag: Energy dissipated by drag (J)
- initial_kinetic_energy: Initial KE (J)
- final_kinetic_energy: Final KE (J)
- lateral_deflection: Lateral deflection from spin/wind (m)
- magnus_force_max: Maximum Magnus force magnitude (N)
- wind_drift: Total wind drift (m)
- effective_air_density: Effective air density used (kg/m³)
Example - Baseball curveball (2500 rpm backspin):
result = await calculate_projectile_with_drag(
initial_velocity=40.23, # 90 mph
angle_degrees=10,
mass=0.145,
cross_sectional_area=0.0043,
drag_coefficient=0.4,
spin_rate=261.8, # 2500 rpm = 261.8 rad/s
spin_axis=[0, 0, 1] # Backspin (vertical axis)
)
# Backspin increases range and height!
Example - Golf ball at altitude (Denver, 1600m):
result = await calculate_projectile_with_drag(
initial_velocity=70,
angle_degrees=12,
mass=0.0459,
cross_sectional_area=0.00143,
drag_coefficient=0.25,
altitude=1600, # Denver elevation
temperature=20 # Summer day
)
# Less air resistance = longer drive!
Example - Soccer free kick with wind:
result = await calculate_projectile_with_drag(
initial_velocity=25,
angle_degrees=15,
mass=0.43,
cross_sectional_area=0.0388,
drag_coefficient=0.25,
wind_velocity=[5, 0], # 5 m/s tailwind
spin_rate=50, # Sidespin for curve
spin_axis=[0, 1, 0] # Horizontal axis
)
# Wind drift + Magnus curve!
| Name | Required | Description | Default |
|---|---|---|---|
| initial_velocity | Yes | ||
| angle_degrees | Yes | ||
| mass | Yes | ||
| cross_sectional_area | Yes | ||
| initial_height | No | ||
| drag_coefficient | No | ||
| fluid_density | No | ||
| gravity | No | ||
| time_step | No | ||
| max_time | No | ||
| spin_rate | No | ||
| spin_axis | No | [0, 0, 1] | |
| wind_velocity | No | [0, 0] | |
| altitude | No | ||
| temperature | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description fully compensates by detailing method (RK4), forces, and return fields. No contradictions.
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?
Long but well-organized with sections, formulas, and examples. Could be slightly trimmed but earns its length due to complexity.
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, but description fully documents return dict. Examples cover diverse scenarios. Complete for a complex projectile 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?
Schema has 0% description coverage; description documents all 15 parameters with defaults, units, and common values, adding immense value well beyond 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?
Clearly states tool calculates projectile motion with drag using numerical integration. Distinguishes from sibling calculate_projectile_motion 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 explicit comparison with no-drag version and multiple sports examples, guiding when to use. Lacks explicit 'when not to use' but context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate Reynolds number: Re = ρvL/μ.
Determines flow regime (laminar, transitional, turbulent).
Args:
velocity: Flow velocity in m/s
characteristic_length: Characteristic length in meters (pipe diameter, etc.)
fluid_density: Fluid density in kg/m³
dynamic_viscosity: Dynamic viscosity in Pa·s (water=0.001, air=1.8e-5)
Returns:
Dict containing:
- reynolds_number: Re (dimensionless)
- flow_regime: "laminar" (Re<2300), "transitional" (2300-4000), "turbulent" (Re>4000)
Example - Water in pipe:
result = await calculate_reynolds_number(
velocity=2.0, # m/s
characteristic_length=0.05, # 5cm diameter
fluid_density=1000, # water
dynamic_viscosity=0.001
)
# Re = 100,000 → turbulent
| Name | Required | Description | Default |
|---|---|---|---|
| velocity | Yes | ||
| characteristic_length | Yes | ||
| fluid_density | Yes | ||
| dynamic_viscosity | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it computes Re, determines flow regime, provides typical viscosity values, and explains the return structure. No hidden behaviors.
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 well-organized with formula, parameter doc, returns, and example. It is concise yet complete, with no unnecessary text.
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 output schema, the description fully documents the return dict including reynolds_number and flow_regime with thresholds. The example further clarifies usage.
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?
Input schema has zero parameter descriptions (0% coverage). The description compensates by detailing each parameter with units, typical values, and the formula's role. Example shows concrete usage.
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 calculates Reynolds number and provides the formula. It distinguishes itself from sibling physics calculation tools by its specific purpose.
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 includes an example but does not explicitly state when to use this tool versus alternatives. Usage is implied by the tool name and context among many physics calculators.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate rotational kinetic energy: KE_rot = (1/2) I ω².
Energy of rotation. A spinning object has kinetic energy even if
its center of mass is stationary.
Args:
moment_of_inertia: Moment of inertia in kg⋅m²
angular_velocity: Angular velocity magnitude in rad/s
Returns:
Dict containing:
- rotational_ke: Rotational kinetic energy in Joules
Tips for LLMs:
- Total KE = translational KE + rotational KE
- Rolling object has both types of kinetic energy
- Flywheel energy storage uses this principle
Example - Car wheel at highway speed:
result = await calculate_rotational_kinetic_energy(
moment_of_inertia=0.5, # kg⋅m²
angular_velocity=100.0 # rad/s (fast spinning)
)
# KE_rot = 2500 J
| Name | Required | Description | Default |
|---|---|---|---|
| moment_of_inertia | Yes | ||
| angular_velocity | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It transparently describes return structure and the deterministic calculation, but lacks details on edge cases or validation.
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?
Well-structured with formula, parameter details, example, and tips. Slightly lengthy but each section adds value; front-loaded with key information.
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?
Covers essential aspects for a simple calculation tool: formula, parameters, return dict with unit. No output schema, so description of return value is necessary and provided. Lacks error handling info.
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 provides only numeric types (0% coverage). Description adds units (kg⋅m², rad/s) and clarifies each parameter's physical meaning, fully compensating for schema gaps.
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 explicitly states the tool calculates rotational kinetic energy, provides the formula KE_rot = (1/2) I ω², and distinguishes it from sibling tools like 'calculate_kinetic_energy' by specifying 'rotational'.
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?
Tips explain when to use (total KE, rolling objects, flywheel energy storage) and imply context, but no explicit when-not-to-use or comparison to similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate simple harmonic motion: x(t) = A cos(ωt + φ).
Position, velocity, and acceleration for sinusoidal oscillation.
Models ideal springs, pendulums, and many other oscillating systems.
Args:
amplitude: Amplitude A in meters (maximum displacement)
angular_frequency: ω in rad/s (ω = 2πf)
time: Time t in seconds
phase: Phase shift φ in radians (default 0)
Returns:
Dict containing:
- position: x(t) in meters
- velocity: v(t) = -Aω sin(ωt + φ) in m/s
- acceleration: a(t) = -Aω² cos(ωt + φ) in m/s²
Tips for LLMs:
- Position and acceleration are 180° out of phase
- Maximum velocity occurs at equilibrium (x = 0)
- Maximum acceleration occurs at maximum displacement
Example - Oscillating mass:
result = await calculate_simple_harmonic_motion(
amplitude=0.1, # 10cm amplitude
angular_frequency=5.0, # rad/s
time=1.0 # at t = 1s
)
| Name | Required | Description | Default |
|---|---|---|---|
| amplitude | Yes | ||
| angular_frequency | Yes | ||
| time | Yes | ||
| phase | No |
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 fully discloses the output structure (position, velocity, acceleration) with formulas and units, plus tips about phase relationships and maxima. This is completely transparent.
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 well-structured with distinct sections: formula, description, Args, Returns, Tips, and an example. Every sentence adds value without redundancy. The key information is front-loaded.
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 output schema, the description thoroughly explains return values with formulas and units. It covers all four parameters, required and optional, and provides a complete example. The tips further enhance usability.
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 input schema has 0% description coverage, so the description must compensate. It provides clear parameter explanations: amplitude in meters, angular_frequency in rad/s, time in seconds, phase in radians with default. This adds all necessary meaning 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?
The description explicitly states the tool calculates simple harmonic motion: position, velocity, and acceleration using the formula x(t)=A cos(ωt+φ). It identifies models like springs and pendulums, clearly distinguishing it from sibling tools that cover other mechanical calculations.
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?
While it doesn't explicitly state when not to use this tool, it provides context that it models ideal oscillating systems. The example and tips guide the agent on appropriate use cases. A score of 4 is given for clear context but no explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate period of spring-mass system: T = 2π√(m/k).
Natural oscillation frequency of a mass attached to a spring.
Independent of amplitude (for ideal springs).
Args:
mass: Mass in kg
spring_constant: Spring constant k in N/m
Returns:
Dict containing:
- period: T in seconds
- frequency: f in Hz
- angular_frequency: ω in rad/s
Tips for LLMs:
- Heavier mass → longer period (slower oscillation)
- Stiffer spring → shorter period (faster oscillation)
- ω = 2πf = √(k/m)
Example - Mass on spring:
result = await calculate_spring_mass_period(
mass=0.5, # 500g mass
spring_constant=20.0 # N/m
)
# T ≈ 0.99s, f ≈ 1.01 Hz
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | ||
| spring_constant | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, disclosing the physics assumptions (ideal springs, amplitude independence), output structure, and units. However, it lacks explicit mention of parameter limits or potential errors.
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 well-structured with sections for args, returns, tips, and an example, and every sentence provides essential information without redundancy.
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, no output schema, and only two parameters, the description covers all necessary aspects: formula, parameters, return values, assumptions, and an example, making it fully 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?
The input schema has no descriptions, but the tool description fully explains each parameter's units and physical meaning, and provides tips on how they affect the results, adding substantial value 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?
The description explicitly states that the tool calculates the period of a spring-mass system using the formula T = 2π√(m/k), clearly distinguishing it from sibling tools like calculate_pendulum_period and calculate_damped_oscillation.
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 provides tips on how mass and spring constant affect the period and includes an example, but does not explicitly state when to avoid using this tool (e.g., for non-ideal springs or damped systems).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate maximum static friction force: f_s,max = μ_s × N.
Determines whether an object will slip under applied force.
Args:
normal_force: Normal force in Newtons
coefficient_static_friction: Coefficient of static friction μ_s
applied_force: Applied horizontal force in Newtons (optional)
Returns:
Dict containing:
- max_static_friction: Maximum static friction in Newtons
- will_slip: Whether object will slip (if applied_force provided)
- friction_force: Actual friction force (if applied_force provided)
Example - Box on floor:
result = await calculate_static_friction(
normal_force=100,
coefficient_static_friction=0.5,
applied_force=40
)
# will_slip = False (40N < 50N max)
| Name | Required | Description | Default |
|---|---|---|---|
| normal_force | Yes | ||
| coefficient_static_friction | Yes | ||
| applied_force | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the tool's behavior: it computes static friction and optionally checks slip. It avoids any side effects, and the example clarifies the output format. No contradictions.
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 concise, well-structured with Args, Returns, and Example sections. Each sentence adds value, and the example illustrates usage efficiently without redundancy.
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 output schema, the description documents the full return dictionary with fields and conditions. It also includes a concrete example. For a simple physics calculator, this is complete and covers all necessary context.
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 input schema has 0% description coverage, so the description compensates fully. It explains each parameter (normal_force, coefficient_static_friction, applied_force) with units and optionality, and provides example values. This adds significant meaning 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?
The description explicitly states the tool calculates maximum static friction force and determines slip condition. It provides the formula f_s,max = μ_s × N and an example, making the purpose highly clear and distinct from sibling tools like calculate_kinetic_energy or calculate_force.
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 includes when to use (to check if an object slips) and gives an example, but does not explicitly mention alternatives or when not to use (e.g., kinetic friction). Still, the context is clear enough for most scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate terminal velocity when drag equals weight.
At terminal velocity, forces balance:
F_drag = F_weight
v_terminal = √(2mg / ρC_dA)
Args:
mass: Object mass in kg
cross_sectional_area: Area perpendicular to fall direction in m²
fluid_density: Fluid density in kg/m³ (air=1.225, water=1000)
drag_coefficient: Drag coefficient (sphere=0.47, skydiver=1.0)
gravity: Gravitational acceleration in m/s² (default 9.81)
Returns:
Terminal velocity, time to 95%, and drag force at terminal
Example - Skydiver terminal velocity:
result = await calculate_terminal_velocity(
mass=70, # kg
cross_sectional_area=0.7, # m² (belly-down position)
fluid_density=1.225, # air
drag_coefficient=1.0, # human
)
# v_terminal ≈ 54 m/s (120 mph)
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | ||
| cross_sectional_area | Yes | ||
| fluid_density | Yes | ||
| drag_coefficient | No | ||
| gravity | No |
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 explains the calculation, returns (terminal velocity, time to 95%, drag force), and includes an example output. This is adequate for a pure calculation 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 well-structured with a summary, formula, parameter list, and example. It is somewhat lengthy but front-loaded with the core purpose, and every part adds 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?
Given the tool's simplicity and lack of output schema, the description is complete: it covers inputs, formula, return values, and an example. No major 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?
Schema coverage is 0%, so the description fully compensates by defining each parameter, providing typical values (e.g., fluid density for air/water, drag coefficients), and listing defaults. This adds significant meaning beyond the input 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 clearly states the tool calculates terminal velocity when drag equals weight, with the formula provided. It is specific to terminal velocity, distinguishing it from sibling physics 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 provides context (when drag balances weight) and an example, but does not explicitly state when to use this tool versus alternatives like calculate_drag_force or calculate_projectile_with_drag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate torque from force and position: τ = r × F (cross product).
Torque is the rotational equivalent of force. It causes angular acceleration
and depends on both the force magnitude and the distance from the pivot point.
Args:
force_x: X component of force in Newtons
force_y: Y component of force in Newtons
force_z: Z component of force in Newtons
position_x: X component of position vector from pivot to force application (meters)
position_y: Y component of position vector from pivot to force application (meters)
position_z: Z component of position vector from pivot to force application (meters)
Returns:
Dict containing:
- torque: Torque vector [x, y, z] in N⋅m
- magnitude: Torque magnitude in N⋅m
Tips for LLMs:
- Torque direction follows right-hand rule (perpendicular to force and position)
- Maximum torque when force is perpendicular to position vector
- Zero torque when force is parallel to position vector
- Use for: wrenches, door hinges, motors, gears
Example - Opening a door:
result = await calculate_torque(
force_x=50.0, # Push perpendicular to door
force_y=0.0,
force_z=0.0,
position_x=0.0,
position_y=0.0,
position_z=0.8 # 0.8m from hinge
)
# Torque = 40 N⋅m
| Name | Required | Description | Default |
|---|---|---|---|
| force_x | Yes | ||
| force_y | Yes | ||
| force_z | Yes | ||
| position_x | Yes | ||
| position_y | Yes | ||
| position_z | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explains the math, return values (torque vector and magnitude), and physical conditions (right-hand rule, max/zero torque). It does not mention side effects or permissions, but for a pure calculation tool this is sufficient.
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 well-structured with a formula, explanation, Args, Returns, Tips, and Example. It is slightly verbose (e.g., listing all vector components in Args), but the organization is clear and front-loaded.
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 simplicity of the tool (vector cross product), the description covers the calculation, parameter meanings, return format, and usage context comprehensively. No gaps are apparent.
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 has 0% description coverage, but the description provides full parameter explanations with units (Newtons, meters) and implicit meaning (force components, position vector components). This compensates completely.
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 'Calculate torque from force and position: τ = r × F (cross product).' It specifies the exact operation and distinguishes it from sibling tools by focusing on torque specifically.
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 includes tips and an example for common use (opening a door) but does not explicitly exclude alternative tools for related concepts like angular momentum or rotational inertia.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate Venturi effect (flow through constriction).
Uses continuity equation and Bernoulli's principle.
Args:
inlet_diameter: Inlet diameter in meters
throat_diameter: Throat (constriction) diameter in meters
inlet_velocity: Inlet velocity in m/s
fluid_density: Fluid density in kg/m³
Returns:
Dict containing:
- throat_velocity: Velocity at throat in m/s
- pressure_drop: Pressure drop from inlet to throat in Pascals
- flow_rate: Volumetric flow rate in m³/s
Example - Venturi meter:
result = await calculate_venturi_effect(
inlet_diameter=0.1, # 10 cm
throat_diameter=0.05, # 5 cm
inlet_velocity=2.0, # m/s
fluid_density=1000 # water
)
# throat_velocity = 8 m/s (4x area reduction)
| Name | Required | Description | Default |
|---|---|---|---|
| inlet_diameter | Yes | ||
| throat_diameter | Yes | ||
| inlet_velocity | Yes | ||
| fluid_density | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description adequately describes the mathematical computation and expected inputs/outputs. For a pure calculation tool, this covers behavioral traits sufficiently. It does not disclose any side effects because none exist.
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 well-structured with sections for purpose, parameter list, return values, and an example. Every sentence adds value; no fluff.
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 output schema, the description fully specifies the return dictionary with keys, units, and an example. All necessary information for a physics calculation tool is present.
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%, but the description includes detailed docstrings for each parameter with units (e.g., 'inlet diameter in meters'). This adds significant meaning beyond the bare schema, enabling correct usage.
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 it calculates the Venturi effect using continuity equation and Bernoulli's principle. The specific verb 'calculate' and resource 'Venturi effect' are precise, and the tool is distinct from sibling physics calculation 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 mentions 'flow through constriction' and provides an example, but does not explicitly guide when to use this tool over closely related siblings like 'calculate_bernoulli'. No 'when not to use' or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate work done by a force and optionally power.
Work is the dot product: W = F · d
Power (if time given): P = W / t
Args:
force: Force vector [x, y, z] in Newtons (or JSON string)
displacement: Displacement vector [x, y, z] in meters (or JSON string)
time: Time taken in seconds (optional, for power calculation)
Returns:
Dict containing:
- work: Work done in Joules
- power: Power in Watts (if time provided, else None)
Example - Pushing box 5m with 100N force:
result = await calculate_work_power(
force=[100, 0, 0],
displacement=[5, 0, 0],
time=10.0
)
# Work = 500 J, Power = 50 W
| Name | Required | Description | Default |
|---|---|---|---|
| force | Yes | ||
| displacement | Yes | ||
| time | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It fully discloses the behavior: vector inputs as JSON or arrays, optional time, return structure with work and possibly power (None if no time). No contradictions.
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 well-structured with sections for Args, Returns, and an Example. It is informative but not overly verbose. Minor redundancy (repeating formulas in text and example) but overall efficient.
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 output schema, the description fully explains return values (work and power). It covers all parameters, usage, and provides a concrete example. With many sibling tools, this is self-contained and 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 has 0% description coverage, so description adds crucial meaning: force and displacement are 3D vectors in specific units (Newtons, meters) and can be arrays or JSON strings. Time is in seconds. This goes far 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?
The description clearly states 'Calculate work done by a force and optionally power.' It provides the specific formulas and distinguishes itself from many sibling physics tools by focusing on work and power computation.
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 power calculation is optional and requires a time parameter. It includes an example. However, it does not explicitly state when not to use this tool or mention alternatives, but given the sibling set, the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify conservation of angular momentum.
Checks whether total angular momentum is conserved. Angular momentum
is conserved when no external torques act on the system.
Args:
initial_angular_momentum: Initial L [x, y, z] in kg⋅m²/s (or JSON string)
final_angular_momentum: Final L [x, y, z] in kg⋅m²/s (or JSON string)
tolerance: Tolerance (fraction, default 0.01 = 1%)
Returns:
Dict containing:
- initial_L_magnitude: Initial |L| in kg⋅m²/s
- final_L_magnitude: Final |L| in kg⋅m²/s
- L_difference: Difference [x, y, z]
- L_difference_magnitude: |ΔL|
- L_difference_percent: % difference
- is_conserved: Whether L is conserved within tolerance
Tips for LLMs:
- Conserved when no external torques (isolated rotation)
- Ice skater spinning: pull arms in → I decreases → ω increases (L constant)
- Gyroscope: resists changes to L direction
- Planets orbiting: L conserved → elliptical orbits
Example - Figure skater:
# Arms extended → Arms pulled in
result = await check_angular_momentum_conservation(
initial_angular_momentum=[0, 15, 0], # kg⋅m²/s
final_angular_momentum=[0, 15.05, 0],
tolerance=0.01
)
| Name | Required | Description | Default |
|---|---|---|---|
| initial_angular_momentum | Yes | ||
| final_angular_momentum | Yes | ||
| tolerance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses the tool's behavior: it performs a conservation check computation, returning a dictionary of results. It implies no side effects, which aligns with the tool's nature.
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 well-structured with sections (Args, Returns, Tips, Example) and front-loads the core purpose. However, the tips and example add length; minor trimming could improve conciseness.
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 fully covers inputs, outputs (all fields of return dict), and provides educational context about angular momentum conservation, making it complete for an agent to use correctly without an output schema.
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 description adds extensive meaning beyond the schema: specifies units (kg⋅m²/s), format (JSON string), and default tolerance (0.01 = 1%), plus an example. The schema has 0% coverage, so the description fully compensates.
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 verb 'verify' and the resource 'conservation of angular momentum', and the purpose is distinct from sibling tools like check_momentum_conservation (linear) and check_energy_conservation.
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 provides explicit when-to-use context (no external torques), examples (ice skater, gyroscope, planets), and a full example with input values, guiding the agent on proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if two moving spherical objects will collide.
Predicts whether two moving spheres will collide within a time window,
and if so, calculates when and where the collision occurs. Uses analytic
relative motion to find exact collision time (if any).
Args:
body1_position: Position of first object [x, y, z] in meters
body1_velocity: Velocity of first object [x, y, z] in m/s
body1_radius: Radius of first object in meters (must be positive)
body2_position: Position of second object [x, y, z] in meters
body2_velocity: Velocity of second object [x, y, z] in m/s
body2_radius: Radius of second object in meters (must be positive)
max_time: Maximum time to check in seconds. Default 10.0.
Returns:
CollisionCheckResponse containing:
- will_collide: True if collision will occur
- collision_time: Time until collision in seconds (if collision occurs)
- collision_point: Approximate collision location [x, y, z] (if collision occurs)
- impact_speed: Relative velocity at impact in m/s (if collision occurs)
- closest_approach_distance: Minimum distance between objects
- closest_approach_time: Time of closest approach
Tips for LLMs:
- Objects are modeled as spheres (point masses with radius)
- Collision detection is exact for constant velocity motion
- Returns earliest collision time if multiple intersections
- If no collision, check closest_approach_distance to see how close they get
- Use for: asteroid tracking, car crash prediction, sports ball interactions
- For complex shapes or forces, use create_simulation instead
Example:
# Check if two cars will collide
result = await check_collision(
body1_position=[0.0, 0.0, 0.0],
body1_velocity=[10.0, 0.0, 0.0],
body1_radius=2.0,
body2_position=[50.0, 1.0, 0.0],
body2_velocity=[-8.0, 0.0, 0.0],
body2_radius=2.0
)
if result.will_collide:
print(f"Collision in {result.collision_time:.2f} seconds at {result.impact_speed:.1f} m/s")
| Name | Required | Description | Default |
|---|---|---|---|
| body1_position | Yes | ||
| body1_velocity | Yes | ||
| body1_radius | Yes | ||
| body2_position | Yes | ||
| body2_velocity | Yes | ||
| body2_radius | Yes | ||
| max_time | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It explains the underlying model (spheres with constant velocity), the analytic method, and the return values. However, it does not discuss edge cases or error handling, which would make it fully transparent.
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 well-structured with sections (Args, Returns, Tips, Example) and is appropriately front-loaded. It is somewhat lengthy but justified by the tool's complexity. Minor redundancy in the example could 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?
The description is complete: it explains all parameters, return values, assumptions, and provides a usage example. It covers the tool's behavior thoroughly given the absence of an output schema.
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?
Despite 0% schema coverage, the description thoroughly explains each parameter in the Args section, adding meaning beyond the schema's type definitions (e.g., units, positivity constraints). This compensates for the lack of schema descriptions.
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's purpose: "Check if two moving spherical objects will collide." It specifies the exact function and distinguishes itself from siblings by mentioning an alternative tool for complex shapes or forces.
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 provides explicit usage guidance, including when to use this tool (e.g., asteroid tracking, car crash prediction) and when to use an alternative: "For complex shapes or forces, use create_simulation instead." It also includes an example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify conservation of energy in a physics process.
Checks whether total mechanical energy is conserved (or correctly dissipated).
Useful for validating simulation results and understanding energy transfer.
Args:
initial_kinetic_energy: Initial KE in Joules
final_kinetic_energy: Final KE in Joules
initial_potential_energy: Initial PE in Joules
final_potential_energy: Final PE in Joules
expected_energy_loss: Expected energy loss (from friction, etc.) in Joules
tolerance: Tolerance for conservation check (fraction, default 0.01 = 1%)
Returns:
Dict containing:
- initial_total_energy: Initial total energy in Joules
- final_total_energy: Final total energy in Joules
- energy_difference: Energy difference in Joules
- energy_difference_percent: % difference
- is_conserved: Whether energy is conserved within tolerance
- expected_loss: Expected energy loss in Joules
- actual_loss: Actual energy loss in Joules
Tips for LLMs:
- In isolated systems, total energy is conserved
- With friction/damping, expect energy loss
- Small numerical errors are normal in simulations
- Use to validate simulation accuracy
Example - Bouncing ball with energy loss:
result = await check_energy_conservation(
initial_kinetic_energy=0,
final_kinetic_energy=0,
initial_potential_energy=10, # J (at 1m height)
final_potential_energy=6.4, # J (bounced to 0.64m)
expected_energy_loss=3.6, # 36% loss (e=0.8)
tolerance=0.01
)
| Name | Required | Description | Default |
|---|---|---|---|
| initial_kinetic_energy | Yes | ||
| final_kinetic_energy | Yes | ||
| initial_potential_energy | Yes | ||
| final_potential_energy | Yes | ||
| expected_energy_loss | No | ||
| tolerance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully explains the tool's behavior: checks conservation, returns detailed results. No side effects mentioned, but it's a read-only verification.
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?
Well-structured with sections, but slightly long due to example and tips. Front-loads purpose efficiently.
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?
Comprehensive with return value description and example. Lacks error handling info, but output schema not provided.
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?
Each parameter is described with units and purpose in the Args section. Schema coverage is 0%, so description carries full burden and does it well.
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?
Clearly states it verifies energy conservation in physics processes. Differentiates from siblings like check_momentum_conservation by focusing on energy.
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 tips for when to use (isolated systems, friction, numerical errors) and example usage. Does not explicitly mention when not to use or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check complete static equilibrium: ΣF = 0 and Στ = 0.
For static equilibrium, both force and torque must be balanced.
Args:
forces: List of force vectors [[x,y,z], ...] in N (or JSON string)
force_positions: Positions where forces applied [[x,y,z], ...] (or JSON string)
pivot_point: Pivot point for torque calculation [x,y,z] (default [0,0,0])
tolerance: Tolerance for equilibrium check (default 0.01)
Returns:
Dict containing:
- force_balanced: Whether ΣF = 0
- torque_balanced: Whether Στ = 0
- in_equilibrium: Whether system is in static equilibrium
- net_force: Net force [x, y, z] in N
- net_torque: Net torque [x, y, z] in N⋅m
Example - Beam with two forces:
result = await check_equilibrium(
forces=[[0, 100, 0], [0, -100, 0]],
force_positions=[[1, 0, 0], [2, 0, 0]]
)
| Name | Required | Description | Default |
|---|---|---|---|
| forces | Yes | ||
| force_positions | Yes | ||
| pivot_point | No | ||
| tolerance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description thoroughly explains the equilibrium conditions and return values. It adds context about input formats and defaults, making the tool's behavior clear.
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 well-structured with a purpose statement, Args/Returns sections, and an example. It is efficient and front-loaded.
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 input, output, and an example sufficiently for a simple calculation tool. It could add notes on error handling or edge cases, but it's largely 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 0%, but the description adds detailed meaning: forces as vector lists with units, positions as coordinates, pivot default, tolerance default, and a concrete example. This fully compensates for the schema gap.
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 it checks static equilibrium (ΣF=0 and Στ=0), distinguishing it from sibling tools like 'check_force_balance' and 'check_torque_balance' which check only one condition.
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 usage for full equilibrium checks, and the presence of sibling tools for individual balances provides context. However, it lacks explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if forces are in equilibrium: ΣF = 0.
Verifies whether a system of forces is balanced (net force = 0).
Essential for statics problems and structural analysis.
Args:
forces: List of force vectors [[x,y,z], ...] in Newtons (or JSON string)
tolerance: Tolerance for equilibrium check (fraction, default 0.01)
Returns:
Dict containing:
- net_force: Net force vector [x, y, z] in Newtons
- net_force_magnitude: Net force magnitude in Newtons
- is_balanced: Whether forces are in equilibrium
- individual_magnitudes: Magnitude of each force
Example - Bridge support forces:
result = await check_force_balance(
forces=[[0, 1000, 0], [0, 500, 0], [0, -1500, 0]],
tolerance=0.01
)
# is_balanced = True if net force ≈ 0
| Name | Required | Description | Default |
|---|---|---|---|
| forces | Yes | ||
| tolerance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It confirms a read-only equilibrium check but does not explicitly state that no state is modified, nor does it discuss error handling or limitations.
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 well-structured with a clear heading, explanation, args, returns, and an example. It is somewhat lengthy but each sentence adds value. Could be slightly tighter.
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 explains the tool's purpose, inputs, and outputs in detail, including an example. However, it does not mention integration with simulations or error behavior, and no output schema is provided.
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 fully compensates by explaining that 'forces' is a list of vectors or JSON string in Newtons and 'tolerance' is a fraction with default 0.01. This adds essential meaning beyond the schema's bare types.
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 'Check if forces are in equilibrium: ΣF = 0' and provides a specific verb-resource pair. It distinguishes from siblings like check_torque_balance by focusing solely on force equilibrium, and the example reinforces its purpose.
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 'Essential for statics problems and structural analysis,' giving context, but does not explicitly state when not to use this tool or compare it to alternatives like check_equilibrium or check_torque_balance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify conservation of momentum.
Checks whether total momentum is conserved in a collision or interaction.
Momentum should be conserved in isolated systems (no external forces).
Args:
initial_momentum: Initial total momentum [x, y, z] in kg⋅m/s (or JSON string)
final_momentum: Final total momentum [x, y, z] in kg⋅m/s (or JSON string)
tolerance: Tolerance for conservation check (fraction, default 0.01 = 1%)
Returns:
Dict containing:
- initial_momentum_magnitude: Initial |p| in kg⋅m/s
- final_momentum_magnitude: Final |p| in kg⋅m/s
- momentum_difference: Difference [x, y, z]
- momentum_difference_magnitude: |Δp|
- momentum_difference_percent: % difference
- is_conserved: Whether momentum is conserved within tolerance
Tips for LLMs:
- Momentum is ALWAYS conserved in isolated systems
- Vector quantity - direction matters
- Use to validate collision calculations
- External forces (friction, etc.) can change total momentum
Example - Collision verification:
result = await check_momentum_conservation(
initial_momentum=[3000, 0, 0], # kg⋅m/s
final_momentum=[2995, 5, 0], # slightly off
tolerance=0.01
)
| Name | Required | Description | Default |
|---|---|---|---|
| initial_momentum | Yes | ||
| final_momentum | Yes | ||
| tolerance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully covers behavior: vector nature, direction importance, external forces impact, and example. Could briefly mention that it is a pure computation without side effects, but overall informative.
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?
Well-structured with Args, Returns, Tips, and Example sections. Slightly verbose in tips (e.g., 'Momentum is ALWAYS conserved...') but overall efficient and front-loaded with purpose.
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, but description explains all return fields. Covers physics context, parameter types, tolerance, and example usage. Complete for an LLM to use effectively.
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 has 0% description coverage, but the description provides detailed parameter explanations: initial_momentum and final_momentum as [x,y,z] vectors in kg·m/s, tolerance as fraction. Also fully explains the return dict, exceeding what schema alone offers.
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 it verifies conservation of momentum and distinguishes from siblings like check_energy_conservation and check_angular_momentum_conservation by explicitly focusing on momentum conservation.
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?
Indicates it is used for isolated systems and collision calculations, with tips about external forces. Does not explicitly mention when not to use or alternatives, but context from sibling tools and physics knowledge fills the gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if torques are in equilibrium: Στ = 0.
Verifies whether a system of torques is balanced (net torque = 0).
Essential for rotational equilibrium and lever problems.
Args:
torques: List of torque vectors [[x,y,z], ...] in N⋅m (or JSON string)
tolerance: Tolerance for equilibrium check (fraction, default 0.01)
Returns:
Dict containing:
- net_torque: Net torque vector [x, y, z] in N⋅m
- net_torque_magnitude: Net torque magnitude in N⋅m
- is_balanced: Whether torques are in equilibrium
- individual_magnitudes: Magnitude of each torque
Example - Seesaw balance:
result = await check_torque_balance(
torques=[[0, 0, 100], [0, 0, -100]],
tolerance=0.01
)
| Name | Required | Description | Default |
|---|---|---|---|
| torques | Yes | ||
| tolerance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the tool's behavior (checking equilibrium, returning net torque and balance status) without annotations. While it doesn't explicitly state read-only or lack of side effects, the context implies a pure computation. Could be improved by noting it does not modify state.
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?
Well-structured with sections for Args, Returns, and Example, but the description is somewhat lengthy. Every sentence serves a purpose, but it could be slightly more concise while retaining clarity.
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 annotations and no output schema, the description provides complete information: purpose, input parameters, return value structure, and a concrete example. No gaps are evident.
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?
Input schema has 0% description coverage, so the description fully explains the two parameters: torques (list of vectors or JSON string) and tolerance (fraction with default 0.01). This adds significant value 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?
Clearly states the tool checks torque equilibrium (Στ = 0), specifying the verb 'check' and the resource 'torques equilibrium'. Distinguishes from sibling tools like check_force_balance and check_equilibrium by focusing specifically on torques.
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 context for usage ('Essential for rotational equilibrium and lever problems') and an example (seesaw balance), but does not explicitly describe when not to use or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a value from one unit to another.
Supports 62 unit types across 16 categories:
- Velocity: m/s, km/h, mph, ft/s, knots
- Distance: m, km, mi, ft, yd, in
- Mass: kg, g, lb, oz
- Force: N, kN, lbf
- Energy: J, kJ, cal, BTU, kWh
- Power: W, kW, hp
- Temperature: K, C, F
- Angle: rad, deg
- Pressure: Pa, kPa, bar, psi, atm
- Area: m², km², ft², acre
- Volume: m³, L, gal, ft³
- Time: s, min, hr, day
- Acceleration: m/s², g, ft/s²
- Torque: N·m, lb·ft, lb·in
- Frequency: Hz, kHz, MHz, GHz
- Data Size: B, KB, MB, GB
Enables natural language queries like:
- "Convert 60 mph to m/s"
- "How fast is 100 km/h in mph?"
- "Convert 10 kg to pounds"
Args:
value: The numeric value to convert
from_unit: Source unit (e.g., 'mph', 'kg', 'J')
to_unit: Target unit (e.g., 'm/s', 'lb', 'kWh')
Returns:
Dictionary with:
- original_value: Input value
- original_unit: Input unit
- converted_value: Result value
- converted_unit: Result unit
- formatted: Human-readable string
Examples:
>>> convert_unit(100, 'm/s', 'mph')
{
"original_value": 100,
"original_unit": "m/s",
"converted_value": 223.694,
"converted_unit": "mph",
"formatted": "100 m/s = 223.694 mph"
}
>>> convert_unit(60, 'mph', 'km/h')
{
"original_value": 60,
"original_unit": "mph",
"converted_value": 96.56064,
"converted_unit": "km/h",
"formatted": "60 mph = 96.56 km/h"
}
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | ||
| from_unit | Yes | ||
| to_unit | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses supported units, parameter purpose, return format, and examples. It does not cover error handling or idempotency, but overall is informative.
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 well-structured with bullet points, args/returns, and examples. It is slightly lengthy but every sentence adds 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?
Given no output schema, the description includes return fields, examples, and supported units, making it complete for a unit conversion 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?
Input schema has 0% description coverage; the description lists parameter names, types, and example values, adding meaning that the schema lacks.
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 'Convert a value from one unit to another', lists supported units/categories, and distinguishes itself from sibling physics calculation 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 implies usage for any unit conversion but does not explicitly specify when to use this tool over alternatives like list_unit_conversions, nor does it provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new physics simulation using Rapier engine.
Initializes a new rigid-body physics world with configurable gravity and
timestep. Returns a simulation ID used for all subsequent operations.
Args:
gravity_x: X component of gravity vector (m/s²). Default 0.0
gravity_y: Y component of gravity vector (m/s²). Default -9.81 (Earth down)
gravity_z: Z component of gravity vector (m/s²). Default 0.0
dimensions: 2 or 3 for 2D/3D simulation. Default 3.
dt: Simulation timestep in seconds. Default 0.016 (60 FPS).
Smaller = more accurate but slower, larger = faster but less stable
integrator: Integration method. Options: "euler", "verlet", "rk4". Default "verlet".
Returns:
SimulationCreateResponse containing:
- sim_id: Unique simulation identifier (use for all other sim calls)
- config: Echo of the configuration used
Tips for LLMs:
- Keep simulation IDs in memory for the conversation session
- Default gravity is Earth standard (9.81 m/s² down = -Y direction)
- dt=0.016 ≈ 60 FPS, dt=0.008 ≈ 120 FPS (higher accuracy)
- "verlet" integrator is good default (stable, energy-conserving)
- Remember to destroy_simulation when done to free resources
Requires:
- Rapier provider must be configured (see config.py)
- Rapier service must be running (see RAPIER_SERVICE.md)
Example:
# Create simulation with Earth gravity
sim = await create_simulation(
gravity_y=-9.81,
dt=0.016
)
# Use sim.sim_id for add_body, step_simulation, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| gravity_x | No | ||
| gravity_y | No | ||
| gravity_z | No | ||
| dimensions | No | ||
| dt | No | ||
| integrator | No | verlet |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that it creates a new physics world and returns a simulation ID for subsequent operations. It mentions resource freeing and default gravity direction. It could improve by noting that calling it multiple times creates independent simulations, but overall it is transparent about effects and prerequisites.
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 well-structured with sections for Args, Returns, Tips, Requirements, and Example. It is front-loaded with the core purpose. While slightly verbose, every sentence adds value, and the structure aids readability. A minor reduction in redundancy (e.g., tips and args overlap slightly) would earn a 5.
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?
Despite no output schema, the description details the return format (sim_id and config) and provides an example. It covers requirements, practical tips (ID memory, integrator choice), and cleanup. Given the tool's complexity (6 parameters, many siblings), the description is complete and leaves no critical 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?
The input schema has 0% description coverage, so the description carries the full burden. It thoroughly explains each parameter with units, defaults, and practical meaning (e.g., dt accuracy trade-off, gravity components, integrator options). This goes well beyond the schema and helps the agent choose correct values.
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 creates a new physics simulation using the Rapier engine, initializing a rigid-body world with configurable gravity and timestep. It distinguishes itself from sibling tools (e.g., add_body, step_simulation) by being the entry point, and the example and tips reinforce its role.
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 provides clear context on when to use the tool: before other simulation operations, and it warns to destroy when done. Requirements (Rapier provider configured, service running) and tips (keep IDs) guide usage. However, it does not explicitly state when not to use it or compare to alternatives, though among siblings it is unique.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Destroy a simulation and free resources.
Cleanup when done with a simulation. Important for long-running servers
to avoid memory leaks.
Args:
sim_id: Simulation ID to destroy
Returns:
Success message
Tips for LLMs:
- Always destroy simulations when conversation ends or changes topic
- Rapier service keeps simulations in memory until explicitly destroyed
- Good practice: destroy after recording trajectory or final state
Example:
await destroy_simulation(sim_id)
| Name | Required | Description | Default |
|---|---|---|---|
| sim_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It discloses that the tool frees memory and that simulations persist until destroyed, which is important for understanding side effects and server resource management.
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?
Well-structured with sections (Description, Args, Returns, Tips, Example). Each sentence adds value, though slightly longer than strictly necessary. Tips for LLMs are helpful.
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?
Covers purpose, parameter, return value, usage guidelines, and behavioral impact. No output schema needed; the description adequately explains what the tool does and what to expect.
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% (no descriptions in schema), but the description adds 'sim_id: Simulation ID to destroy' and includes an example, providing clear meaning beyond the raw type.
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 'Destroy a simulation and free resources' with a specific verb and resource. It distinguishes itself from sibling tools like create_simulation and step_simulation by focusing on cleanup.
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 'Cleanup when done with a simulation' and 'Always destroy simulations when conversation ends or changes topic.' Provides clear when-to-use guidance and implies not to use while simulation is still needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fit polynomial to trajectory data.
Useful for smoothing noisy data or finding trajectory equations.
Default fit_type="quadratic" fits parabolic trajectory (constant acceleration).
Args:
times: Time values in seconds (or JSON string)
positions: Position vectors [[x,y,z], ...] in meters (or JSON string)
fit_type: Polynomial type - "linear", "quadratic", or "cubic" (default "quadratic")
Returns:
Dict containing:
- coefficients_x: Polynomial coefficients for x(t)
- coefficients_y: Polynomial coefficients for y(t)
- coefficients_z: Polynomial coefficients for z(t)
- r_squared: R² goodness of fit (0-1)
- predicted_positions: Fitted positions [[x,y,z], ...]
Example - Projectile motion:
result = await fit_trajectory(
times=[0, 1, 2, 3],
positions=[[0,0,0], [10,15,0], [20,20,0], [30,15,0]],
fit_type="quadratic"
)
# Fits x(t) = c0 + c1*t + c2*t²
| Name | Required | Description | Default |
|---|---|---|---|
| times | Yes | ||
| positions | Yes | ||
| fit_type | No | quadratic |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It describes outputs and example but does not disclose any side effects, destructive actions, or limitations. However, the tool appears to be a pure computation function, so the lack of behavioral warnings is acceptable.
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 well-structured with sections for description, args, returns, and example. Every sentence adds value, and it is appropriately sized without redundancy.
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 is complete: it explains what the tool does, all parameters, return values, and provides a concrete example. An AI agent has enough information to use it 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 has 0% description coverage (all string types), but the description explains each parameter: times in seconds, positions as vector arrays, fit_type with enumerated options. This adds significant meaning beyond the raw 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 clearly states 'Fit polynomial to trajectory data,' which is a specific verb+resource. It distinguishes from sibling tools like 'calculate_projectile_motion' by focusing on fitting curves to arbitrary trajectory data, not just projectile calculations.
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?
Mentions it's 'useful for smoothing noisy data or finding trajectory equations,' providing clear usage context. However, it does not explicitly state when not to use this tool or compare to alternative tools among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate motion graph data (position, velocity, acceleration vs time).
Calculates velocity and acceleration from position data and extracts
the specified component for graphing.
Args:
times: Time values in seconds (or JSON string)
positions: Position vectors [[x,y,z], ...] in meters (or JSON string)
component: Which component to analyze - "x", "y", "z", or "magnitude" (default)
Returns:
Dict containing:
- times: Time values
- positions: Position values (selected component)
- velocities: Velocity values (selected component)
- accelerations: Acceleration values (selected component)
- max_velocity: Maximum velocity magnitude
- max_acceleration: Maximum acceleration magnitude
- component: Which component was analyzed
Example:
result = await generate_motion_graph(
times=[0, 1, 2, 3],
positions=[[0,0,0], [5,0,0], [20,0,0], [45,0,0]],
component="x"
)
# Automatically calculates v and a
| Name | Required | Description | Default |
|---|---|---|---|
| times | Yes | ||
| positions | Yes | ||
| component | No | magnitude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses that it calculates velocity and acceleration from position data, extracts a component, and returns multiple derived quantities. However, it does not mention error handling or data validation.
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 well-structured with sections for Args, Returns, and Example, and the first sentence states the purpose. It is slightly lengthy but each sentence adds value. Could be trimmed slightly.
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 complexity and lack of output schema, the description covers input parameters, return structure with keys, and includes an example. It lacks units for velocities/accelerations but is otherwise 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 description coverage is 0%, but the description explains each parameter: times as seconds or JSON string, positions as vector arrays in meters, component with default 'magnitude' and enum-like options. This adds substantial meaning 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?
The description clearly states it 'Generates motion graph data (position, velocity, acceleration vs time)' and distinguishes from siblings like calculate_instantaneous_velocity by producing multiple series. The verb 'generate' and resource 'motion graph' are specific.
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 usage by showing automatic calculation of v and a, but it does not explicitly state when to use this tool over individual calculation tools, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all supported unit conversions.
Returns a dictionary mapping category names to lists of supported units.
Returns:
Dictionary with supported unit categories:
- velocity: Speed units
- distance: Length units
- mass: Weight units
- force: Force units
- energy: Energy units
- power: Power units
- temperature: Temperature scales
- angle: Angular units
- pressure: Pressure units
- area: Area units
- volume: Volume units
Example:
>>> list_unit_conversions()
{
"velocity": ["m/s", "km/h", "mph", "ft/s", "knots"],
"distance": ["m", "km", "mi", "ft", "yd", "in"],
"mass": ["kg", "g", "lb", "oz"],
...
}
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses that it returns a dictionary mapping categories to unit lists. No side effects or destructive behavior is mentioned, which is acceptable for a read-only listing 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?
Description is concise, well-structured with bullet points and an example. Every sentence earns its place, and the key information is front-loaded.
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 zero parameters and no output schema, the description completely explains the return format and content with an example. No gaps remain.
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?
No parameters in schema; baseline score of 4 applies. Description adds value by detailing the return structure and example, which compensates for lack of parameters.
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?
Description clearly states 'List all supported unit conversions' with a specific verb and resource. It distinguishes itself from sibling tool 'convert_unit' by providing the list of available units.
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?
Description implies usage as a precursor to conversion, but does not explicitly state when to use it or when not to use it. It is clear that it serves as a reference for available units.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record the trajectory of a specific body over time.
Steps the simulation and records position/orientation/velocity at each
timestep for one body. Perfect for generating animation data for R3F.
Args:
sim_id: Simulation ID
body_id: ID of the body to track
steps: Number of timesteps to record
dt: Optional timestep override. If None, uses config default.
Returns:
TrajectoryResponse containing:
- body_id: Tracked body identifier
- frames: List of trajectory frames with time, position, orientation, velocity
- total_time: Total simulated time in seconds
- num_frames: Number of frames recorded
Tips for LLMs:
- Each frame has: time, position [x,y,z], orientation [x,y,z,w], velocity [x,y,z]
- Frames are evenly spaced in time (every dt seconds)
- Output is R3F-compatible: use position/orientation directly in Three.js
- For 60 FPS video: record at dt=1/60 ≈ 0.0167
- Typical recording: 100-1000 frames (1.6-16 seconds at 60 FPS)
Example:
# Record 5 seconds of a falling ball
traj = await record_trajectory(
sim_id=sim_id,
body_id="ball",
steps=300 # 300 × 0.016 ≈ 5 seconds
)
# Use traj.frames in React Three Fiber for animation
| Name | Required | Description | Default |
|---|---|---|---|
| sim_id | Yes | ||
| body_id | Yes | ||
| steps | Yes | ||
| dt | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the simulation is stepped, records per timestep, and describes return frame structure. Without annotations, it carries the full burden and covers key behaviors, though could mention simulation state mutability more explicitly.
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?
Well-organized with sections for description, args, returns, tips, and example. Every sentence adds value; no redundancy.
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?
Covers return format comprehensively given no output schema. Mentions prerequisites indirectly (sim_id, body_id) but does not address error conditions or missing bodies.
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?
Fully explains all 4 parameters including purpose, optionality (dt), and typical values. Compensates for 0% schema coverage with clear descriptions and an example.
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?
Clearly states verb (record), resource (trajectory of a specific body), and scope (over time). Differentiates from siblings like record_trajectory_with_events by focusing on pure trajectory recording without events.
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 practical context: generating animation data for R3F, tips for FPS, and example usage. However, does not explicitly mention when not to use or compare to sibling alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record trajectory and automatically detect collision and bounce events.
This is an enhanced version of record_trajectory that analyzes the motion
and detects important events like bounces and collisions. Perfect for
answering questions like "how many times did the ball bounce?"
Args:
sim_id: Simulation ID
body_id: Body to track
steps: Number of simulation steps to record
dt: Optional custom timestep (overrides simulation default)
detect_bounces: Whether to detect bounce events (default True)
bounce_height_threshold: Maximum height to consider as "on ground" in meters (default 0.01)
Returns:
TrajectoryWithEventsResponse containing:
- frames: Trajectory frames (positions, velocities)
- bounces: Detected bounce events with energy loss
- contact_events: Contact/collision events (future)
Tips for LLMs:
- Use this instead of record_trajectory when you need event detection
- Bounces are detected from velocity reversals near the ground
- Each bounce includes: time, position, speeds before/after, energy loss
- Use `trajectory.bounces` to count or analyze bounces
- Adjust bounce_height_threshold for different ground shapes
Example:
# Record ball bouncing and count bounces
traj = await record_trajectory_with_events(
sim_id=sim_id,
body_id="ball",
steps=600,
detect_bounces=True,
bounce_height_threshold=0.01 # 1cm threshold
)
print(f"Detected {len(traj.bounces)} bounces")
for bounce in traj.bounces:
print(f"Bounce #{bounce.bounce_number} at t={bounce.time:.2f}s")
| Name | Required | Description | Default |
|---|---|---|---|
| sim_id | Yes | ||
| body_id | Yes | ||
| steps | Yes | ||
| dt | No | ||
| detect_bounces | No | ||
| bounce_height_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description explains bounce detection via velocity reversals near ground, the role of bounce_height_threshold, and the returned fields (bounces with time/position/speeds/energy loss). It does not cover potential side effects or performance considerations, but adequately discloses key behavioral traits.
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?
Well-structured with clear sections: short intro, formatted Args/Returns, actionable Tips, and a concise Example. Every sentence adds value; no fluff. Length is appropriate for the tool's complexity.
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?
Covers purpose, parameters, return structure (frames, bounces, contact_events), and typical use case with an example. However, it lacks details on the output fields beyond bounces, and does not mention how contact_events will be structured or if any side effects occur on the simulation. Still, it is largely complete for a simulation tool with no output schema.
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?
Input schema provides only types and defaults (0% description coverage). The description fully compensates with detailed Args documentation explaining each parameter's purpose, default behavior, and practical usage (e.g., dt override, bounce_height_threshold meaning). The example shows concrete parameter values.
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?
Clearly states the tool records trajectory and detects collision/bounce events, enhancing the sibling record_trajectory. The description explicitly differentiates by labeling it an 'enhanced version' and listing detected event types.
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 explicit guidance: 'Use this instead of record_trajectory when you need event detection.' The Tips section further advises on when to adjust parameters like bounce_height_threshold, and includes an example that demonstrates typical usage for bounce counting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate underwater projectile motion with drag and buoyancy.
Uses numerical integration to simulate motion under:
- Gravity (downward)
- Buoyancy (upward, from displaced fluid)
- Drag (opposes motion)
Args:
initial_velocity: Initial velocity [x, y, z] in m/s
mass: Object mass in kg
volume: Object volume in m³
cross_sectional_area: Cross-sectional area in m²
fluid_density: Fluid density in kg/m³ (default 1000 for water)
fluid_viscosity: Fluid viscosity in Pa·s (default 1.002e-3 for water)
initial_position: Initial position [x, y, z] in m (default [0,0,0])
drag_coefficient: Drag coefficient (default 0.47 for sphere)
gravity: Gravitational acceleration in m/s² (default 9.81)
duration: Simulation duration in seconds (default 10.0)
dt: Time step in seconds (default 0.01)
Returns:
Complete trajectory, final state, max depth, and total distance
Example - Torpedo launch:
result = await simulate_underwater_motion(
initial_velocity=[20, 0, 0], # 20 m/s forward
mass=100, # kg
volume=0.05, # m³
cross_sectional_area=0.03, # m²
fluid_density=1000, # water
drag_coefficient=0.04, # streamlined
duration=30.0
)
| Name | Required | Description | Default |
|---|---|---|---|
| initial_velocity | Yes | ||
| mass | Yes | ||
| volume | Yes | ||
| cross_sectional_area | Yes | ||
| fluid_density | No | ||
| fluid_viscosity | No | ||
| initial_position | No | ||
| drag_coefficient | No | ||
| gravity | No | ||
| duration | No | ||
| dt | No |
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 discloses the numerical integration method, forces considered, and return values (trajectory, final state, max depth, total distance). This is good transparency, though default values are mentioned for some parameters.
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 well-structured with a clear header, bullet-pointed forces, arg list, return statement, and example. Every sentence adds value, and the length is appropriate for the complexity.
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 11 parameters, no output schema, and a complex simulation with many siblings, the description covers parameters, return values, assumptions, and provides an example. It is complete for an agent to use 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?
The input schema has 0% description coverage, but the 'Args' section fully documents each parameter with units, defaults, and explanations. This adds significant meaning beyond the schema. An example further clarifies usage.
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 it simulates underwater projectile motion with drag and buoyancy using numerical integration. This distinguishes it from siblings like calculate_projectile_motion (no drag/buoyancy) and calculate_buoyancy (single force).
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 use for underwater scenarios with realistic physics but does not explicitly state when to use this tool versus alternatives like calculate_projectile_with_drag or calculate_drag_force. More explicit guidance would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Step the simulation forward in time.
Advances the physics simulation by running the integrator for N steps.
Returns the complete state of all bodies after stepping.
Args:
sim_id: Simulation ID
steps: Number of timesteps to simulate. Default 1.
Example: steps=600 with dt=0.016 = 9.6 seconds of simulation
dt: Optional timestep override (seconds). If None, uses config default.
Returns:
SimulationStepResponse containing:
- sim_id: Simulation identifier
- time: Current simulation time in seconds
- bodies: List of all body states with positions, velocities, contacts
Tips for LLMs:
- Each body state includes position, orientation (quaternion), velocities
- contacts array shows active collisions with impulse magnitudes
- For real-time preview: steps=1, call repeatedly
- For final result: steps=1000+, call once
- Large step counts may timeout - limit to ~10,000 steps per call
Example:
# Simulate 10 seconds at 60 FPS
result = await step_simulation(
sim_id=sim_id,
steps=600 # 600 steps × 0.016s = 9.6s
)
for body in result.bodies:
print(f"{body.id}: position={body.position}")
| Name | Required | Description | Default |
|---|---|---|---|
| sim_id | Yes | ||
| steps | No | ||
| dt | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully discloses behavioral traits: it advances simulation, returns complete state, includes timeout limits, and describes the return structure (SimulationStepResponse with bodies, time, etc.).
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 well-structured with a summary, parameter details, return info, tips, and example. Every sentence adds value without redundancy.
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?
Despite no output schema, the description completely covers return types and provides tips for effective use. Given the moderate complexity of a simulation stepping tool, it is fully 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?
The input schema has no descriptions (0% coverage), but the description explains each parameter's meaning: sim_id is the simulation ID, steps is number of timesteps with default and example, dt is optional timestep override. This fully compensates for missing schema descriptions.
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 steps the simulation forward in time using a specific verb ('step') and resource ('simulation'). It distinguishes from sibling tools like 'create_simulation' and 'destroy_simulation'.
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 provides tips on when to use specific step counts ('real-time preview' vs 'final result') and warns about timeouts for large steps. However, it does not explicitly state when not to use this tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Track energy dissipation over a trajectory.
Analyzes how energy changes over time in a recorded trajectory.
Useful for understanding damping, bounces, and energy loss mechanisms.
Args:
trajectory_data: Trajectory data dict with 'frames' field
mass: Object mass in kg
gravity: Gravitational acceleration in m/s² (default 9.81)
reference_height: Reference height for PE in meters (default 0.0)
Returns:
Dict containing:
- frames: Energy data for each frame (time, KE, PE, total E)
- initial_total_energy: Initial total energy in Joules
- final_total_energy: Final total energy in Joules
- total_energy_loss: Total energy dissipated in Joules
- total_energy_loss_percent: % of energy lost
- average_power_dissipated: Average power in Watts (J/s)
Tips for LLMs:
- Use after record_trajectory or record_trajectory_with_events
- Visualize energy vs time to see where energy is lost
- Identifies bounces, friction effects, air resistance
- Power = rate of energy dissipation
Example - Bouncing ball energy analysis:
traj = await record_trajectory_with_events(sim_id, "ball", 600)
result = await track_energy_dissipation(
trajectory_data=traj.model_dump(),
mass=0.5, # 500g ball
gravity=9.81
)
# See how energy decreases with each bounce
| Name | Required | Description | Default |
|---|---|---|---|
| trajectory_data | Yes | ||
| mass | Yes | ||
| gravity | No | ||
| reference_height | No |
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 details the return structure (frames, initial/final energy, loss, power) and explains that it analyzes damping, bounces, and energy loss mechanisms. No side effects or contradictory information.
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 well-structured with clear sections (Description, Args, Returns, Tips, Example). It is somewhat lengthy but every section adds value. The opening sentence is front-loaded and clear.
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 complexity (4 params, nested object, no output schema in structured data), the description is complete. It covers all parameters, return values in detail, includes an example, and provides usage tips. No 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?
Schema coverage is 0%, but the description provides detailed parameter documentation in the Args section: trajectory_data (dict with 'frames' field), mass (kg), gravity (default 9.81), reference_height (default 0). This adds essential 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?
The description states 'Track energy dissipation over a trajectory' and explains it analyzes energy changes over time. This clearly distinguishes it from sibling tools like calculate_kinetic_energy or check_energy_conservation, which focus on static calculations or conservation checks rather than trajectory analysis.
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 recommends using this tool after record_trajectory or record_trajectory_with_events, and provides tips for interpretation (e.g., visualize energy vs time). It does not explicitly state when not to use it, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but there is significant overlap in the calculation category, such as multiple collision tools (elastic_collision, elastic_collision_3d, inelastic_collision_3d) and projectile tools (calculate_projectile_motion, calculate_projectile_with_drag). Descriptions help differentiate, but an agent might struggle to choose between similar tools without careful reading.
Tool names follow a highly consistent snake_case pattern with a clear 'verb_noun' structure, such as 'calculate_force', 'add_rigid_body', and 'check_collision'. There are no deviations in naming conventions across all 62 tools.
With 62 tools, the count is excessive for a single server, making it overwhelming and difficult to navigate. While the domain is broad, the toolset feels bloated with many specialized calculations that could be consolidated, leading to a heavy and confusing interface.
The toolset provides comprehensive coverage of physics simulation and calculations, including simulation management (create_simulation, step_simulation), rigid body dynamics, orbital mechanics, fluid dynamics, and various checks (equilibrium, conservation). There are no obvious gaps for the stated purpose of a physics server.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
AI-callable calculators and engineering models with real formulas. No hallucinated math.
Precision math engine for AI agents. 203 exact methods. Zero hallucination.
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
60+ units, live FX, timezones, and date arithmetic for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/IBM/chuk-mcp-physics'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
