Tools: clarify execute_javascript-first descriptions

lib/tool-registry.js

@@ -186,7 +186,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'get_scene_info',
       profile: 'core',
-      description: '[core] Get a summary of the active Cocos scene.',
+      description: '[specialist] Return a structured summary of the active Cocos scene. Prefer execute_javascript for multi-step inspection or mutation; use this when you specifically want a compact scene snapshot.',
       inputSchema: createSchema(
         {
           maxDepth: { type: 'number', description: 'Maximum child depth to include in the scene summary.' },
@@ -199,7 +199,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'get_hierarchy',
       profile: 'core',
-      description: '[core] Browse the scene hierarchy tree from the active scene or a specific node path.',
+      description: '[specialist] Return a structured hierarchy tree from the active scene or a specific node path. Prefer execute_javascript for broader reasoning or repair; use this when you want a predictable hierarchy snapshot.',
       inputSchema: createSchema(
         {
           rootPath: { type: 'string', description: 'Optional node path to use as the traversal root.' },
@@ -292,14 +292,14 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'get_project_info',
       profile: 'core',
-      description: '[core] Return the active Cocos project path, version, and MCP server configuration.',
+      description: '[specialist] Return the active Cocos project path, version, and MCP server configuration. Prefer this for a fast structured project summary; use execute_javascript when you need to inspect and act in one step.',
       inputSchema: createSchema({}, []),
       handler: async () => getRuntimeContext(),
     },
     {
       name: 'list_scenes',
       profile: 'core',
-      description: '[core] List scene assets in the project.',
+      description: '[specialist] List scene assets in the project. Prefer this when you need exact scene discovery before opening one; otherwise stay in execute_javascript for broader workflows.',
       inputSchema: createSchema(
         {
           pattern: { type: 'string', description: 'Optional asset-db pattern. Defaults to db://assets/**.' },
@@ -314,7 +314,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'open_scene',
       profile: 'core',
-      description: '[core] Open a scene asset in Cocos Creator by uuid, db url, or path.',
+      description: '[specialist] Open a scene asset in Cocos Creator by uuid, db url, or path. Use this when scene switching is the explicit goal; otherwise keep execute_javascript as the main planning tool.',
       inputSchema: createSchema(
         {
           target: { type: 'string', description: 'Scene uuid, db url, or path.' },
@@ -368,7 +368,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'list_assets',
       profile: 'core',
-      description: '[core] Query project assets from asset-db by pattern or asset type.',
+      description: '[specialist] Query project assets from asset-db by pattern or asset type. Prefer this when you need exact asset discovery; otherwise use execute_javascript for broader automation.',
       inputSchema: createSchema(
         {
           pattern: { type: 'string', description: 'Optional asset-db pattern such as db://assets/** or a folder url.' },
@@ -387,7 +387,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'inspect_asset',
       profile: 'core',
-      description: '[core] Inspect asset-db info, metadata, and serialized asset data by uuid or path.',
+      description: '[specialist] Inspect asset-db info, metadata, and serialized asset data by uuid or path. Prefer this when you need a precise structured asset read.',
       inputSchema: createSchema(
         {
           target: { type: 'string', description: 'Asset uuid, db url, or path.' },
@@ -405,7 +405,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'open_asset',
       profile: 'core',
-      description: '[core] Open an asset inside Cocos Creator by uuid, db url, or path.',
+      description: '[specialist] Open an asset inside Cocos Creator by uuid, db url, or path. Use this only when opening the asset itself is the explicit next step.',
       inputSchema: createSchema(
         {
           target: { type: 'string', description: 'Asset uuid, db url, or path.' },
@@ -429,7 +429,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'select_asset',
       profile: 'core',
-      description: '[core] Select an asset in the Cocos editor.',
+      description: '[specialist] Select an asset in the Cocos editor. Use this when editor selection state matters; otherwise keep execute_javascript as the primary workflow.',
       inputSchema: createSchema(
         {
           target: { type: 'string', description: 'Asset uuid, db url, or path.' },
@@ -924,7 +924,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'run_script_diagnostics',
       profile: 'core',
-      description: '[core] Run a TypeScript no-emit check for the current Cocos project and return parsed diagnostics.',
+      description: '[specialist] Run a TypeScript no-emit check for the current Cocos project and return parsed diagnostics. This is a preferred specialist tool for script errors when diagnostics are needed.',
       inputSchema: createSchema(
         {
           tsconfigPath: { type: 'string', description: 'Optional path to the tsconfig file to use.' },
@@ -939,7 +939,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'get_runtime_state',
       profile: 'core',
-      description: '[core] Get Cocos director runtime state, pause state, frame count, and scheduler time scale.',
+      description: '[specialist] Return structured Cocos runtime state including pause state, frame count, and scheduler time scale. Prefer this when you want a compact validation snapshot.',
       inputSchema: createSchema({}, []),
       handler: async (args) => sceneBridge.call('getRuntimeState', args),
     },
@@ -1020,7 +1020,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'get_script_diagnostic_context',
       profile: 'core',
-      description: '[core] Run TypeScript diagnostics and attach source snippets for each error.',
+      description: '[specialist] Run TypeScript diagnostics and attach source snippets for each error. This is a preferred specialist tool for compile-error triage before repair.',
       inputSchema: createSchema(
         {
           tsconfigPath: { type: 'string', description: 'Optional path to the tsconfig file to use.' },
@@ -1066,7 +1066,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'capture_editor_screenshot',
       profile: 'core',
-      description: '[core] Capture the focused Cocos Creator editor window using Electron and return it as an MCP image payload.',
+      description: '[specialist] Capture the focused Cocos Creator editor window and return it as an MCP image payload. Prefer screenshot tools only when visual verification is explicitly needed.',
       inputSchema: createSchema(
         {
           fileName: { type: 'string', description: 'Optional output file name under temp/mcp-captures.' },
@@ -1083,7 +1083,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'capture_scene_screenshot',
       profile: 'core',
-      description: '[core] Capture the Scene panel region from the editor window with panel-level cropping when available.',
+      description: '[specialist] Capture the Scene panel region from the editor window with panel-level cropping when available. Prefer this only for visual validation of scene-side results.',
       inputSchema: createSchema(
         {
           fileName: { type: 'string', description: 'Optional output file name under temp/mcp-captures.' },
@@ -1119,7 +1119,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'list_editor_windows',
       profile: 'core',
-      description: '[core] List available Electron windows so input injection and precise screenshots can target the correct one.',
+      description: '[specialist] List available Electron windows so screenshots or input-targeting can choose the correct window. Use this when window targeting is the explicit problem.',
       inputSchema: createSchema({}, []),
       handler: async () => listWindows(),
     },
@@ -1232,7 +1232,7 @@ function createToolRegistry({ getRuntimeContext, interactionLog, sceneBridge, ed
     {
       name: 'capture_preview_screenshot',
       profile: 'core',
-      description: '[core] Capture the preview/simulator window or game panel as an MCP image payload.',
+      description: '[specialist] Capture the preview or simulator window as an MCP image payload. Prefer this only when you need visual proof of game or preview output.',
       inputSchema: createSchema(
         {
           fileName: { type: 'string', description: 'Optional output file name under temp/mcp-captures.' },