Godot AI

Overview Schema Source Related Servers Discussions Admin

Test Run

test_run

Run GDScript test suites in a live Godot editor to validate code changes, returning concise summaries and failure details.

Instructions

Run GDScript test suites inside the connected Godot editor.

Discovers test_*.gd in res://tests/, instantiates them, and runs all test_* methods. Returns a compact summary by default (counts, suite names, duration) plus failures only. verbose=True includes every individual test result (each with per-test duration_ms).

Preloaded GDScript dependencies may remain stale after source edits; the response includes cache_warning. Restart the editor before using a rerun to validate dependency edits. ResourceLoader cache modes alone do not refresh the GDScript preload cache.

The whole run has a 300s budget; the plugin aborts between tests shortly before it expires and returns TEST_RUN_TIMEOUT with the partial summary (full partials via test_manage(op="results_get")). Long suites are safe — the editor services the MCP transport between tests — but one single test blocking the main thread for 20s+ can still drop the session. Not allowed inside batch_execute.

The response includes edited_scene (the scene currently open in the editor). Many suites assume the project's main scene is open; if it is not and there are failures, the response also carries a scene_warning — open the main scene (scene_open) and re-run before treating those failures as real.

Input Schema

TableJSON Schema

Name	Required	Description
`suite`	No	Run only the named suite (e.g. "scene", "node", "editor"). Empty runs all suites.
`verbose`	No	Include every individual test result. Default False.
`test_name`	No	Run only tests whose name contains this substring.
`session_id`	No	Optional Godot session to target. Empty = active session.
`exclude_test_name`	No	Skip tests whose name contains this substring.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv2.9.1Jul 11, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses the 300s timeout and TEST_RUN_TIMEOUT behavior, the risk of a single test blocking the main thread for 20s+, the cache_warning about stale preloads, the scene_warning about main scene assumptions, and the edited_scene response field. This is rich behavioral context beyond what any schema could provide.

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 description is long but every sentence earns its place: discovery mechanism, output format, cache warning, timeout behavior, batch_execute restriction, and scene warning. It is front-loaded with the core purpose and then layers caveats. Slightly dense, but appropriate for a tool with this many behavioral nuances.

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?

Given the tool's complexity (5 optional params, no required params, output schema present, no annotations), the description covers all critical operational aspects: what runs, how to filter, what the response contains, timeout behavior, safety during long runs, and environmental prerequisites (main scene). An agent has enough to invoke it correctly and interpret results.

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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the default summary vs verbose output, the substring matching behavior for test_name/exclude_test_name, and the suite filtering concept. It doesn't detail every parameter's edge cases, but it adds value beyond the schema's terse descriptions.

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 states a specific verb ('Run GDScript test suites'), a resource ('inside the connected Godot editor'), and the mechanism (discovers test_*.gd, instantiates, runs test_* methods). It clearly distinguishes itself from siblings like test_manage and project_run by focusing on executing tests in-editor.

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?

The description gives explicit when-to-use context: run suites, filter by suite/test_name, use verbose for full results. It also provides exclusions: not allowed inside batch_execute, and warns about stale preload caches requiring editor restart. It names alternatives indirectly (test_manage for partial results, scene_open for main scene) and gives clear re-run guidance.

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