Skip to main content
Glama

get_sim_state

Read-only

Retrieve a Kit simulation's playback state, timeline time and loop behavior, frame-of-reference settings, prim count, and app, extension, and server versions to inspect or diagnose the running scene.

Instructions

Get the simulation's state and the stage's frame of reference: playing, paused or stopped, the timeline's time, the up axis, meters_per_unit, the prim count; the Kit app, its version, Kit's version and the OS Kit runs on; and the versions of the Kit extension and this server.

timeline gives the timeline's range and what it does at its end: while it loops, time goes back to the start there, so a wait for time to pass the end never finishes; a timeline that doesn't loop pauses at its end, and physics with it. A range of one frame or less gets a note.

fps is the timeline's time codes per second, not a render rate: get_performance measures the frame rate. When the two versions differ, the answer names the command that installs the matching extension; while a recording runs whose frames stopped early, it says why; while a job run_script_job started runs, it names it. sim_control changes the state.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_sim_state"
  }
}

Input Schema

NameRequiredDescriptionDefault

No arguments

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.2

TDQS

A4.4/5.0
Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint; the description goes far beyond by disclosing conditional return behavior: a looping timeline resets time so a wait for the end never completes, a non-looping timeline pauses at its end along with physics, and a range of one frame or less produces a note. It also explains when the answer names a version-matching command, why a recording's frames stopped early, and when a run_script_job job is named — all context an agent needs to interpret the result.

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

Conciseness3/5

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

The purpose is front-loaded, but the description runs three dense paragraphs and much of the middle section reads as a list of return fields that an output schema already covers. Some sentences are telegraphic to the point of ambiguity ('A range of one frame or less gets a note', 'while a job run_script_job started runs, it names it'), costing clarity rather than saving space.

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

Completeness4/5

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

For a zero-parameter read tool with a full output schema and read-only annotations, this is more than sufficient — the behavioral caveats about timeline looping and fps-vs-frame-rate are the genuinely load-bearing additions. The remaining gap is that it never says the practical precondition for calling it, so completeness is high but not exhaustive.

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

Parameters4/5

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

The tool takes zero parameters and the schema is an empty object, so there is no parameter meaning to add; the baseline of 4 applies. The description correctly spends no space on argument semantics.

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

Purpose5/5

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

The opening sentence names a specific verb (get) and resource (simulation's state), then enumerates exactly what is returned: play state, timeline time, up axis, meters_per_unit, prim count, Kit/app/OS versions, and extension/server versions. It distinguishes itself from siblings by naming get_performance, sim_control, and run_script_job where their domains overlap.

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

Usage Guidelines4/5

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

It clearly routes away from itself where appropriate — 'sim_control changes the state' and 'get_performance measures the frame rate' — which tells the agent which sibling to pick for mutation or performance data. What's missing is an explicit statement of when to call this tool (e.g. before issuing sim commands, or to check unit scale before transforms).

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