Skip to main content
Glama

stop_profiler

Stops an active profiler capture and ranks recorded function timings by self time, total time, or call count to identify performance bottlenecks in a running Godot game.

Instructions

Stop the start_profiler capture of the current session and rank what it recorded; one that hit its time limit is read back as-is, re-readable with another sort. Times are elapsed, not CPU; inclusive rows overlap, never sum totalMs. Returns: the profile_project payload: warnings first, projectPath, complete (false if cut short), fps, slowFrames, rows, frame, servers, worstFrame, monitors, plus visual and timeline when started with them. Errors if no capture was started.

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

Input Schema

NameRequiredDescriptionDefault
topNoHow many functions to return, 1..100 (default: 20). Also caps visual.areas when the capture recorded render stages.
sortNoRank by own time ("selfMs", default), inclusive time ("totalMs"), or invocation count ("calls").

Output Schema

NameRequiredDescriptionDefault
fpsYes
rowsYes
sortYes
frameYes
framesYes
visualYes
secondsYes
serversYes
completeYes
monitorsYes
timelineYes
warningsNo
frameGapsYes
lastFrameYes
targetFpsYes
firstFrameYes
slowFramesYes
worstFrameYes
projectPathYes
captureLimitYes
limitReachedYes
framesReceivedYes
functionsReceivedYes
undecodablePacketsYes
unresolvedFunctionsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed15 schema fields changedv4.0.1
    • changedInput schema / properties / top / description
      Previous value: -"How many functions to return, 1..100 (default: 20)."New value: +"How many functions to return, 1..100 (default: 20). Also caps visual.areas when the capture recorded render stages."
    • addedInput schema / properties / top / maximum
      Added value: +100
    • addedInput schema / properties / top / minimum
      Added value: +1
    • changedInput schema / properties / top / type
      Previous value: -"number"New value: +"integer"
    • addedOutput schema / properties / complete
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / fps
      Added value: +{
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / monitors
      Added value: +{
      +  "properties": {
      +    "bufferMemMiB": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "custom": {
      +      "items": {
      +        "properties": {
      +          "avg": {
      +            "type": "number"
      +          },
      +          "max": {
      +            "type": "number"
      +          },
      +          "min": {
      +            "type": "number"
      +          },
      +          "name": {
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "drawCallsInFrame": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "nodes": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "objects": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "objectsInFrame": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "orphanNodes": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "physics2dActiveObjects": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "physics2dCollisionPairs": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "physics3dActiveObjects": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "physics3dCollisionPairs": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "pipelineCompilations": {
      +      "properties": {
      +        "duringCapture": {
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        },
      +        "total": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "primitivesInFrame": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "resources": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "samples": {
      +      "type": "number"
      +    },
      +    "staticMemMiB": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "textureMemMiB": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "videoMemMiB": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    }
      +  },
      +  "type": [
      +    "object",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / projectPath
      Added value: +{
      +  "type": "string"
      +}
    • changedOutput schema / properties / rows / items / properties / percentOfFrame / type
      Previous value: -"number"New value: +[
      +  "number",
      +  "null"
      +]
    • addedOutput schema / properties / slowFrames
      Added value: +{
      +  "type": "number"
      +}
    • addedOutput schema / properties / targetFps
      Added value: +{
      +  "type": "number"
      +}
    • addedOutput schema / properties / timeline
      Added value: +{
      +  "properties": {
      +    "bucketMs": {
      +      "type": "number"
      +    },
      +    "buckets": {
      +      "items": {
      +        "properties": {
      +          "drawCalls": {
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "fps": {
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "frameMs": {
      +            "properties": {
      +              "avg": {
      +                "type": "number"
      +              },
      +              "max": {
      +                "type": "number"
      +              }
      +            },
      +            "type": [
      +              "object",
      +              "null"
      +            ]
      +          },
      +          "frames": {
      +            "type": "number"
      +          },
      +          "physicsMs": {
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "processMs": {
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "render": {
      +            "properties": {
      +              "cpuMs": {
      +                "type": "number"
      +              },
      +              "gpuMs": {
      +                "description": "Null when the renderer timed no GPU work (gpuTimed false).",
      +                "type": [
      +                  "number",
      +                  "null"
      +                ]
      +              }
      +            },
      +            "type": [
      +              "object",
      +              "null"
      +            ]
      +          },
      +          "scriptMs": {
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "slowFrames": {
      +            "type": "number"
      +          },
      +          "t": {
      +            "type": "number"
      +          },
      +          "top": {
      +            "items": {
      +              "properties": {
      +                "item": {
      +                  "type": "integer"
      +                },
      +                "maxMs": {
      +                  "type": "number"
      +                },
      +                "ms": {
      +                  "type": "number"
      +                }
      +              },
      +              "type": "object"
      +            },
      +            "type": "array"
      +          },
      +          "track": {
      +            "description": "Tracked values that changed since the last interval with a sample, by spec: absent means unchanged, null means the value became null. The first sample lists every spec. null here means no sample landed in the interval.",
      +            "type": [
      +              "object",
      +              "null"
      +            ]
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "items": {
      +      "items": {
      +        "properties": {
      +          "kind": {
      +            "enum": [
      +              "script",
      +              "server",
      +              "render"
      +            ],
      +            "type": "string"
      +          },
      +          "name": {
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "track": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "trackError": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    }
      +  },
      +  "type": [
      +    "object",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / visual
      Added value: +{
      +  "properties": {
      +    "areas": {
      +      "items": {
      +        "properties": {
      +          "cpuMs": {
      +            "properties": {
      +              "avg": {
      +                "type": "number"
      +              },
      +              "max": {
      +                "type": "number"
      +              }
      +            },
      +            "type": "object"
      +          },
      +          "frames": {
      +            "type": "number"
      +          },
      +          "gpuMs": {
      +            "description": "Null when the renderer timed no GPU work (gpuTimed false).",
      +            "properties": {
      +              "avg": {
      +                "type": "number"
      +              },
      +              "max": {
      +                "type": "number"
      +              }
      +            },
      +            "type": [
      +              "object",
      +              "null"
      +            ]
      +          },
      +          "group": {
      +            "type": "boolean"
      +          },
      +          "name": {
      +            "type": "string"
      +          },
      +          "path": {
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "areasReceived": {
      +      "type": "number"
      +    },
      +    "cpuMs": {
      +      "description": "Null when no render frame was folded (frames is 0).",
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "frames": {
      +      "type": "number"
      +    },
      +    "framesReceived": {
      +      "type": "number"
      +    },
      +    "gpuMs": {
      +      "description": "Null when no render frame was folded, or the renderer timed no GPU work.",
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "gpuTimed": {
      +      "type": "boolean"
      +    },
      +    "hardware": {
      +      "properties": {
      +        "cpu": {
      +          "type": "string"
      +        },
      +        "gpu": {
      +          "type": "string"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "stoppedAt": {
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "truncatedFrames": {
      +      "type": "number"
      +    },
      +    "worstFrame": {
      +      "properties": {
      +        "areas": {
      +          "items": {
      +            "properties": {
      +              "cpuMs": {
      +                "type": "number"
      +              },
      +              "gpuMs": {
      +                "description": "Null when the renderer timed no GPU work (gpuTimed false).",
      +                "type": [
      +                  "number",
      +                  "null"
      +                ]
      +              },
      +              "path": {
      +                "type": "string"
      +              }
      +            },
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "cpuMs": {
      +          "type": "number"
      +        },
      +        "frame": {
      +          "type": "number"
      +        },
      +        "gpuMs": {
      +          "description": "Null when the renderer timed no GPU work (gpuTimed false).",
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    }
      +  },
      +  "type": [
      +    "object",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / warnings
      Added value: +{
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / required
      Added value: +[
      +  "projectPath",
      +  "complete",
      +  "seconds",
      +  "frames",
      +  "fps",
      +  "targetFps",
      +  "slowFrames",
      +  "framesReceived",
      +  "firstFrame",
      +  "lastFrame",
      +  "frameGaps",
      +  "undecodablePackets",
      +  "captureLimit",
      +  "limitReached",
      +  "sort",
      +  "functionsReceived",
      +  "unresolvedFunctions",
      +  "frame",
      +  "servers",
      +  "rows",
      +  "worstFrame",
      +  "monitors",
      +  "visual",
      +  "timeline"
      +]
  2. Addedv3.4.0

TDQS

A4.1/5.0
Behavior4/5

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

With readOnlyHint=false and destructiveHint=false already given, the description adds real context: the capture is read back 'as-is' and is re-readable rather than consumed, a time-limited capture yields complete=false, and the tool errors when no capture exists. It still does not state whether timings/data are reset or retained after repeated stops, leaving one behavioral question open.

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?

The purpose and the key caveats are front-loaded in a tight opening clause, and the semicolon structure keeps it to a few dense sentences. The trailing 'Returns:' enumeration of payload fields is somewhat redundant with the existing output schema, though the 'complete (false if cut short)' note still earns its place.

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?

An output schema exists, so return fields need not be described, yet the description supplies the caveats that matter (complete=false when truncated, elapsed vs CPU time, overlapping inclusive rows, error when no capture). Combined with 100% schema coverage, little an agent needs for correct invocation 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 coverage is 100% (default top=20 with a 1..100 cap, sort enum with defaults), so the schema carries the parameter burden. The description reinforces the sort dimension by noting the capture is 're-readable with another sort,' but adds no format or interaction details for top beyond what the schema says.

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 description opens with a specific verb+resource: 'Stop the start_profiler capture of the current session and rank what it recorded.' It explicitly names the sibling that creates the capture, so an agent can tell start_profiler and stop_profiler apart without opening either schema.

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

Usage Guidelines4/5

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

Usage context is clear: this is the terminator for a start_profiler run, it is re-callable with a different sort, and it 'Errors if no capture was started,' which states a precondition. It lacks an explicit 'when not to use' or a named alternative for obtaining profile data another way, which keeps it below a 5.

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