Skip to main content
The Substrate AI Assistant has access to 49 built-in tools organized into 10 categories. When a simulation is running, additional tools registered by the container’s native MCP server are also available — see Simulation MCP Server. These tools let the agent read and edit code, launch and control simulations, capture and analyze visuals, and explore live data — all from a natural language conversation.
Tools marked with Requires Approval will show a diff or confirmation dialog before executing. The assistant cannot bypass this — you always have the final say on file modifications.

​
Code Editing & Exploration

11 tools for navigating and modifying your workspace.
Find files by glob pattern.
ParameterTypeRequiredDescription
patternstringYesGlob pattern (e.g. **/*.rs, src/**/mod.rs)
pathstringNoDirectory to search from (defaults to workspace root)
Returns: List of matching file paths (capped at 1,000 files).Example prompt: “Find all Python files under the scripts directory.”
Search file contents with regex.
ParameterTypeRequiredDescription
patternstringYesRegular expression to match
pathstringNoDirectory or file to search
glob_filterstringNoLimit to files matching this glob
case_insensitiveboolNoIgnore case when matching
Returns: Matching lines with file paths and line numbers (capped at 500 matches).Example prompt: “Search for all usages of spawn_entity in the Rust source.”
Read a file with line numbers.
ParameterTypeRequiredDescription
file_pathstringYesAbsolute path to the file
offsetintNoStarting line number
limitintNoNumber of lines to read (default 256)
Returns: File content with line numbers.Example prompt: “Show me lines 100-200 of dispatch.rs.”
AST-based file reading that chunks at function and class boundaries using Tree-sitter.
ParameterTypeRequiredDescription
file_pathstringYesAbsolute path to the file
token_budgetintNoMaximum tokens to return (default 1,000)
Returns: Semantic chunks of the file (functions, classes, structs) within the token budget.Example prompt: “Read the structure of window_tab.rs — just the function signatures.”
Replace content in a file with 4-level fuzzy matching: exact, CRLF-normalized, whitespace-normalized, and Jaro-Winkler (80% threshold).
ParameterTypeRequiredDescription
file_pathstringYesFile to edit
old_contentstringYesContent to find and replace
new_contentstringYesReplacement content
Returns: Confirmation with diff of the change.
Requires user approval. The edit is shown as a diff for review before applying.
Example prompt: “Change the default altitude from 5 to 10 meters in the takeoff handler.”
Create a new file or overwrite an existing one.
ParameterTypeRequiredDescription
file_pathstringYesPath to create or overwrite
contentstringYesFull file content
Returns: Confirmation of write.
Requires user approval. File content is shown for review before writing.
Example prompt: “Create a new Python script at scripts/waypoint_mission.py with a basic MAVSDK takeoff sequence.”
Create an implementation plan for user review before making changes.
ParameterTypeRequiredDescription
file_pathstringYesWhere to save the plan
contentstringYesPlan content
titlestringYesPlan title
Returns: The rendered plan for approval.Example prompt: “Draft a plan for adding GPS fence support to the flight controller.”
Execute a shell command in the workspace directory.
ParameterTypeRequiredDescription
commandstringYesShell command to run
timeout_msintNoTimeout in milliseconds (default 120,000; max 300,000)
Returns: stdout and stderr output.Example prompt: “Run cargo test for the lapce-rpc crate.”
Generate a PageRank-based symbol ranking across the codebase using Tree-sitter.
ParameterTypeRequiredDescription
pathstringNoRoot directory (defaults to workspace)
token_budgetintNoMax tokens (default 1,000)
file_patternslistNoGlob patterns to include
Returns: Ranked list of the most interconnected symbols (functions, types, traits).Example prompt: “Show me the most important symbols in the simulation module.”
Open a file in the IDE editor panel.
ParameterTypeRequiredDescription
file_pathstringYesAbsolute path to the file
lineintNoLine number to scroll to
Returns: Confirmation that the file was opened.Example prompt: “Open the dispatch.rs file at line 500.”
Spawn a sub-agent with isolated context for parallel work.
ParameterTypeRequiredDescription
descriptionstringYesWhat the sub-agent should accomplish
promptstringYesDetailed instructions
modestringYes"explore", "search", or "edit"
modelstringNoModel override
explore and search modes use Haiku for speed. edit mode uses Sonnet for accuracy.Returns: Sub-agent result.Example prompt: “Search the codebase for how MAVLink heartbeats are parsed.”

​
Simulation Lifecycle

5 tools for launching, monitoring, and querying simulation status.
Launch a PX4 SITL simulation in Docker.
ParameterTypeRequiredDescription
modelstringYesx500, iris, rc_cessna, standard_vtol, or r1_rover
worldstringNodefault, baylands, warehouse, or a Gazebo Fuel name
vehicle_countintNoNumber of vehicles (1—10)
workspace_pathstringNoHost path to mount into the container
Returns: Container name and initial status.Example prompt: “Start a simulation with two x500 drones in the baylands world.”
Find running simulation containers.
ParameterTypeRequiredDescription
modelstringNoFilter by vehicle model
worldstringNoFilter by world name
Returns: List of containers with container_name, readiness_state, and metadata.Example prompt: “Are there any simulations running right now?”
Block until the simulation reaches a target readiness state.
ParameterTypeRequiredDescription
container_namestringYesContainer to wait on
target_statestringNoDefault ReadyToArm
timeout_secsintNoDefault 60, max 120
Readiness states in order: Launching > BridgeConnected > WorldLoaded > Rendering > AutopilotConnected > ReadyToArm > FullyOperational.Returns: Final readiness state when target is reached, or timeout error.Example prompt: “Wait until the simulation is ready to arm.”
MAVLink-level diagnostics: heartbeat status, GPS fix type, EKF convergence, and arm readiness.
ParameterTypeRequiredDescription
container_namestringNoContainer to query (defaults to active)
Runs proxy-local with no UI round-trip for minimal latency.Returns: Structured MAVLink health snapshot.Example prompt: “Why can’t I arm? Show me the readiness details.”
Combined readiness, telemetry, and background task status in a single call.
ParameterTypeRequiredDescription
container_namestringNoContainer to query (defaults to active)
Returns: Readiness state, current telemetry snapshot, and background task summary.Example prompt: “Give me a full status check of the current simulation.”

​
Flight Control

6 tools for MAVLink-based vehicle command. All send MAVLink COMMAND_LONG messages to PX4.
Arm or disarm motors. Sends MAV_CMD_COMPONENT_ARM_DISARM (400).
ParameterTypeRequiredDescription
simulation_idstringYesTarget simulation
armboolYestrue to arm, false to disarm
Example prompt: “Arm the drone.”
Takeoff to a target altitude. Sends MAV_CMD_NAV_TAKEOFF (22).
ParameterTypeRequiredDescription
simulation_idstringYesTarget simulation
altitude_metersfloatNoAltitude in meters, 1—120 (default 5)
Example prompt: “Take off to 15 meters.”
Land at the current position. Sends MAV_CMD_NAV_LAND (21).
ParameterTypeRequiredDescription
simulation_idstringYesTarget simulation
Example prompt: “Land the drone.”
Navigate to a waypoint in ENU coordinates. Sends MAV_CMD_DO_REPOSITION (192).
ParameterTypeRequiredDescription
simulation_idstringYesTarget simulation
xfloatYesEast position (meters)
yfloatYesNorth position (meters)
zfloatYesUp position (meters)
Example prompt: “Fly to position 10, 5, 20.”
Switch PX4 flight mode. Sends MAV_CMD_DO_SET_MODE (176).
ParameterTypeRequiredDescription
simulation_idstringYesTarget simulation
modestringYesFlight mode name
Supported modes: MANUAL, ALTCTL/ALTITUDE, POSCTL/POSITION, OFFBOARD, STABILIZED/STABILIZE, HOLD/LOITER, MISSION, RTL/RETURN, LAND, TAKEOFF, GUIDED (maps to POSCTL).Example prompt: “Switch to position hold mode.”
Return to launch position. Sends MAV_CMD_NAV_RETURN_TO_LAUNCH (20).
ParameterTypeRequiredDescription
simulation_idstringYesTarget simulation
Example prompt: “Return to home.”

​
Simulation Control

3 tools for playback, camera, and in-container command execution.
Control simulation playback.
ParameterTypeRequiredDescription
actionstringYespause, resume, step, reset, or set_speed
framesintNoNumber of frames to advance (for step)
multiplierfloatNoSpeed multiplier (for set_speed)
Example prompt: “Pause the simulation and step forward 10 frames.”
Control the 3D viewer camera.
ParameterTypeRequiredDescription
action_typestringYesset_preset, orbit, set_distance, look_at, or follow_entity
presetstringNofront, back, left, right, top, bottom, isometric
azimuth_deltafloatNoHorizontal orbit delta (for orbit)
elevation_deltafloatNoVertical orbit delta (for orbit)
distancefloatNoCamera distance (for set_distance)
x, y, zfloatNoTarget point (for look_at)
entity_namestringNoEntity to track (for follow_entity)
Example prompt: “Follow the drone from an isometric angle.”
Run a command synchronously inside the simulation Docker container.
ParameterTypeRequiredDescription
simulation_idstringYesTarget container
commandstringYesShell command to execute
timeout_msintNoTimeout (default 120,000; max 300,000)
workdirstringNoWorking directory inside the container
Pre-installed software: MAVSDK 2.0.1, DroneKit 2.9.2, pymavlink, ROS 2 Humble, Gazebo Harmonic, PX4 v1.16.1.Example prompt: “Run ros2 topic list inside the simulation container.”

​
Background Tasks

6 tools for running long operations without blocking the conversation.
Run a command asynchronously inside the simulation container.
ParameterTypeRequiredDescription
simulation_idstringYesTarget container
commandstringYesShell command to execute
timeout_msintNoTimeout (max 600,000)
workdirstringNoWorking directory inside the container
Returns: task_id immediately. Use check_background_task or wait_for_any to get results.Example prompt: “Run the MAVSDK waypoint mission script in the background.”
Start a long-running managed task.
ParameterTypeRequiredDescription
kindstringYesWaitSimulationReady, AnalyzeVideo, or BashExecution
notify_on_completeboolNoWhether to notify when done
Returns: task_id.Example prompt: “Start waiting for the simulation to be ready in the background.”
Wait for ANY of the given background tasks to complete.
ParameterTypeRequiredDescription
task_idslistYesTask IDs to wait on
timeout_msintNoTimeout (default 60,000; max 300,000)
Returns: The first completed task’s result.Example prompt: “Wait for either the build or the simulation startup to finish.”
Check the status of a background task.
ParameterTypeRequiredDescription
task_idstringYesTask to check
blockboolNoBlock until complete
timeout_msintNoTimeout when blocking
Task states: Pending, Running, Complete, Failed, Cancelled.Returns: Current state and output if complete.Example prompt: “Is the waypoint mission script still running?”
Cancel a running background task.
ParameterTypeRequiredDescription
task_idstringYesTask to cancel
Example prompt: “Cancel the background mission script.”
List all background tasks with their current status.No parameters.Returns: All tasks with IDs, kinds, and states.Example prompt: “Show me all background tasks.”

​
Data Exploration

5 tools for inspecting live simulation data.
List available data topics from the simulation.
ParameterTypeRequiredDescription
categorystringNoFilter: Image, PointCloud, JointState, Telemetry, Transform, Marker, Annotation, Log, LaserScan, Other
Returns: Topic names, types, and update rates.Example prompt: “What telemetry topics are available?”
Get the current telemetry snapshot: pose, velocity, battery, and flight mode.No parameters.Returns: Latest telemetry values.Example prompt: “What’s the drone’s current altitude and battery level?”
Read time-series data for a telemetry channel.
ParameterTypeRequiredDescription
channel_pathstringYesChannel name (supports suffix matching, e.g. position.z)
max_samplesintNoMax data points (default 200, max 1,000)
Returns: Auto-downsampled ring buffer data with min, max, unit, and time range.Example prompt: “Plot the altitude over the last 30 seconds.”
Query the entity hierarchy from the 3D viewer.
ParameterTypeRequiredDescription
path_prefixstringNoFilter to a subtree (e.g. /world/default/x500_0)
Returns: Entity list with entity_id, path, and parent_path.Example prompt: “Show me all entities under the x500 model.”
Query the transform (TF) hierarchy or look up a specific frame transform.
ParameterTypeRequiredDescription
source_framestringNoSource coordinate frame
target_framestringNoTarget coordinate frame
timefloatNoTimestamp for the lookup
Hierarchy mode (no args): returns the full parent-child frame tree. Lookup mode (with frames): returns a 4x4 transform matrix.Example prompt: “What’s the transform from the base_link to the camera frame?”

​
Vision & Recording

5 tools for visual capture and AI-powered analysis.
Capture a PNG screenshot of the 3D viewer. Returns binary image content directly (bypasses output truncation).No parameters.Returns: PNG image as BinaryContent.Example prompt: “Take a screenshot of the viewer.”
Capture a screenshot and analyze it with Gemini vision.
ParameterTypeRequiredDescription
promptstringYesWhat to look for in the image
Returns: Vision model analysis of the captured frame.Example prompt: “Take a screenshot and check if the drone is hovering level.”
Begin video recording of the 3D viewer.
ParameterTypeRequiredDescription
max_duration_secsintNoMaximum duration (default 30, max 30)
Returns: Confirmation that recording started.Example prompt: “Start recording the viewer for 20 seconds.”
Stop the current video recording.No parameters.Returns: Path to the saved video file.Example prompt: “Stop recording.”
Analyze a recorded video with Gemini vision.
ParameterTypeRequiredDescription
video_pathstringYesPath to the video file
promptstringYesWhat to analyze
backgroundboolNoRun analysis as a background task
Videos under 5 MB use frame extraction. Videos 5 MB and above are uploaded via the Gemini File API.Example prompt: “Analyze the recording and tell me if the landing was smooth.”

​
Scene Authoring

3 tools for modifying the simulation scene at runtime.
Spawn a Gazebo model into the scene.
ParameterTypeRequiredDescription
simulation_idstringYesTarget simulation
model_idstringYesGazebo model identifier
entity_namestringYesName for the spawned entity
x, y, zfloatYesSpawn position (meters)
Example prompt: “Spawn a construction barrel at position 5, 3, 0.”
Remove an entity from the scene.
ParameterTypeRequiredDescription
simulation_idstringYesTarget simulation
entity_idstringYesEntity to remove
Example prompt: “Remove the barrel I just spawned.”
List entities that have dynamic pose updates (suitable for camera follow).No parameters.Returns: Entity names with active pose streams.Example prompt: “Which entities can I follow with the camera?”

​
Task Management

4 tools for structured task tracking with dependency support.
Create a new task in the session’s task list.
ParameterTypeRequiredDescription
titlestringYesShort task description
descriptionstringNoDetailed requirements
blocked_bylistNoIDs of tasks that must complete first
Returns: Created task with ID and status.Example prompt: “Create a task to implement the GPS fence, blocked by the config parser task.”
Update a task’s status, title, or dependencies.
ParameterTypeRequiredDescription
task_idintYesTask to update
statusstringNopending, in_progress, completed, or cancelled
titlestringNoNew title
descriptionstringNoNew description
resultstringNoCompletion result or notes
Completing a task automatically unblocks any tasks that were waiting on it.Returns: Updated task.Example prompt: “Mark task 3 as completed.”
List all tasks in the current session.No parameters.Returns: All tasks with IDs, titles, statuses, and dependency info.Example prompt: “Show me all tasks and their status.”
Get full details for a specific task.
ParameterTypeRequiredDescription
task_idintYesTask to retrieve
Returns: Full task details including description, dependencies, and result.Example prompt: “Show me the details of task 2.”

​
Web

1 tool for fetching external content.
Fetch a URL with pagination support.
ParameterTypeRequiredDescription
urlstringYesURL to fetch
max_lengthintNoMax content length (default 5,000)
start_indexintNoPagination offset (default 0)
rawboolNoReturn raw response (for JSON APIs); otherwise HTML is converted to Markdown
Returns: Fetched content as Markdown or raw text.Example prompt: “Fetch the PX4 parameter reference for EKF2_HGT_REF.”

​
Safety & Security

Two tools require explicit user approval before executing:
ToolApproval Type
edit_fileDiff shown for review
write_fileFull content shown for review
The assistant cannot modify files without your confirmation. Edits are presented as diffs in the chat panel so you can accept, reject, or request changes.
You can ask the assistant “what tools do you have?” at any time. It will summarize its available capabilities based on the current simulation state.