Prefer direct tools in live agent code guidance

lib/ai/agents.ts

@@ -187,9 +187,10 @@ const executeCode = tool(
   {
     name: "execute_code",
     description:
-      "Execute a Blender Python script. Use this for geometry creation, material setup, " +
-      "animation, lighting, camera, and any Blender Python API operation. " +
-      "Break complex objects into SEPARATE calls — one component per call.",
+      "Execute a scoped Blender Python script. Use only when no direct MCP tool fits, " +
+      "such as one-off geometry, procedural effects, animation internals, or short API introspection. " +
+      "Prefer direct tools like create_mesh_from_data, create_material_preset, add_light, add_camera, " +
+      "set_render_settings, prepare_uv_layout, and validate_export_readiness whenever they cover the operation.",
     schema: z.object({
       code: z.string().describe("The Blender Python script to execute"),
     }),

scripts/test/test-live-agent-execute-code-guidance.ts

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict"
+import { readFileSync } from "node:fs"
+
+const agentSource = readFileSync("lib/ai/agents.ts", "utf8")
+
+const executeCodeBlock = agentSource.slice(
+  agentSource.indexOf("const executeCode = tool("),
+  agentSource.indexOf("const getSceneInfo = tool(")
+)
+
+assert.match(executeCodeBlock, /Use only when no direct MCP tool fits/)
+assert.match(executeCodeBlock, /one-off geometry/)
+assert.match(executeCodeBlock, /short API introspection/)
+assert.match(executeCodeBlock, /Prefer direct tools/)
+assert.match(executeCodeBlock, /create_mesh_from_data/)
+assert.match(executeCodeBlock, /create_material_preset/)
+assert.match(executeCodeBlock, /add_light/)
+assert.match(executeCodeBlock, /add_camera/)
+
+assert.doesNotMatch(executeCodeBlock, /Use this for geometry creation, material setup/)
+assert.doesNotMatch(executeCodeBlock, /any Blender Python API operation/)
+assert.doesNotMatch(executeCodeBlock, /Break complex objects into SEPARATE calls/)
+
+console.log("Live agent execute_code guidance tests passed")