docs: update human and LLM docs and enhance tool/list schemas with actionable next steps

server/src/tools.rs

@@ -140,7 +140,13 @@ pub enum StickyNoteAction {
     Clear,
 }
 
-/// Ephemeral sticky notes with TTL (add, read, delete, clear).
+/// Ephemeral sticky notes with TTL for scratchpad items, ports, and transient notes.
+/// Actions:
+/// - 'add': Add note. Required: content. Optional: ttl_seconds, session_only.
+/// - 'read': Read all active notes.
+/// - 'delete': Delete note. Required: index (1-based integer).
+/// - 'clear': Clear all active notes.
+/// Next steps on error: Ensure required fields for the specific action are supplied.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct StickyNotesTool {
     /// Action to perform: 'add', 'read', 'delete', or 'clear'.
@@ -1093,7 +1099,12 @@ pub enum HandoffMemoAction {
     Clear,
 }
 
-/// Manage handoff memos across sessions (leave, read, clear).
+/// Persistent handoff memos for passing session context to future agents.
+/// Actions:
+/// - 'leave': Post a handoff memo. Required: content. Optional: namespace.
+/// - 'read': Inspect active memos. Optional: namespace.
+/// - 'clear': Clear memos. Optional: namespace, ids.
+/// Next steps on error: Check parameter requirements for 'leave' or 'clear' actions.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct HandoffMemosTool {
     /// Action to perform: 'leave', 'read', or 'clear'.
@@ -1117,7 +1128,15 @@ pub enum TaskAction {
     Verify,
 }
 
-/// Consolidated task management (add, update, delete, list, set_criteria, verify).
+/// Action-oriented task tracking system (add, update, delete, list, set_criteria, verify).
+/// Actions:
+/// - 'add': Create task. Required: title. Optional: description, git_branch, parent_id, dependencies.
+/// - 'update': Update task status. Required: id, status ('pending'|'completed'|'cancelled').
+/// - 'delete': Delete task & subtasks. Required: id.
+/// - 'list': List active tasks. Optional: git_branch, summary_level ('compact'|'detailed'|'full'), max_tokens.
+/// - 'set_criteria': Set acceptance criteria. Required: id, criteria (array of strings).
+/// - 'verify': Verify criteria met. Required: id.
+/// Next steps on error: Check required parameters or call list to verify task IDs.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct TasksTool {
     /// Action to perform: 'add', 'update', 'delete', 'list', 'set_criteria', or 'verify'.
@@ -1126,7 +1145,7 @@ pub struct TasksTool {
     pub id: Option<String>,
     /// Task title (required for 'add').
     pub title: Option<String>,
-    /// Task description (required for 'add').
+    /// Task description (optional for 'add').
     pub description: Option<String>,
     /// New status: 'pending', 'completed', or 'cancelled' (for 'update').
     pub status: Option<String>,
@@ -1152,7 +1171,12 @@ pub enum MilestoneAction {
     List,
 }
 
-/// Consolidated milestone management (add, update, list).
+/// Project milestone management (add, update, list).
+/// Actions:
+/// - 'add': Create milestone. Required: title. Optional: namespace.
+/// - 'update': Update milestone status. Required: id, status.
+/// - 'list': List milestones. Optional: namespace.
+/// Next steps on error: Provide required title for 'add' or id/status for 'update'.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct MilestonesTool {
     /// Action to perform: 'add', 'update', or 'list'.
@@ -1175,7 +1199,12 @@ pub enum PinnedFileAction {
     List,
 }
 
-/// Consolidated pinned files focus management (pin, unpin, list).
+/// Pinned working set files management (pin, unpin, list).
+/// Actions:
+/// - 'pin': Pin file to active focus set. Required: path. Optional: namespace.
+/// - 'unpin': Unpin file from focus set. Required: path. Optional: namespace.
+/// - 'list': List pinned files. Optional: namespace.
+/// Next steps on error: Provide exact file path for pin/unpin operations.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct PinnedFilesTool {
     /// Action to perform: 'pin', 'unpin', or 'list'.
@@ -1196,14 +1225,21 @@ pub enum ContextWorkspaceAction {
     Diff,
 }
 
-/// Consolidated context workspace state management (save, load, list, delete, diff).
+/// Context workspace snapshots management (save, load, list, delete, diff).
+/// Actions:
+/// - 'save': Save current pinned files & task IDs. Required: name. Optional: pinned_files, active_task_ids, namespace.
+/// - 'load': Restore saved workspace state. Required: name. Optional: namespace.
+/// - 'list': List saved context workspaces. Optional: namespace.
+/// - 'delete': Delete saved workspace. Required: name. Optional: namespace.
+/// - 'diff': Compare two context workspaces. Required: name, other_name. Optional: namespace.
+/// Next steps on error: Check workspace name or list existing workspaces first.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ContextWorkspacesTool {
     /// Action to perform: 'save', 'load', 'list', 'delete', or 'diff'.
     pub action: ContextWorkspaceAction,
-    /// Workspace name.
+    /// Workspace name (required for 'save', 'load', 'delete', 'diff').
     pub name: Option<String>,
-    /// Second workspace name (for 'diff').
+    /// Second workspace name (required for 'diff').
     pub other_name: Option<String>,
     /// Pinned file paths (for 'save').
     pub pinned_files: Option<Vec<String>>,
@@ -1221,7 +1257,12 @@ pub enum PrChecklistAction {
     Clear,
 }
 
-/// Consolidated PR checklist management (add, get, clear).
+/// Pre-commit and Pull Request checklist management (add, get, clear).
+/// Actions:
+/// - 'add': Add PR checklist item. Required: description. Optional: namespace.
+/// - 'get': Get PR checklist items. Optional: namespace.
+/// - 'clear': Clear PR checklist. Optional: namespace.
+/// Next steps on error: Provide description for 'add' action.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct PrChecklistTool {
     /// Action to perform: 'add', 'get', or 'clear'.
@@ -1241,14 +1282,20 @@ pub enum SnippetAction {
     Tag,
 }
 
-/// Consolidated reusable code snippets management (store, search, delete, tag).
+/// Syntactically preserved reusable code snippets vault (store, search, delete, tag).
+/// Actions:
+/// - 'store': Store snippet. Required: query (or id) as snippet name. Optional: language, code, description, tags.
+/// - 'search': Search snippets. Optional: query, tags, hybrid (boolean for BM25+vector search).
+/// - 'delete': Delete snippet. Required: id (or query) as snippet name.
+/// - 'tag': Tag snippet. Required: id (or query), tags (array of strings).
+/// Next steps on error: Ensure snippet name/query or id is provided.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SnippetsTool {
     /// Action to perform: 'store', 'search', 'delete', or 'tag'.
     pub action: SnippetAction,
-    /// Snippet ID (required for 'delete', 'tag').
+    /// Snippet ID or name (required for 'delete', 'tag').
     pub id: Option<String>,
-    /// Search query or snippet name.
+    /// Search query or snippet name (required for 'store').
     pub query: Option<String>,
     /// Snippet language (for 'store').
     pub language: Option<String>,
@@ -1270,7 +1317,12 @@ pub enum DecisionAction {
     Delete,
 }
 
-/// Consolidated Architectural Decision Records (ADRs) management (log, query, delete).
+/// Architectural Decision Records (ADRs) log (log, query, delete).
+/// Actions:
+/// - 'log': Record ADR. Required: title. Optional: status, context, decision, consequences, namespace.
+/// - 'query': Search ADRs. Optional: query, namespace.
+/// - 'delete': Remove ADR. Required: id.
+/// Next steps on error: Provide title for 'log' or id for 'delete'.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct DecisionsTool {
     /// Action to perform: 'log', 'query', or 'delete'.
@@ -1279,13 +1331,13 @@ pub struct DecisionsTool {
     pub id: Option<String>,
     /// ADR title (required for 'log').
     pub title: Option<String>,
-    /// ADR status (required for 'log').
+    /// ADR status (for 'log').
     pub status: Option<String>,
-    /// Context & problem statement (required for 'log').
+    /// Context & problem statement (for 'log').
     pub context: Option<String>,
-    /// Decision made (required for 'log').
+    /// Decision made (for 'log').
     pub decision: Option<String>,
-    /// Consequences & tradeoffs (required for 'log').
+    /// Consequences & tradeoffs (for 'log').
     pub consequences: Option<String>,
     /// Search query string (for 'query').
     pub query: Option<String>,
@@ -1301,7 +1353,12 @@ pub enum TechDebtAction {
     List,
 }
 
-/// Consolidated technical debt management (log, resolve, list).
+/// Technical debt backlog management (log, resolve, list).
+/// Actions:
+/// - 'log': Record technical debt. Required: description. Optional: ideal_solution, git_commit, git_branch, symbol_references, line_range, namespace.
+/// - 'resolve': Mark tech debt resolved. Required: id.
+/// - 'list': List tech debt items. Optional: include_resolved, namespace.
+/// Next steps on error: Provide description for 'log' or valid ID for 'resolve'.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct TechDebtTool {
     /// Action to perform: 'log', 'resolve', or 'list'.
@@ -1310,7 +1367,7 @@ pub struct TechDebtTool {
     pub id: Option<String>,
     /// Tech debt description (required for 'log').
     pub description: Option<String>,
-    /// Ideal solution (required for 'log').
+    /// Ideal solution (optional for 'log').
     pub ideal_solution: Option<String>,
     /// Include resolved tech debt items (for 'list').
     pub include_resolved: Option<bool>,
@@ -1336,20 +1393,27 @@ pub enum EnvAction {
     GetDetails,
 }
 
-/// Consolidated environment & infrastructure management (update_fingerprint, read_fingerprint, log_requirement, register, get_details).
+/// Environment requirements, tool fingerprints & infrastructure management.
+/// Actions:
+/// - 'update_fingerprint': Update tool versions. Optional: tool_versions map, namespace.
+/// - 'read_fingerprint': Read current environment fingerprint. Optional: namespace.
+/// - 'log_requirement': Log environment variable requirement. Required: key. Optional: description, is_secret, namespace.
+/// - 'register': Register remote target environment. Required: name. Optional: url, description, requires_vpn, namespace.
+/// - 'get_details': Get full environment details. Optional: namespace.
+/// Next steps on error: Provide key for 'log_requirement' or name for 'register'.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct EnvironmentTool {
-    /// Action to perform.
+    /// Action to perform: 'update_fingerprint', 'read_fingerprint', 'log_requirement', 'register', or 'get_details'.
     pub action: EnvAction,
     /// Map of tool names to versions (for 'update_fingerprint').
     pub tool_versions: Option<std::collections::HashMap<String, String>>,
-    /// Env variable key (for 'log_requirement').
+    /// Env variable key (required for 'log_requirement').
     pub key: Option<String>,
     /// Description (for 'log_requirement', 'register').
     pub description: Option<String>,
     /// Secret flag (for 'log_requirement').
     pub is_secret: Option<bool>,
-    /// Environment name (for 'register').
+    /// Environment name (required for 'register').
     pub name: Option<String>,
     /// Environment URL (for 'register').
     pub url: Option<String>,
@@ -1367,7 +1431,12 @@ pub enum ClipboardAction {
     ToggleWatch,
 }
 
-/// Consolidated OS clipboard management (read, write, toggle_watch).
+/// OS Clipboard management (read, write, toggle_watch).
+/// Actions:
+/// - 'read': Read current clipboard contents.
+/// - 'write': Write content to OS clipboard. Optional: text, html, files, image_path.
+/// - 'toggle_watch': Enable or disable auto-clipboard ingestion. Optional: enabled (bool).
+/// Next steps on error: Provide text/html/files/image_path when calling 'write'.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ClipboardTool {
     /// Action to perform: 'read', 'write', or 'toggle_watch'.