From 9a547d1f5f4edd4f5415666ed348fd5612d44703 Mon Sep 17 00:00:00 2001 From: winlifes <110321103+Winlifes@users.noreply.github.com> Date: Wed, 15 Apr 2026 18:09:59 +0800 Subject: [PATCH] Tools: clarify execute_javascript-first descriptions --- lib/tool-registry.js | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/lib/tool-registry.js b/lib/tool-registry.js index a68cd4a..1982f9a 100644 --- a/lib/tool-registry.js +++ b/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.' },