mcp-memory/server/src/tools.rs

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

/// Extracts the current contents of the OS clipboard (text, HTML, files, and image).
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ReadClipboardTool {}

/// Writes contents to the OS clipboard. You can provide any combination of text, HTML, file paths, or an image path.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct WriteClipboardTool {
    /// Optional plain text to write to the clipboard.
    pub text: Option<String>,
    /// Optional HTML to write to the clipboard (useful for rich text pasting).
    pub html: Option<String>,
    /// Optional absolute file paths to write to the clipboard as a Windows File Drop.
    pub files: Option<Vec<String>>,
    /// Optional absolute path to a local image to write to the clipboard.
    pub image_path: Option<String>,
}

/// Create new entities in the knowledge graph. Note: entity_type MUST ALWAYS be PascalCase (e.g. DatabaseTable, McpTool, File).
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct CreateEntitiesTool {
    /// Array of entities to create.
    pub entities: Vec<crate::models::Entity>,
}

/// Create new relations between entities in the knowledge graph. Note: relation_type MUST ALWAYS be snake_case (e.g. depends_on, calls, implements).
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct CreateRelationsTool {
    /// Array of relations to create.
    pub relations: Vec<crate::models::Relation>,
}

#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ObservationInput {
    pub entity_name: String,
    pub contents: Vec<String>,
}

/// Add new observations to existing entities in the knowledge graph.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct AddObservationsTool {
    /// Array of observations to add.
    pub observations: Vec<ObservationInput>,
}

/// Delete entities from the knowledge graph.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct DeleteEntitiesTool {
    /// Array of entity names to delete.
    pub entity_names: Vec<String>,
}

#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct DeleteObservationInput {
    pub entity_name: String,
    pub observations: Vec<String>,
}

/// Delete observations from existing entities.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct DeleteObservationsTool {
    /// Array of observation deletions.
    pub deletions: Vec<DeleteObservationInput>,
}

/// Delete relations between entities.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct DeleteRelationsTool {
    /// Array of relations to delete.
    pub relations: Vec<crate::models::Relation>,
}

/// Read the entire knowledge graph. WARNING: For large graphs, use search_nodes instead to avoid context limits.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ReadGraphTool {
    /// Optional namespace to restrict the read to.
    pub namespace: Option<String>,
    /// Optional token budget cap. Truncates graph outputs to fit within the specified token budget.
    pub max_tokens: Option<usize>,
}

/// Search for entities in the knowledge graph by name or type.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SearchNodesTool {
    /// The search query.
    pub query: String,
    /// Optional namespace to restrict the search to.
    pub namespace: Option<String>,
    /// Limit the number of results to avoid context limit overflow. Defaults to 10.
    pub limit: Option<usize>,
    /// Include the full observations of the matched items. If false, returns only IDs and types (recommended for LLMs to prevent context bloat). Defaults to false.
    pub include_body: Option<bool>,
}

/// Open and retrieve full details of specific nodes in the knowledge graph.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct OpenNodesTool {
    /// Array of entity names to open.
    pub names: Vec<String>,
}

/// Log a significant code change or refactor in the memory system.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct LogCodeChangeTool {
    /// The path of the file that was changed.
    pub file_path: String,
    /// A description of the change.
    pub description: String,
    /// The associated git commit hash, if any.
    pub git_commit: Option<String>,
    /// The associated git branch, if any.
    pub git_branch: Option<String>,
    /// Optional symbol references (e.g. ['MemoryIndex', 'switchTab']) modified in this change.
    pub symbol_references: Option<Vec<String>>,
    /// Optional line range (e.g. 'L123-L145') modified in the target file.
    pub line_range: Option<String>,
}

/// Query recently logged code changes.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct QueryRecentChangesTool {}

/// Generate a visual representation of the knowledge graph.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct VisualizeGraphTool {
    /// Optional search query to filter the graph before visualization.
    pub query: Option<String>,
    /// Optional namespace to restrict the visualization to.
    pub namespace: Option<String>,
}

#[derive(Debug, Deserialize, Serialize, JsonSchema, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum StickyNoteAction {
    Add,
    Read,
    Delete,
    Clear,
}

/// Manage ephemeral sticky notes with TTL (add, read, delete, clear).
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ManageStickyNotesTool {
    /// Action to perform: 'add', 'read', 'delete', or 'clear'.
    pub action: StickyNoteAction,
    /// Content of the sticky note (required for 'add').
    pub content: Option<String>,
    /// 1-indexed position of the sticky note to delete (required for 'delete').
    pub index: Option<usize>,
    /// Optional time-to-live in seconds (for 'add').
    pub ttl_seconds: Option<u64>,
    /// Optional flag to auto-expire the note at the end of the current session (for 'add').
    pub session_only: Option<bool>,
}

/// Add a sticky note for unstructured thoughts or reminders.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct AddStickyNoteTool {
    /// The content of the sticky note.
    pub content: String,
    /// Optional time-to-live in seconds. Automatically expires the note after specified duration.
    pub ttl_seconds: Option<u64>,
    /// Optional flag to auto-expire the note at the end of the current session.
    pub session_only: Option<bool>,
}

/// Read all active sticky notes.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ReadStickyNotesTool {}

/// Delete a specific sticky note by its 1-indexed position.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct DeleteStickyNoteTool {
    /// The 1-indexed position of the sticky note to delete.
    pub index: usize,
}

/// Clear all sticky notes.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ClearStickyNotesTool {}

/// Condense or summarize an entity's observations to reduce size.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct CondenseEntityTool {
    /// The name of the entity to condense.
    pub entity_name: String,
    /// The condensed observations that will replace the existing ones.
    pub summarized_observations: Vec<String>,
}

/// Add a new task to the task tracker.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct AddTaskTool {
    /// The title of the task.
    pub title: String,
    /// A detailed description of the task.
    pub description: String,
    /// The associated git branch, if any.
    pub git_branch: Option<String>,
    /// Optional parent task ID to create a nested sub-task.
    pub parent_id: Option<String>,
    /// Optional list of task IDs this task depends on.
    pub dependencies: Option<Vec<String>>,
}

/// Delete a task and all its children.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct DeleteTaskTool {
    /// The ID of the task to delete.
    pub id: String,
}

/// Update the status of an existing task.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct UpdateTaskStatusTool {
    /// The ID of the task to update.
    pub id: String,
    /// The new status of the task (e.g., 'pending', 'completed', 'cancelled').
    #[schemars(description = "Must be 'pending', 'completed', or 'cancelled'")]
    pub status: String,
}

/// List all currently active tasks.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ListActiveTasksTool {
    /// Optional git branch to filter tasks by.
    pub git_branch: Option<String>,
    /// Optional summary level: 'compact' (IDs and titles), 'detailed', or 'full'. Defaults to 'detailed'.
    pub summary_level: Option<String>,
    /// Optional token budget cap. Truncates results to stay within max_tokens.
    pub max_tokens: Option<usize>,
}

/// Store a reusable code snippet.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct StoreSnippetTool {
    /// The name of the snippet.
    pub name: String,
    /// The programming language of the snippet.
    pub language: String,
    /// The code snippet content.
    pub code: String,
    /// A description of what the snippet does.
    pub description: String,
    /// Optional classification tags (e.g. ['rust', 'async', 'mcp']).
    pub tags: Option<Vec<String>>,
}

/// Add classification tags to an existing code snippet.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct TagSnippetTool {
    /// The name of the snippet to tag.
    pub name: String,
    /// Array of tags (e.g. ['rust', 'async', 'mcp']).
    pub tags: Vec<String>,
}

#[derive(Debug, Deserialize, Serialize, JsonSchema, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum SnippetSearchMode {
    Hybrid,
    Keyword,
    Semantic,
}

/// Search stored code snippets using Hybrid BM25 + Vector ranking or keyword search.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SearchSnippetsTool {
    /// The search query.
    pub query: String,
    /// Search mode: 'hybrid' (BM25 + Semantic Tags), 'keyword', or 'semantic'. Defaults to 'hybrid'.
    pub mode: Option<SnippetSearchMode>,
    /// Optional classification tags to filter by.
    pub tags: Option<Vec<String>>,
    /// Limit the number of results to avoid context limit overflow. Defaults to 10.
    pub limit: Option<usize>,
    /// Include the full code content of the matched items. If false, returns only IDs and descriptions. Defaults to false.
    pub include_body: Option<bool>,
}

/// Delete a stored code snippet.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct DeleteSnippetTool {
    /// The name of the snippet to delete.
    pub name: String,
}

#[derive(Debug, Deserialize, Serialize, JsonSchema, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum SubgraphFormat {
    Json,
    MarkdownTree,
}

/// Extract a multi-hop neighborhood subgraph around a specific root entity node as JSON or Markdown topology tree.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct GetSubgraphTool {
    /// The root entity name to start the subgraph search from.
    pub root_entity: Option<String>,
    /// Legacy alias for root_entity.
    pub root_node: Option<String>,
    /// Maximum search depth (hops). Defaults to 2.
    pub depth: Option<u32>,
    /// Output format: 'json' (raw entities and relations) or 'markdown_tree' (compact topology tree). Defaults to 'json'.
    pub format: Option<SubgraphFormat>,
    /// Optional namespace filter.
    pub namespace: Option<String>,
    /// Target maximum token length for generated summary when format is 'markdown_tree'. Defaults to 1000.
    pub max_tokens: Option<usize>,
}

/// Search historical error fixes using keyword search or semantic vector similarity and return matching solutions.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SuggestErrorFixTool {
    /// The exact stack trace or error signature.
    pub stack_trace: String,
    /// Maximum number of suggested fixes to return. Defaults to 3.
    pub limit: Option<usize>,
}

#[derive(Debug, Deserialize, Serialize, JsonSchema, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum CheckpointAction {
    Create,
    Restore,
    List,
    Delete,
}

/// Save, restore, list, or delete point-in-time memory state snapshot checkpoints.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ManageCheckpointTool {
    /// Action to perform: 'create', 'restore', 'list', or 'delete'.
    pub action: CheckpointAction,
    /// Unique name or ID for the snapshot checkpoint.
    pub name_or_id: Option<String>,
    /// Optional description of why this checkpoint was created.
    pub description: Option<String>,
    /// Optional namespace filter.
    pub namespace: Option<String>,
}

/// Save a named memory snapshot checkpoint before risky operations or subagent invocations.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct CheckpointStateTool {
    /// The unique name for this state snapshot checkpoint.
    pub name: String,
    /// Optional description of why this checkpoint was created.
    pub description: Option<String>,
}

/// Restore a previously saved memory snapshot checkpoint.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct RestoreStateTool {
    /// The name of the checkpoint to restore.
    pub name: String,
}

/// Log an architectural decision record (ADR).
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct LogDecisionTool {
    /// The title of the decision.
    pub title: String,
    /// The context or problem requiring a decision.
    pub context: String,
    /// The decision made.
    pub decision: String,
    /// The consequence of the decision.
    pub consequence: String,
    /// The ID of an older ADR this decision supersedes, if any.
    pub supersedes: Option<String>,
}

/// Query architectural decision records.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct QueryDecisionsTool {
    /// Optional search query.
    pub query: Option<String>,
    /// Limit the number of results to avoid context limit overflow. Defaults to 5.
    pub limit: Option<usize>,
    /// Include the full body/content of the matched ADRs. If false, returns only titles and IDs (recommended for LLMs to prevent context bloat). Defaults to false.
    pub include_body: Option<bool>,
}

/// Delete an architectural decision record (ADR).
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct DeleteDecisionTool {
    /// The ID of the decision to delete.
    pub id: String,
}

/// Merge two entities in the knowledge graph into one.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct MergeEntitiesTool {
    /// The name of the entity to merge from (will be deleted).
    pub source_entity: String,
    /// The name of the entity to merge into.
    pub target_entity: String,
}

/// Find orphaned entities (entities without any relations) in the graph.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct FindOrphansTool {}

/// Record a user preference or behavior to adapt future interactions.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct LearnPreferenceTool {
    /// The key for the preference.
    pub key: String,
    /// The value of the preference.
    pub value: String,
}

/// Read all learned user preferences.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ReadPreferencesTool {}

/// Log a complex error and its fix for future reference.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct LogErrorFixTool {
    /// The error signature or stack trace.
    pub signature: String,
    /// The solution applied to fix the error.
    pub solution: String,
    /// The associated git commit hash, if any.
    pub git_commit: Option<String>,
    /// The associated git branch, if any.
    pub git_branch: Option<String>,
    /// Optional symbol references (e.g. ['MemoryIndex', 'switchTab']) associated with the error.
    pub symbol_references: Option<Vec<String>>,
    /// Optional line range (e.g. 'L123-L145') associated with the error.
    pub line_range: Option<String>,
}

/// Search historical error fixes using keyword query or stack trace vector similarity.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SearchErrorFixesTool {
    /// The search query string.
    pub query: Option<String>,
    /// Exact stack trace or error signature for vector cosine matching.
    pub stack_trace: Option<String>,
    /// Limit the number of results to avoid context limit overflow. Defaults to 5.
    pub limit: Option<usize>,
    /// Include the full solution details. If false, returns only error signatures. Defaults to false.
    pub include_body: Option<bool>,
}

/// Pin a file to keep it explicitly in the context workspace.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct PinFileTool {
    /// The namespace to pin the file in.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// The absolute path of the file to pin.
    pub file_path: String,
    /// The associated git branch, if any.
    pub git_branch: Option<String>,
}

/// Unpin a file from the context workspace.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct UnpinFileTool {
    /// The namespace the file is pinned in.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// The absolute path of the file to unpin.
    pub file_path: String,
}

/// List all currently pinned files.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ListPinnedFilesTool {
    /// Optional namespace to filter by.
    pub namespace: Option<String>,
    /// Optional git branch to filter by.
    pub git_branch: Option<String>,
}

/// Add a summary of the current session.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct AddSessionSummaryTool {
    /// The summary content.
    pub summary: String,
    /// The namespace to add the summary to.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
}

/// Get a timeline of major project events.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
#[allow(dead_code)]
pub struct GetProjectTimelineTool {
    /// Optional namespace to restrict the timeline to.
    pub namespace: Option<String>,
}

/// Leave a memo for the next session or agent.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct LeaveHandoffMemoTool {
    /// The content of the memo.
    pub content: String,
    /// The namespace to leave the memo in.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
}

/// Read pending handoff memos.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ReadHandoffMemosTool {
    /// Optional namespace to restrict the read to.
    pub namespace: Option<String>,
}

/// Clear handoff memos after reading.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ClearHandoffMemosTool {
    /// Array of memo IDs to clear.
    pub ids: Vec<String>,
}

/// Update the environment fingerprint (e.g., OS, tool versions).
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct UpdateEnvFingerprintTool {
    /// The namespace to update the fingerprint for.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// A map of tool names to their versions.
    pub tool_versions: std::collections::HashMap<String, String>,
}

/// Read the environment fingerprint.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ReadEnvFingerprintTool {
    /// The namespace to read the fingerprint for.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
}

/// Log a required environment variable or configuration.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct LogEnvRequirementTool {
    /// The namespace.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// The environment variable key (e.g., DATABASE_URL).
    pub key: String,
    /// A description of what the variable is used for.
    pub description: String,
    /// Whether the variable contains a secret.
    pub is_secret: bool,
}

/// Add a new milestone.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct AddMilestoneTool {
    /// The title of the milestone.
    pub title: String,
    /// The namespace for the milestone.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
}

/// Update the status of a milestone.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct UpdateMilestoneTool {
    /// The ID of the milestone to update.
    pub id: String,
    /// The new status (e.g., 'active', 'completed').
    pub status: String,
}

/// List all milestones.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ListMilestonesTool {
    /// Optional namespace to restrict the list to.
    pub namespace: Option<String>,
}

/// Generate a standup report for a specific time window.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct GenerateStandupReportTool {
    /// The namespace to generate the report for.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// The number of hours to look back for activity.
    pub hours_lookback: u64,
}

/// Register a new infrastructure environment.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct RegisterEnvironmentTool {
    /// The namespace.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// The name of the environment (e.g., 'staging', 'prod').
    pub name: String,
    /// The URL or connection string for the environment.
    pub url: String,
    /// A description of the environment.
    pub description: String,
    /// Whether a VPN is required to access the environment.
    pub requires_vpn: bool,
}

/// Get details about a registered environment.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct GetEnvironmentDetailsTool {
    /// The namespace to retrieve details for.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
}

/// Add an item to the PR checklist.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct AddPrChecklistItemTool {
    /// The namespace.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// The description of the checklist item.
    pub description: String,
}

/// Get the PR checklist.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct GetPrChecklistTool {
    /// The namespace.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
}

/// Clear the PR checklist.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ClearPrChecklistTool {
    /// The namespace.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
}

/// Log a technical debt record.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct LogTechDebtTool {
    /// The namespace.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// A description of the technical debt.
    pub description: String,
    /// The ideal solution to resolve the debt.
    pub ideal_solution: String,
    /// The associated git commit hash, if any.
    pub git_commit: Option<String>,
    /// The associated git branch, if any.
    pub git_branch: Option<String>,
    /// Optional symbol references (e.g. ['MemoryIndex', 'switchTab']) associated with the tech debt.
    pub symbol_references: Option<Vec<String>>,
    /// Optional line range (e.g. 'L123-L145') associated with the tech debt.
    pub line_range: Option<String>,
}

/// Resolve a technical debt record.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ResolveTechDebtTool {
    /// The ID of the technical debt record to resolve.
    pub id: String,
}

/// List technical debt records.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ListTechDebtTool {
    /// The namespace.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// Whether to include resolved technical debt in the results.
    pub include_resolved: bool,
    /// Optional summary level: 'compact' (IDs and descriptions), 'detailed', or 'full'. Defaults to 'detailed'.
    pub summary_level: Option<String>,
    /// Optional token budget cap. Truncates results to stay within max_tokens.
    pub max_tokens: Option<usize>,
}

/// Save the current context workspace.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SaveContextWorkspaceTool {
    /// The namespace for the workspace.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// The name to save the workspace as.
    pub name: String,
    /// Array of pinned file paths.
    pub pinned_files: Vec<String>,
    /// Array of active task IDs.
    pub active_task_ids: Vec<String>,
}

/// Load a saved context workspace.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct LoadContextWorkspaceTool {
    /// The namespace of the workspace.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// The name of the workspace to load.
    pub name: String,
}

/// List all saved context workspaces.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ListContextWorkspacesTool {
    /// The namespace to list workspaces for.
    pub namespace: Option<String>,
}

/// Delete a saved context workspace.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct DeleteContextWorkspaceTool {
    /// The namespace of the workspace.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// The name of the workspace to delete.
    pub name: String,
}

/// Search across all memory stores (Graph, Tasks, Snippets, ADRs, Error Fixes, Tech Debt) using Hybrid Reciprocal Rank Fusion (BM25 + Dense Vectors).
/// Highly recommended for discovery. Supports Lucene query syntax.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct OmniSearchTool {
    /// The search query. Supports Lucene syntax (e.g., 'title:"auth" AND status:open').
    pub query: String,
    /// Optional namespace to restrict the search to.
    pub namespace: Option<String>,
    /// Limit the number of results per category to avoid context limit overflow. Defaults to 5.
    pub limit: Option<usize>,
    /// Include the full body/content of the matched items. If false, returns only IDs and titles (recommended for LLMs to prevent context bloat). Defaults to false.
    pub include_body: Option<bool>,
    /// Optional token budget cap. Dynamically caps and truncates search results to stay within max_tokens.
    pub max_tokens: Option<usize>,
}

/// Get a health digest of the project.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct GetProjectHealthTool {
    /// The namespace to get health for.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
}

/// Traverse the knowledge graph to find a path between two entities.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct QueryGraphPathTool {
    /// The starting entity name.
    pub start_node: String,
    /// The ending entity name.
    pub end_node: String,
    /// Optional maximum depth to search.
    pub max_depth: Option<u32>,
}
/// Define a strict checklist of acceptance criteria for a given task or feature before starting work.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SetAcceptanceCriteriaTool {
    pub task_title: String,
    pub criteria: Vec<String>,
}
/// Mark a previously defined acceptance criteria as met by providing cryptographic-like proof.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct VerifyAcceptanceCriteriaTool {
    pub task_id: String,
    pub criteria: String,
    pub proof: String,
}

/// Audit the knowledge graph to detect orphaned entities, compute name similarity for potential duplicate merges, and optionally auto-prune orphans.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SweepGraphHealthTool {
    /// Optional flag to automatically prune orphaned nodes with 0 relations. Defaults to false.
    pub auto_prune_orphans: Option<bool>,
    /// Minimum string similarity threshold (0.0 to 1.0) to report duplicate entity pairs. Defaults to 0.8.
    pub similarity_threshold: Option<f32>,
}

/// Trace the causal provenance and historical lineage linking a task, ADR, git commit, code change, or error fix.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct QueryLineageTool {
    /// The task ID, file path, symbol name, or git commit to query lineage for.
    pub query: String,
}

/// Topological task resolver that returns unblocked, ready-to-run active tasks.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct GetNextActionableTasksTool {
    /// Optional git branch filter.
    pub git_branch: Option<String>,
    /// Limit the number of actionable tasks returned. Defaults to 5.
    pub limit: Option<usize>,
}

/// Log a structured diagnostic hypothesis, tested evidence, and status during problem solving.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct LogHypothesisTool {
    /// Optional task ID associated with this hypothesis.
    pub task_id: Option<String>,
    /// The diagnostic hypothesis or potential root cause.
    pub hypothesis: String,
    /// Status: 'unverified', 'verified', or 'rejected'. Defaults to 'unverified'.
    pub status: Option<String>,
    /// Evidence or test results supporting or disproving the hypothesis.
    pub evidence: Option<String>,
}

/// Query previously logged diagnostic hypotheses and test results.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct QueryHypothesesTool {
    /// Optional task ID to filter hypotheses for.
    pub task_id: Option<String>,
    /// Optional search query text.
    pub query: Option<String>,
}

/// Compare two saved context workspaces and return a structured diff of pinned files, active tasks, and metadata.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct DiffContextWorkspacesTool {
    /// The name of the first context workspace.
    pub workspace_a: String,
    /// The name of the second context workspace.
    pub workspace_b: String,
}

#[cfg(test)]
mod tests {
    use super::*;
    use schemars::schema_for;

    #[test]
    fn test_schema_extraction_includes_descriptions() {
        let schema = schema_for!(SetAcceptanceCriteriaTool);
        let schema_json = serde_json::to_value(&schema).unwrap();

        let desc = schema_json
            .get("description")
            .and_then(|d| d.as_str())
            .unwrap_or("");
        assert!(
            desc.contains("Define a strict checklist of acceptance criteria"),
            "Schema should include struct docstring as description"
        );

        let schema2 = schema_for!(LogCodeChangeTool);
        let schema2_json = serde_json::to_value(&schema2).unwrap();
        let props = schema2_json.get("properties").expect("Missing properties");

        let file_path_prop = props.get("file_path").expect("Missing file_path property");
        let field_desc = file_path_prop
            .get("description")
            .and_then(|d| d.as_str())
            .unwrap_or("");
        assert!(
            field_desc.contains("The path of the file that was changed"),
            "Schema should include field docstring as description"
        );
    }
}
/// Get the active worktree context, including branch name, modified files, and a truncated git diff.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct GetActiveWorktreeContextTool {}
/// Tail a specific log file in the background so it can be queried later.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct WatchProcessLogsTool {
    pub file_path: String,
}

/// Get the recent logs from a watched file.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct GetRecentLogsTool {
    pub file_path: String,
}

/// Enable or disable clipboard watch mode (auto-ingesting into StickyNotes).
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ToggleClipboardWatchModeTool {
    pub enable: bool,
}
/// Read a file and return only its AST skeleton (Imports, Structs, Enums, Traits, Functions)
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ReadFileSkeletonTool {
    pub file_path: String,
}
/// Replace a specific AST node in a file (robust structural editing). Use this instead of regex or line-based string replacement to prevent indentation bugs and matching failures.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ReplaceAstNodeTool {
    pub file_path: String,
    pub node_type: String, // e.g., "function_item", "impl_item"
    pub node_name: String, // e.g., "execute"
    pub new_content: String,
}

/// Semantic code search using local vector embeddings. Use this conceptual search instead of raw regex (grep) when trying to locate abstract logic or exploring new patterns.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SemanticCodeSearchTool {
    pub query: String,
    pub directory: Option<String>,
}

/// Get a bird's-eye view of directory architecture. Use this when first exploring a new repository to get a summary of what each file is responsible for, instead of blindly reading files.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ReadDirectoryArchitectureTool {
    pub directory: String,
}

/// Create a point-in-time state snapshot of memory stores for safety.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct CreateSnapshotTool {
    pub description: String,
    pub namespace: Option<String>,
}

/// Restore a point-in-time state snapshot of memory stores.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct RestoreSnapshotTool {
    pub snapshot_id: String,
}

#[derive(Debug, Deserialize, Serialize, JsonSchema, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum SubagentNamespaceAction {
    Create,
    Condense,
    Purge,
}

/// Manage isolated memory namespaces for subagent sessions (create, condense/promote, or purge).
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ManageSubagentNamespaceTool {
    /// Action to perform: 'create', 'condense', or 'purge'.
    pub action: SubagentNamespaceAction,
    /// Subagent namespace ID.
    pub subagent_id: String,
    /// For 'condense': whether to auto-purge the subagent namespace after promotion. Defaults to true.
    pub purge_after_promotion: Option<bool>,
}

/// Create an isolated memory namespace for a subagent session.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct CreateSubagentNamespaceTool {
    pub subagent_id: String,
}

/// Purge an isolated subagent memory namespace after session completion.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct PurgeSubagentNamespaceTool {
    pub subagent_id: String,
}

/// Find all source locations and AST chunks where a specific symbol (function, struct, method, type) is referenced or called.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct FindSymbolReferencesTool {
    /// The symbol name (e.g. 'MemoryState', 'handle_search', 'AppError').
    pub symbol: String,
    /// Optional maximum number of reference locations to return. Defaults to 10.
    pub limit: Option<usize>,
}

/// Find all caller functions or methods that invoke a specified target function or method name.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct GetCallersTool {
    /// The target function or method name (e.g. 'generate_embeddings_async', 'keyword_search').
    pub function_name: String,
    /// Optional maximum number of callers to return. Defaults to 10.
    pub limit: Option<usize>,
}

/// Query git commit history, diffs, and change ledger entries using keyword or semantic search.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct QueryGitDiffsTool {
    /// Search query (e.g. 'deploy-server', 'shutdown', 'debounce', 'rename trick').
    pub query: String,
    /// Optional maximum number of commit diff entries to return. Defaults to 5.
    pub limit: Option<usize>,
}

/// Promote a transient sticky note or active task observation into a permanent Knowledge Graph entity.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct PromoteToEntityTool {
    /// Note text or content to promote.
    pub content: String,
    /// Target entity name to create or merge into.
    pub entity_name: String,
    /// Entity type (e.g. 'Component', 'Decision', 'BugFix', 'Architecture').
    pub entity_type: String,
    /// Optional namespace. Defaults to 'default'.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
}

/// Analyze the potential downstream breaking impact of modifying a function, struct, or file across AST callers and Knowledge Graph relations.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct AnalyzeImpactTool {
    /// Target function, struct, or symbol name (e.g. 'MemoryState', 'execute', 'AppError').
    pub target_symbol: String,
    /// Optional file path.
    pub file_path: Option<String>,
}

/// Auto-condense a subagent's memory namespace and promote its high-value entities/relations to the global Knowledge Graph.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct CondenseSubagentNamespaceTool {
    /// The subagent namespace ID to consolidate.
    pub subagent_id: String,
    /// Whether to auto-purge the subagent namespace after promotion. Defaults to true.
    pub purge_after_promotion: Option<bool>,
}

/// Get a consolidated 1-page executive summary of current active branch, active task, pinned files, open tech debt, and diagnostic hypotheses in 1 turn.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct GetPreflightContextTool {
    /// Optional namespace. Defaults to 'default'.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
    /// Optional git branch to filter context for.
    pub git_branch: Option<String>,
}

/// Inspect Knowledge Graph entities, observations, and tech debt symbol/line references against current files on disk and AST, flagging and healing stale or broken pointers.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ResolveStaleSymbolsTool {
    /// Optional entity or file path to check. If omitted, checks all graph entities and tech debts.
    pub target: Option<String>,
    /// Whether to automatically update or remove broken references. Defaults to true.
    pub auto_heal: Option<bool>,
}

/// Generate a compact, LLM-optimized Markdown topology or summary of a graph component capped within a strict token budget.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SummarizeSubgraphTool {
    /// The root entity name to center the summary on (e.g. 'MemoryState', 'ServerRouter').
    pub root_entity: String,
    /// Search depth from root entity. Defaults to 2.
    pub depth: Option<usize>,
    /// Target maximum token length for the generated summary. Defaults to 1000.
    pub max_tokens: Option<usize>,
}

/// Broadcast a real-time signal or status transition to other subagents on the inter-agent signal bus.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct BroadcastAgentSignalTool {
    /// Sender agent ID or role (e.g. 'PrePushAuditor', 'MemoryLibrarian').
    pub sender: String,
    /// Signal type or event category (e.g. 'AUDIT_PASSED', 'REPRODUCER_READY', 'TESTS_FAILED').
    pub signal_type: String,
    /// JSON or text payload containing event details or artifact URIs.
    pub payload: String,
    /// Optional Time-To-Live in seconds for the signal. Defaults to 3600 (1 hour).
    pub ttl_seconds: Option<u64>,
}

/// Query active inter-agent signals published by subagents on the inter-agent signal bus.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct QueryAgentSignalsTool {
    /// Optional sender filter (e.g. 'PrePushAuditor').
    pub sender: Option<String>,
    /// Optional signal_type filter (e.g. 'AUDIT_PASSED').
    pub signal_type: Option<String>,
    /// Optional limit on returned signals. Defaults to 20.
    pub limit: Option<usize>,
}

/// Trigger an automated context checkpoint, summarizing active tasks, hypotheses, recent commits, and open tech debt into a permanent HandoffMemo.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct AutoSessionCheckpointTool {
    /// Author or agent ID creating the checkpoint. Defaults to 'AutoCheckpoint'.
    pub author: Option<String>,
    /// Optional namespace. Defaults to 'default'.
    #[serde(default = "crate::models::default_namespace")]
    pub namespace: String,
}

/// Hybrid BM25 & semantic tag search across stored code snippets, returning ranked code patterns with relevance scores.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SearchSnippetsHybridTool {
    /// Query string (e.g. 'rate limiter', 'websocket client', 'shutdown poll').
    pub query: String,
    /// Optional tags to filter by.
    pub tags: Option<Vec<String>>,
    /// Maximum number of snippets to return. Defaults to 10.
    pub limit: Option<usize>,
}