Make tool description order deterministic (BTreeMap + alphabetical)

ToolRegistry now uses BTreeMap instead of HashMap so
generate_description() always iterates tools in alphabetical order.
canonical_tool_descriptions() is also sorted alphabetically to match,
ensuring GEPA and production produce identical tool prompt strings.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: AnthonyRonning

crates/sage-core/src/sage_agent.rs

@@ -7,7 +7,7 @@
 
 use anyhow::Result;
 use dspy_rs::{configure, BamlType, ChatAdapter, Predict, LM};
-use std::collections::HashMap;
+use std::collections::{BTreeMap, HashMap};
 use std::sync::Arc;
 use uuid::Uuid;
 
@@ -295,13 +295,13 @@ pub trait Tool: Send + Sync {
 
 /// Registry of available tools
 pub struct ToolRegistry {
-    tools: HashMap<String, Arc<dyn Tool>>,
+    tools: BTreeMap<String, Arc<dyn Tool>>,
 }
 
 impl ToolRegistry {
     pub fn new() -> Self {
         Self {
-            tools: HashMap::new(),
+            tools: BTreeMap::new(),
         }
     }
 

crates/sage-core/src/tools.rs

@@ -7,66 +7,72 @@ use std::sync::Arc;
 
 use crate::sage_agent::{Tool, ToolResult};
 
-/// Canonical tool descriptions matching exactly what the live Sage agent registers.
-/// Used by both the live agent (via ToolRegistry::generate_description) and GEPA evaluation
-/// to ensure prompts are identical.
+/// Canonical tool descriptions for GEPA evaluation.
 ///
-/// Format matches ToolRegistry::generate_description():
-///   {name}:\n  Description: {description}\n  Args: {args_schema}\n\n
+/// Sorted alphabetically by name to match the deterministic BTreeMap order
+/// used by ToolRegistry::generate_description() in production. Descriptions
+/// are copied verbatim from each Tool impl so both paths produce identical output.
+///
+/// Note: production may omit tools based on config (e.g. web_search requires
+/// BRAVE_API_KEY). GEPA always includes the full set.
 #[allow(dead_code)]
 pub fn canonical_tool_descriptions() -> String {
-    // Each entry: (name, description, args_schema)
-    // Order and content must match what agent_manager.rs registers.
+    // Alphabetical order to match BTreeMap iteration in ToolRegistry
     let tools: &[(&str, &str, &str)] = &[
         (
-            "memory_replace",
-            "Replace text in a memory block. Requires exact match of old text.",
-            r#"{"block": "block label (e.g., 'persona', 'human')", "old": "exact text to find", "new": "replacement text"}"#,
+            "archival_insert",
+            "Store information in long-term archival memory for future recall. Good for important facts, preferences, and details you want to remember.",
+            r#"{"content": "text to store", "tags": "optional comma-separated tags"}"#,
         ),
         (
-            "memory_append",
-            "Append text to the end of a memory block.",
-            r#"{"block": "block label (e.g., 'persona', 'human')", "content": "text to append"}"#,
+            "archival_search",
+            "Search long-term archival memory using semantic similarity. Returns most relevant stored memories.",
+            r#"{"query": "search query", "top_k": "max results (default 5)", "tags": "optional comma-separated tags to filter by"}"#,
         ),
         (
-            "memory_insert",
-            "Insert text at a specific line in a memory block. Use line=-1 for end.",
-            r#"{"block": "block label", "content": "text to insert", "line": "line number (0-indexed, -1 for end)"}"#,
+            "cancel_schedule",
+            "Cancel a pending scheduled task by ID.",
+            r#"{"id": "UUID of the task to cancel"}"#,
         ),
         (
             "conversation_search",
             "Search through past conversation history, including older summarized conversations. Returns matching messages and summaries with relevance scores.",
             r#"{"query": "search query", "limit": "max results (default 5)"}"#,
         ),
         (
-            "archival_insert",
-            "Store information in long-term archival memory for future recall. Good for important facts, preferences, and details you want to remember.",
-            r#"{"content": "text to store", "tags": "optional comma-separated tags"}"#,
+            "done",
+            "No-op signal. Use ONLY when messages is [] AND no other tools needed. Indicates nothing to do this turn.",
+            r#"{}"#,
         ),
         (
-            "archival_search",
-            "Search long-term archival memory using semantic similarity. Returns most relevant stored memories.",
-            r#"{"query": "search query", "top_k": "max results (default 5)", "tags": "optional comma-separated tags to filter by"}"#,
+            "list_schedules",
+            "List scheduled tasks. By default shows pending tasks only.",
+            r#"{"status": "optional filter: pending, completed, failed, cancelled, or all (default: pending)"}"#,
         ),
         (
-            "set_preference",
-            "Set a user preference. Known keys: 'timezone' (IANA format like 'America/Chicago'), 'language' (ISO code like 'en'), 'display_name'. Other keys are also allowed.",
-            r#"{"key": "preference key (e.g., 'timezone', 'language', 'display_name')", "value": "preference value"}"#,
+            "memory_append",
+            "Append text to the end of a memory block.",
+            r#"{"block": "block label (e.g., 'persona', 'human')", "content": "text to append"}"#,
+        ),
+        (
+            "memory_insert",
+            "Insert text at a specific line in a memory block. Use line=-1 for end.",
+            r#"{"block": "block label", "content": "text to insert", "line": "line number (0-indexed, -1 for end)"}"#,
+        ),
+        (
+            "memory_replace",
+            "Replace text in a memory block. Requires exact match of old text.",
+            r#"{"block": "block label (e.g., 'persona', 'human')", "old": "exact text to find", "new": "replacement text"}"#,
         ),
         (
             "schedule_task",
             "Schedule a future message or tool execution. Supports one-off (ISO datetime) or recurring (cron expression).",
             r#"{"task_type": "message|tool_call", "description": "human-readable description", "run_at": "ISO datetime (2026-01-26T15:30:00Z) or cron (0 9 * * MON-FRI)", "payload": "JSON: {\"message\": \"...\"} for message, {\"tool\": \"name\", \"args\": {...}} for tool_call", "timezone": "optional IANA timezone for cron (default: user preference or UTC)"}"#,
         ),
         (
-            "list_schedules",
-            "List scheduled tasks. By default shows pending tasks only.",
-            r#"{"status": "optional filter: pending, completed, failed, cancelled, or all (default: pending)"}"#,
-        ),
-        (
-            "cancel_schedule",
-            "Cancel a pending scheduled task by ID.",
-            r#"{"id": "UUID of the task to cancel"}"#,
+            "set_preference",
+            "Set a user preference. Known keys: 'timezone' (IANA format like 'America/Chicago'), 'language' (ISO code like 'en'), 'display_name'. Other keys are also allowed.",
+            r#"{"key": "preference key (e.g., 'timezone', 'language', 'display_name')", "value": "preference value"}"#,
         ),
         (
             "shell",
@@ -78,11 +84,6 @@ pub fn canonical_tool_descriptions() -> String {
             "Search the web with AI summaries, real-time data (weather, stocks, sports), and rich results. Use 'freshness' for time-sensitive queries, 'location' for local results.",
             r#"{ "query": "search query", "count": "results (default 10)", "freshness": "pd=24h, pw=week, pm=month (optional)", "location": "city or 'city, state' for local results (optional)" }"#,
         ),
-        (
-            "done",
-            "No-op signal. Use ONLY when messages is [] AND no other tools needed. Indicates nothing to do this turn.",
-            r#"{}"#,
-        ),
     ];
 
     let mut desc = String::from("Available tools (add to tool_calls array to use):\n\n");