decentraland · dalkia · Aug 7, 2026 · Jul 21, 2026 · Jul 24, 2026 · Aug 3, 2026
@@ -1005,7 +1005,8 @@ await MapRendererContainer
                     bootstrapContainer.DiagnosticsContainer,
                     staticContainer.InputBlock,
                     assetsProvisioner,
-                    debugBuilder
+                    debugBuilder,
+                    staticContainer.ScenesCache
                 ));
 
             if (!localSceneDevelopment)

@@ -299,6 +299,7 @@ public UniTask InitializeAsync(StaticSettings settings, CancellationToken ct)
                 new AssetsCollidersPlugin(sharedDependencies),
                 new AvatarShapePlugin(globalWorld, componentsContainer.ComponentPoolsRegistry, launchMode, useRemoteAssetBundles),
                 new PrimitivesRenderingPlugin(sharedDependencies),
+                new SceneContentStatsPlugin(),
                 new VisibilityPlugin(),
                 new AudioSourcesPlugin(sharedDependencies, container.WebRequestsContainer.WebRequestController, container.CacheCleaner, container.assetsProvisioner),
                 new AudioAnalysisPlugin(sharedDependencies),

@@ -153,7 +153,7 @@ public SceneInstanceDependencies(
             /* Pass dependencies here if they are needed by the systems */
             ecsWorldSharedDependencies = new ECSWorldInstanceSharedDependencies(sceneData, partitionProvider, ecsToCRDTWriter, entitiesMap,
                 ExceptionsHandler, EntityCollidersCache, SceneStateProvider, entityEventsBuilder, ecsMultiThreadSync,
-                systemGroupThrottler, systemsUpdateGate);
+                systemGroupThrottler, systemsUpdateGate, RuntimeMetrics);
 
             ECSWorldFacade = ecsWorldFactory.CreateWorld(new ECSWorldFactoryArgs(ecsWorldSharedDependencies, systemGroupThrottler, sceneData));
             CRDTWorldSynchronizer = new CRDTWorldSynchronizer(ECSWorldFacade.EcsWorld, sdkComponentsRegistry, entityFactory, entitiesMap);

@@ -120,6 +120,9 @@ public void InjectToWorld(ref ArchSystemsWorldBuilder<Arch.Core.World> builder,
                           .Add(screenshotTool)
                           .Add(new GetPlayerStateTool(globalWorld, arguments.PlayerEntity, exposedCameraData, currentSceneInfo))
                           .Add(new GetSceneStateTool(scenesCache, currentSceneInfo, loadingStatus, localSceneDevelopment))
+                          .Add(new GetSceneContentStatsTool(scenesCache))
+                          .Add(new GetSceneContentBreakdownTool(scenesCache))
+                          .Add(new GetPerformanceStatsTool(scenesCache))
                           .Add(new GetSceneLogsTool(logBuffer))
                           .Add(new TeleportTool(chatMessagesBus, scenesCache, loadingStatus))
                           .Add(new MoveToTool(globalWorldActions, globalWorld, arguments.PlayerEntity))

@@ -0,0 +1,117 @@
+using DCL.McpServer.Core;
+using DCL.McpServer.Tools;
+using DCL.Profiling;
+using DCL.Utilities;
+using ECS.SceneLifeCycle;
+using Newtonsoft.Json.Linq;
+using NSubstitute;
+using NUnit.Framework;
+using SceneRunner.Scene;
+using System.Collections.Generic;
+using System.Threading;
+using UnityEngine;
+
+namespace DCL.McpServer.Tests
+{
+    public class GetSceneContentStatsToolShould
+    {
+        private IScenesCache scenesCache = null!;
+        private ISceneFacade scene = null!;
+        private SceneRuntimeMetrics runtimeMetrics = null!;
+
+        [SetUp]
+        public void Setup()
+        {
+            runtimeMetrics = new SceneRuntimeMetrics();
+
+            ISceneData sceneData = Substitute.For<ISceneData>();
+            sceneData.Parcels.Returns(new List<Vector2Int> { new (0, 0), new (0, 1) });
+
+            scene = Substitute.For<ISceneFacade>();
+            scene.SceneData.Returns(sceneData);
+            scene.RuntimeMetrics.Returns(runtimeMetrics);
+
+            scenesCache = Substitute.For<IScenesCache>();
+            scenesCache.CurrentScene.Returns(new ReactiveProperty<ISceneFacade?>(scene));
+        }
+
+        [Test]
+        public void ErrorWhenNoSceneIsLoaded()
+        {
+            // Arrange
+            scenesCache.CurrentScene.Returns(new ReactiveProperty<ISceneFacade?>(null));
+            var tool = new GetSceneContentStatsTool(scenesCache, collectionTimeoutMs: 0);
+
+            // Act
+            McpToolResult result = Execute(tool);
+
+            // Assert
+            Assert.That(result.Payload["isError"]!.Value<bool>(), Is.True);
+        }
+
+        [Test]
+        public void ErrorWhenTheSceneNeverProducedStats()
+        {
+            // Arrange — HasData stays false and the zero timeout skips waiting for a pass
+            var tool = new GetSceneContentStatsTool(scenesCache, collectionTimeoutMs: 0);
+
+            // Act
+            McpToolResult result = Execute(tool);
+
+            // Assert
+            Assert.That(result.Payload["isError"]!.Value<bool>(), Is.True);
+            Assert.That(runtimeMetrics.ContentStats.RequestedByMcp, Is.False);
+        }
+
+        [Test]
+        public void ReportStatsWithCapsMatchingTheOutputSchema()
+        {
+            // Arrange
+            SceneContentStats stats = runtimeMetrics.ContentStats;
+            stats.HasData = true;
+            stats.Entities = 10;
+            stats.Triangles = 5200;
+            stats.Bodies = 12;
+            stats.Geometries = 7;
+            stats.Materials = 5;
+            stats.Textures = 3;
+            stats.ShaderVariants = 2;
+            stats.Colliders = 2;
+            stats.Videos = 1;
+
+            var tool = new GetSceneContentStatsTool(scenesCache, collectionTimeoutMs: 0);
+
+            // Act
+            var structured = (JObject)Execute(tool).Payload["structuredContent"]!;
+
+            // Assert
+            McpSchemaAssert.KeysMatch(tool.OutputSchema, structured);
+            Assert.That(structured["parcelCount"]!.Value<int>(), Is.EqualTo(2));
+            Assert.That(structured["fresh"]!.Value<bool>(), Is.False);
+            Assert.That(structured["entities"]!.Value<int>(), Is.EqualTo(10));
+            Assert.That(structured["entitiesCap"]!.Value<int>(), Is.EqualTo(400));
+            Assert.That(structured["triangles"]!.Value<long>(), Is.EqualTo(5200));
+            Assert.That(structured["trianglesCap"]!.Value<long>(), Is.EqualTo(20000));
+            Assert.That(structured["geometries"]!.Value<int>(), Is.EqualTo(7));
+            Assert.That(structured["shaderVariants"]!.Value<int>(), Is.EqualTo(2));
+            Assert.That(structured["videos"]!.Value<int>(), Is.EqualTo(1));
+        }
+
+        [Test]
+        public void ClearTheDemandFlagAfterReporting()
+        {
+            // Arrange
+            runtimeMetrics.ContentStats.HasData = true;
+            var tool = new GetSceneContentStatsTool(scenesCache, collectionTimeoutMs: 0);
+
+            // Act
+            Execute(tool);
+
+            // Assert
+            Assert.That(runtimeMetrics.ContentStats.RequestedByMcp, Is.False);
+        }
+
+        private static McpToolResult Execute(GetSceneContentStatsTool tool) =>
+            tool.ExecuteAsync(new JObject(), CancellationToken.None).GetAwaiter().GetResult();
+    }
+}
@@ -0,0 +1,161 @@
+using Cysharp.Threading.Tasks;
+using DCL.McpServer.Core;
+using DCL.McpServer.Utils;
+using DCL.Profiling;
+using ECS.SceneLifeCycle;
+using Newtonsoft.Json.Linq;
+using SceneRunner.Scene;
+using System.Globalization;
+using System.Text;
+using System.Threading;
+using UnityEngine;
+
+namespace DCL.McpServer.Tools
+{
+    /// <summary>
+    ///     Samples the client's real frame rate over its own short window (no shared profiler state
+    ///     is touched) and reports it together with the current scene's tick FPS, so an agent can
+    ///     correlate a viewpoint's content cost with the frame rate it actually produces.
+    /// </summary>
+    public class GetPerformanceStatsTool : McpTool
+    {
+        private const float DEFAULT_SAMPLE_SECONDS = 2f;
+        private const float MIN_SAMPLE_SECONDS = 0.5f;
+        private const float MAX_SAMPLE_SECONDS = 10f;
+        private const float HICCUP_THRESHOLD_MS = 50f;
+
+        private readonly IScenesCache scenesCache;
+        private readonly long[] tickScratch = new long[SampledCounter.BUFFER_CAPACITY];
+
+        public override string Name => "get_performance_stats";
+
+        public override string Description =>
+            "Sample the client's real frame rate over a short window and report render FPS (average, min, max, hiccup frames > 50 ms) plus "
+            + "the current scene's tick FPS vs its target. The call holds for sampleSeconds while it measures. Use together with "
+            + "get_scene_content_breakdown (sortBy=visibleTriangles) to correlate a viewpoint's content cost with the frame rate it actually "
+            + "produces — position the camera first, then sample.";
+
+        public override JObject OutputSchema =>
+            McpJsonSchema.Object()
+                          .Number("sampleSeconds")
+                          .Integer("framesSampled")
+                          .Number("averageFps")
+                          .Number("minFps", "Lowest instantaneous FPS in the window (longest frame).")
+                          .Number("maxFps")
+                          .Number("averageFrameMs")
+                          .Number("maxFrameMs")
+                          .Integer("hiccupFrames", "Frames longer than 50 ms in the window.")
+                          .Object("sceneTick", McpJsonSchema.Object()
+                                                             .Number("averageFps")
+                                                             .Number("minFps")
+                                                             .Number("maxFps")
+                                                             .Integer("targetFps"),
+                              "The current scene's JS tick rate, or null when no scene is loaded or it has not ticked yet.", nullable: true)
+                          .Build();
+
+        public override McpToolAnnotations Annotations => McpToolAnnotations.ReadOnly();
+
+        public GetPerformanceStatsTool(IScenesCache scenesCache)
+        {
+            this.scenesCache = scenesCache;
+        }
+
+        public override async UniTask<McpToolResult> ExecuteAsync(JObject arguments, CancellationToken ct)
+        {
+            float sampleSeconds = Mathf.Clamp(arguments.GetFloat("sampleSeconds", DEFAULT_SAMPLE_SECONDS), MIN_SAMPLE_SECONDS, MAX_SAMPLE_SECONDS);
+
+            var framesSampled = 0;
+            float totalMs = 0f;
+            float minFrameMs = float.MaxValue;
+            float maxFrameMs = 0f;
+            var hiccupFrames = 0;
+
+            float start = UnityEngine.Time.realtimeSinceStartup;
+
+            while (UnityEngine.Time.realtimeSinceStartup - start < sampleSeconds)
+            {
+                await UniTask.NextFrame(ct);
+
+                float frameMs = UnityEngine.Time.unscaledDeltaTime * 1000f;
+                framesSampled++;
+                totalMs += frameMs;
+                if (frameMs < minFrameMs) minFrameMs = frameMs;
+                if (frameMs > maxFrameMs) maxFrameMs = frameMs;
+                if (frameMs > HICCUP_THRESHOLD_MS) hiccupFrames++;
+            }
+
+            if (framesSampled == 0)
+                return McpToolResult.Error("No frames rendered during the sampling window.");
+
+            float averageFrameMs = totalMs / framesSampled;
+            float averageFps = 1000f / averageFrameMs;
+            float minFps = 1000f / maxFrameMs;
+            float maxFps = 1000f / minFrameMs;
+
+            JObject? sceneTick = null;
+            ISceneFacade? scene = scenesCache.CurrentScene.Value;
+
+            if (scene != null)
+            {
+                SceneRuntimeMetrics metrics = scene.RuntimeMetrics;
+                int tickSamples = metrics.TickTimesNs.CopySnapshot(tickScratch);
+
+                if (tickSamples > 0)
+                {
+                    long totalNs = 0;
+                    long minNs = long.MaxValue;
+                    long maxNs = long.MinValue;
+
+                    for (var i = 0; i < tickSamples; i++)
+                    {
+                        long ns = tickScratch[i];
+                        if (ns <= 0) continue;
+                        totalNs += ns;
+                        if (ns < minNs) minNs = ns;
+                        if (ns > maxNs) maxNs = ns;
+                    }
+
+                    if (totalNs > 0)
+                        sceneTick = new JObject
+                        {
+                            ["averageFps"] = Round1(1e9f / ((float)totalNs / tickSamples)),
+                            ["minFps"] = Round1(1e9f / maxNs),
+                            ["maxFps"] = Round1(1e9f / minNs),
+                            ["targetFps"] = metrics.TargetFps,
+                        };
+                }
+            }
+
+            var structured = new JObject
+            {
+                ["sampleSeconds"] = Round1(sampleSeconds),
+                ["framesSampled"] = framesSampled,
+                ["averageFps"] = Round1(averageFps),
+                ["minFps"] = Round1(minFps),
+                ["maxFps"] = Round1(maxFps),
+                ["averageFrameMs"] = Round1(averageFrameMs),
+                ["maxFrameMs"] = Round1(maxFrameMs),
+                ["hiccupFrames"] = hiccupFrames,
+                ["sceneTick"] = sceneTick ?? (JToken)JValue.CreateNull(),
+            };
+
+            var text = new StringBuilder();
+            text.Append("Render: ").Append(averageFps.ToString("F1", CultureInfo.InvariantCulture)).Append(" fps avg (min ")
+                .Append(minFps.ToString("F1", CultureInfo.InvariantCulture)).Append(", max ")
+                .Append(maxFps.ToString("F1", CultureInfo.InvariantCulture)).Append(") over ")
+                .Append(framesSampled).Append(" frames / ").Append(sampleSeconds.ToString("F1", CultureInfo.InvariantCulture)).Append("s; ")
+                .Append(hiccupFrames).AppendLine(" hiccup frames (>50 ms).");
+
+            if (sceneTick != null)
+                text.Append("Scene tick: ").Append(sceneTick["averageFps"]!.Value<float>().ToString("F1", CultureInfo.InvariantCulture))
+                    .Append(" fps avg (target ").Append(sceneTick["targetFps"]!.Value<int>()).Append(").");
+            else
+                text.Append("Scene tick: no data (no scene loaded or it has not ticked yet).");
+
+            return McpToolResult.TextWithStructured(text.ToString(), structured);
+        }
+
+        private static float Round1(float value) =>
+            Mathf.Round(value * 10f) / 10f;
+    }
+}