Skip to main content
Glama

start_profiler

Begin recording a Godot runtime profiling capture that runs while scripts, input, and screenshots drive the game, then reports frame drops and timelines. Stops automatically after the set duration.

Instructions

Start a profiler capture and return at once, so simulate_input, run_script and screenshots drive the game while it records; timeline and track show where frames drop. Requires run_project with profiling: true. Stops itself after seconds (default 30, max 60); read it with stop_profiler. Unattended window: use profile_project. Returns: warnings if any, projectPath, active, visual, timeline, timelineMs, firstFrame, captureLimit, maxSeconds. Errors if a capture is running or profiling was off.

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": "start_profiler"
  }
}

Input Schema

NameRequiredDescriptionDefault
trackNoUp to 4 NodePath:property values the game samples during the capture (every 250 ms, or half the interval when shorter), placed on the timeline by frame number, e.g. "/root/Main/Player:global_position" - where the player was when frames got slow. Implies timeline. Uses the bridge: drive the game between start_profiler and stop_profiler, not in parallel with profile_project. Collected only while the session that started the capture is current.
visualNoAlso record the editor's Visual Profiler: CPU and GPU milliseconds per render stage (culling, shadows, opaque pass, canvas, ...) in `visual` (default: false). GPU times are null on GLES/web builds of the Compatibility renderer, which time no GPU work; `visual.gpuTimed` is false and a warning says so. A frame holds 256 render markers by default; a scene that needs more makes the engine log an error per lost marker, slowing the game, so the capture switches visual off and its warnings say how to raise the limit.
secondsNoMaximum capture duration before the automatic stop, greater than 0 and at most 60 (default: 30).
timelineNoAlso record the capture over time in `timeline.buckets`: per interval the fps, frameMs avg/max, process/physics/script ms, slowFrames, draw calls, render CPU/GPU ms (with visual) and the heaviest functions, server calls or render stages (`top`, named once in `timeline.items`) - where and when frames got slow (default: false). timelineMs, timelineTop, timelineBuckets and track turn it on by themselves; false beside any is rejected.
targetFpsNoFrame rate to hold the game to (default: 60). slowFrames counts frames whose frameMs exceeds 1000/targetFps, over the capture and per timeline interval. Under vsync every frame lasts the refresh interval: disable vsync, or set targetFps a few percent below the refresh rate.
timelineMsNoTimeline interval in milliseconds, 250..5000 (default: 500). Records at most about 60 intervals (60 s: 1000 ms) and the reply merges them down to timelineBuckets. Implies timeline.
timelineTopNoHeaviest functions, server calls or render stages listed per timeline interval, 0..10 (default: 3). 0 leaves `top` empty. Implies timeline.
captureLimitNoRows the engine puts in each frame packet, 16..512 (default: 512). Godot selects them by inclusive time, so a lower limit hides cheap functions and sets limitReached.
timelineBucketsNoMost intervals the timeline reply holds, 4..60 (default: 20). A capture recorded in more is merged: adjacent intervals combine (counts and times add up, maxima stay) and `timeline.bucketMs` reports the width. Implies timeline.

Output Schema

NameRequiredDescriptionDefault
activeYes
visualYes
timelineYes
warningsNo
firstFrameYes
maxSecondsYes
timelineMsYes
projectPathYes
captureLimitYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed18 schema fields changedv4.0.1
    • addedInput schema / properties / captureLimit / maximum
      Added value: +512
    • addedInput schema / properties / captureLimit / minimum
      Added value: +16
    • changedInput schema / properties / captureLimit / type
      Previous value: -"number"New value: +"integer"
    • addedInput schema / properties / seconds / exclusiveMinimum
      Added value: +0
    • addedInput schema / properties / seconds / maximum
      Added value: +60
    • addedInput schema / properties / targetFps
      Added value: +{
      +  "description": "Frame rate to hold the game to (default: 60). slowFrames counts frames whose frameMs exceeds 1000/targetFps, over the capture and per timeline interval. Under vsync every frame lasts the refresh interval: disable vsync, or set targetFps a few percent below the refresh rate.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 1000,
      +  "type": "number"
      +}
    • addedInput schema / properties / timeline
      Added value: +{
      +  "description": "Also record the capture over time in `timeline.buckets`: per interval the fps, frameMs avg/max, process/physics/script ms, slowFrames, draw calls, render CPU/GPU ms (with visual) and the heaviest functions, server calls or render stages (`top`, named once in `timeline.items`) - where and when frames got slow (default: false). timelineMs, timelineTop, timelineBuckets and track turn it on by themselves; false beside any is rejected.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / timelineBuckets
      Added value: +{
      +  "description": "Most intervals the timeline reply holds, 4..60 (default: 20). A capture recorded in more is merged: adjacent intervals combine (counts and times add up, maxima stay) and `timeline.bucketMs` reports the width. Implies timeline.",
      +  "maximum": 60,
      +  "minimum": 4,
      +  "type": "integer"
      +}
    • addedInput schema / properties / timelineMs
      Added value: +{
      +  "description": "Timeline interval in milliseconds, 250..5000 (default: 500). Records at most about 60 intervals (60 s: 1000 ms) and the reply merges them down to timelineBuckets. Implies timeline.",
      +  "maximum": 5000,
      +  "minimum": 250,
      +  "type": "integer"
      +}
    • addedInput schema / properties / timelineTop
      Added value: +{
      +  "description": "Heaviest functions, server calls or render stages listed per timeline interval, 0..10 (default: 3). 0 leaves `top` empty. Implies timeline.",
      +  "maximum": 10,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / track
      Added value: +{
      +  "description": "Up to 4 NodePath:property values the game samples during the capture (every 250 ms, or half the interval when shorter), placed on the timeline by frame number, e.g. \"/root/Main/Player:global_position\" - where the player was when frames got slow. Implies timeline. Uses the bridge: drive the game between start_profiler and stop_profiler, not in parallel with profile_project. Collected only while the session that started the capture is current.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "maxItems": 4,
      +  "type": "array"
      +}
    • addedInput schema / properties / visual
      Added value: +{
      +  "description": "Also record the editor's Visual Profiler: CPU and GPU milliseconds per render stage (culling, shadows, opaque pass, canvas, ...) in `visual` (default: false). GPU times are null on GLES/web builds of the Compatibility renderer, which time no GPU work; `visual.gpuTimed` is false and a warning says so. A frame holds 256 render markers by default; a scene that needs more makes the engine log an error per lost marker, slowing the game, so the capture switches visual off and its warnings say how to raise the limit.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / projectPath
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / timeline
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / timelineMs
      Added value: +{
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / visual
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / warnings
      Added value: +{
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / required
      Added value: +[
      +  "projectPath",
      +  "active",
      +  "visual",
      +  "timeline",
      +  "timelineMs",
      +  "maxSeconds",
      +  "firstFrame",
      +  "captureLimit"
      +]
  2. Addedv3.4.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only say readOnlyHint=false / destructiveHint=false; the description adds far more: the tool returns immediately and records in the background, self-terminates after `seconds` (default 30, max 60), and errors if a capture is already running or profiling was off. It also notes that exceeding the 256-render-marker limit forces visual off and produces warnings, which is genuine behavioral context an agent cannot get from the schema.

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

Conciseness4/5

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

Front-loaded with the action and its async nature, then prerequisites, lifetime, alternative, and errors — a logical order. The trailing "Returns: warnings if any, projectPath, active, ..." enumeration is largely redundant with the existing output schema and is the one piece that does not fully earn its space.

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

Completeness5/5

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

For a 9-parameter, side-effecting capture tool, the description covers prerequisites, lifetime, related tools, error cases, and return contents. Nothing an agent needs in order to invoke it correctly — including the requirement not to run it in parallel with profile_project — is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter is already documented in depth; the description adds little beyond restating the `seconds` default and maximum. The schema's own prose carries the semantics for `track`, `visual`, `timeline`, and the timeline* params, so the baseline 3 applies.

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?

"Start a profiler capture and return at once" gives a specific verb and resource, plus the non-blocking behavior. It explicitly separates itself from profile_project ("Unattended window: use profile_project") and stop_profiler, so an agent can pick the right tool without opening schemas.

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

Usage Guidelines5/5

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

Prerequisites are stated ("Requires run_project with profiling: true"), the intended workflow is spelled out ("drive the game between start_profiler and stop_profiler, not in parallel with profile_project"), the alternative for unattended runs is named, and the error conditions are given.

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