Merge branch 'main' into change-d274fbc6

frontend/src/lib/components/copilot/chat/flow/core.ts

@@ -1164,6 +1164,7 @@ AI agents can use tools to accomplish tasks. When creating an AI agent module:
       {
         id: "search_docs",
         summary: "Search_documentation",
+        description: "Search the product documentation. Use it whenever the user asks how a feature works.",
         value: {
           tool_type: "flowmodule",
           type: "rawscript",
@@ -1178,7 +1179,8 @@ AI agents can use tools to accomplish tasks. When creating an AI agent module:
 \`\`\`
 
 - **Tool IDs**: Cannot contain spaces - use underscores
-- **Tool summaries**: Cannot contain spaces - use underscores
+- **Tool summaries**: Cannot contain spaces - use underscores. This is the tool *name* the agent sees
+- **Tool descriptions**: Optional free text telling the agent when and how to call the tool. Set it whenever the name alone does not make that obvious - it overrides the description derived from the underlying script
 - **Tool types**: \`flowmodule\` for scripts/flows, \`mcp\` for MCP server tools
 
 ### Contexts

frontend/src/lib/components/flows/agentToolUtils.ts

@@ -122,10 +122,13 @@ export function agentToolToFlowModule(tool: FlowModuleTool): FlowModule {
 }
 
 /**
- * Convert a FlowModule back to an AgentTool
- * Used when saving changes back to the AI Agent tools array
+ * Wrap a newly created FlowModule as an AgentTool.
+ *
+ * Only valid for a module that is not already a tool: FlowModule carries none of the
+ * AgentTool-level metadata (`description`), so folding an edited module back into an
+ * existing tool through here would drop it — spread over the existing tool instead.
  */
-export function flowModuleToAgentTool(flowModule: FlowModule): AgentTool {
+export function newFlowModuleAgentTool(flowModule: FlowModule): AgentTool {
 	return {
 		id: flowModule.id,
 		summary: flowModule.summary,

frontend/src/lib/components/flows/map/FlowModuleSchemaMap.svelte

@@ -45,7 +45,7 @@
 	import {
 		type AgentTool,
 		type SpecialToolKind,
-		flowModuleToAgentTool,
+		newFlowModuleAgentTool,
 		createMcpTool,
 		createWebsearchTool,
 		createAiAgentTool,
@@ -250,8 +250,7 @@
 			;(modules as AgentTool[]).splice(index, 0, aiAgentTool)
 			return modules as AgentTool[]
 		} else if (toolKind === 'flowmoduleTool') {
-			// Create AgentTool from FlowModule
-			const agentTool = flowModuleToAgentTool(module)
+			const agentTool = newFlowModuleAgentTool(module)
 			;(modules as AgentTool[]).splice(index, 0, agentTool)
 			return modules as AgentTool[]
 		} else {