refactor: standardize function description format with call/do-not-use sections

Restructure all AI function descriptions to use consistent "Call this function:" and "Do NOT use this function:" sections for improved clarity and scannability.

AIClasses/FunctionDefinitions/Functions/AskUserQuestionExecution.ts

@@ -4,16 +4,16 @@ import type { IAIFunctionDefinition } from "../IAIFunctionDefinition";
 export const AskUserQuestionExecution: IAIFunctionDefinition = {
   name: AIFunction.AskUserQuestionExecution,
   description: `Asks the user a question during plan execution and waits for their response.
-Use this function when you encounter situations during plan execution that require user input or decisions.
 This allows interactive execution where unexpected circumstances or ambiguous situations can be resolved with user feedback.
 
-Common use cases:
-- Encountering unexpected file states or content that wasn't anticipated in the plan
-- Discovering conflicts or duplicates that require user decision
-- Handling errors or edge cases where multiple recovery strategies exist
-- Confirming destructive or irreversible operations before proceeding
-- Requesting missing information that only becomes apparent during execution
-- Choosing between alternatives discovered while processing`,
+Call this function:
+- When you encounter situations during plan execution that require user input or decisions
+- When encountering unexpected file states or content that wasn't anticipated in the plan
+- When discovering conflicts or duplicates that require user decision
+- When handling errors or edge cases where multiple recovery strategies exist
+- When confirming destructive or irreversible operations before proceeding
+- When requesting missing information that only becomes apparent during execution
+- When choosing between alternatives discovered while processing`,
   parameters: {
     type: "object",
     properties: {

AIClasses/FunctionDefinitions/Functions/AskUserQuestionPlanning.ts

@@ -4,14 +4,14 @@ import type { IAIFunctionDefinition } from "../IAIFunctionDefinition";
 export const AskUserQuestionPlanning: IAIFunctionDefinition = {
   name: AIFunction.AskUserQuestionPlanning,
   description: `Asks the user a question during the planning phase and waits for their response.
-Use this function when you need clarification, user input, or decisions while creating the plan.
 This allows interactive planning where user feedback shapes the plan before it's submitted.
 
-Common use cases:
-- Clarifying ambiguous requirements before creating the plan
-- Getting user preferences when multiple valid approaches exist for the plan
-- Asking which files or folders the user wants to target
-- Confirming assumptions about the user's intent before planning`,
+Call this function:
+- When you need clarification or user input while creating the plan
+- When ambiguous requirements need to be clarified before creating the plan
+- When getting user preferences because multiple valid approaches exist for the plan
+- When asking which files or folders the user wants to target
+- When confirming assumptions about the user's intent before planning`,
 
   parameters: {
     type: "object",

AIClasses/FunctionDefinitions/Functions/CompleteStep.ts

@@ -3,11 +3,16 @@ import type { IAIFunctionDefinition } from "../IAIFunctionDefinition";
 
 export const CompleteStep: IAIFunctionDefinition = {
   name: AIFunction.CompleteStep,
-  description: `Signals that plan execution should proceed to the next step without modification. 
-   
-- Use this tool when the most recent step completed successfully and its results align with the plan's expectations.
-- This is the appropriate choice when everything is working as intended and no course correction is needed.
-- Do NOT use this if there were any failures, unexpected results, or if the plan needs adjustment based on new information.`,
+  description: `Signals that plan execution should proceed to the next step without modification.
+
+Call this function:
+- When the most recent step completed successfully and its results align with the plan's expectations
+- When everything is working as intended and no course correction is needed
+
+Do NOT use this function:
+- When there were any failures or unexpected results
+- When the plan needs adjustment based on new information
+- When you need to perform more work on the current step`,
   parameters: {
     type: "object",
     properties: {

AIClasses/FunctionDefinitions/Functions/CompleteTask.ts

@@ -3,15 +3,17 @@ import type { IAIFunctionDefinition } from "../IAIFunctionDefinition";
 
 export const CompleteTask: IAIFunctionDefinition = {
     name: AIFunction.CompleteTask,
-    description: `Signals that you have finished executing all of your assigned instructions. This function MUST be called exactly once, only after you have fully completed or can no longer make progress on everything you were asked to do.
-  
-  Do NOT call this function:
-  - After completing individual actions or sub-tasks
-  - While you still have remaining work from your instructions
-  
-  Call this function only when:
-  - You have completed everything you were instructed to do (success: true)
-  - You have encountered a blocker that prevents further progress on your instructions (success: false)`,
+    description: `Signals that you have finished executing all of your assigned instructions.
+
+This function MUST be called exactly once, only after you have fully completed or can no longer make progress on everything you were asked to do.
+
+Call this function:
+- When you have completed everything you were instructed to do (success: true)
+- When you have encountered a blocker that prevents further progress on your instructions (success: false)
+
+Do NOT use this function:
+- After completing individual actions or sub-tasks
+- While you still have remaining work from your instructions`,
     parameters: {
       type: "object",
       properties: {

AIClasses/FunctionDefinitions/Functions/ContinuePlanExecution.ts

@@ -5,11 +5,11 @@ export const ContinuePlanExecution: IAIFunctionDefinition = {
     name: AIFunction.ContinuePlanExecution,
     description: `Signals that you need to perform additional actions to complete the current step.
 
-**When to use this tool:**
+Call this function:
 - When the current step requires multiple function calls to complete
 - When you need to perform more work before the step can be marked as complete
 
-**When NOT to use this tool:**
+Do NOT use this function:
 - When you have finished all work for the current step - mark the step as complete instead`,
     parameters: {
         type: "object",

AIClasses/FunctionDefinitions/Functions/CreatePlan.ts

@@ -7,20 +7,20 @@ export const ExecuteWorkflow: IAIFunctionDefinition = {
 
 When called, this tool hands off the goal to a planning and execution engine that operates independently. The system will analyze the goal, create a detailed plan, execute each step programmatically, handle any necessary replanning if steps fail, and return the final outcome. You do not need to manage or monitor the execution — the result will be returned to you once the workflow completes or if it fails irrecoverably.
 
-This is the appropriate choice when:
-- The user's request involves multiple coordinated operations or phases
-- The task requires vault exploration, analysis, or search before acting
-- The optimal approach is unclear and benefits from systematic planning
-- Work spans multiple vault areas or requires sequential dependencies
-- The task is substantial enough that delegating execution is more efficient than step-by-step guidance
+The workflow system specializes in breaking down complex tasks, conducting exploratory searches, managing dependencies, recovering from failures through replanning, and coordinating multi-step operations to completion.
 
-Do NOT use this tool for:
-- Simple, single-step operations you can perform directly (e.g., reading one file, creating one note)
-- Tasks where you already know the exact steps and can execute them yourself
-- Requests that require real-time user interaction or clarification during execution
-- Operations where partial results need to be shown to the user incrementally
+Call this function:
+- When the user's request involves multiple coordinated operations or phases
+- When the task requires vault exploration, analysis, or search before acting
+- When the optimal approach is unclear and benefits from systematic planning
+- When work spans multiple vault areas or requires sequential dependencies
+- When the task is substantial enough that delegating execution is more efficient than step-by-step guidance
 
-The workflow system specializes in breaking down complex tasks, conducting exploratory searches, managing dependencies, recovering from failures through replanning, and coordinating multi-step operations to completion.`,
+Do NOT use this function:
+- For simple, single-step operations you can perform directly (e.g., reading one file, creating one note)
+- When you already know the exact steps and can execute them yourself
+- For requests that require real-time user interaction or clarification during execution
+- When partial results need to be shown to the user incrementally`,
   parameters: {
     type: "object",
     properties: {

AIClasses/FunctionDefinitions/Functions/DeleteVaultFiles.ts

@@ -3,12 +3,20 @@ import type { IAIFunctionDefinition } from "../IAIFunctionDefinition";
 
 export const DeleteVaultFiles: IAIFunctionDefinition = {
     name: AIFunction.DeleteVaultFiles,
-    description: `Permanently removes files and folders from the vault. Use this when the user explicitly
-requests to delete file(s) or folder(s), when a file or folder is no longer needed, or when removing outdated
-content. IMPORTANT: This action is irreversible - always confirm the exact file path(s)
-before deletion. Prefer archiving or moving files to a trash folder over permanent
-deletion when uncertain. Only call this after verifying the file(s) exist and confirming
-the user's intent to delete.`,
+    description: `Permanently removes files and folders from the vault.
+
+IMPORTANT: This action is irreversible - always confirm the exact file path(s) before deletion.
+
+Call this function:
+- When the user explicitly requests to delete file(s) or folder(s)
+- When a file or folder is no longer needed and should be permanently removed
+- When removing outdated content that has been confirmed for deletion
+- After verifying the file(s) exist and confirming the user's intent to delete
+
+Do NOT use this function:
+- When uncertain about whether to delete
+- Before reading the files to confirm their contents
+- When the user might want to recover the files later - archive them instead`,
     parameters: {
         type: "object",
         properties: {

AIClasses/FunctionDefinitions/Functions/ListVaultFiles.ts

@@ -5,11 +5,16 @@ export const ListVaultFiles: IAIFunctionDefinition = {
     name: AIFunction.ListVaultFiles,
     description: `Lists files and directories in the vault's directory structure.
 Returns a structured view of the vault's organization including file names, paths, and directory hierarchy.
-Use this function when you need to:
-- List files in a specific directory or the entire vault
-- Get an overview of vault organization and structure
-- Browse available files and folders
-- Understand how notes are organized`,
+
+Call this function:
+- When you need to list files in a specific directory or the entire vault
+- When getting an overview of vault organization and structure
+- When browsing available files and folders
+- When understanding how notes are organized
+
+Do NOT use this function:
+- When you need to search for specific content within files (use SearchVaultFiles instead)
+- When you already know the exact file path to read (use ReadVaultFiles instead)`,
     parameters: {
       type: "object",
       properties: {

AIClasses/FunctionDefinitions/Functions/MoveVaultFiles.ts

@@ -4,12 +4,16 @@ import type { IAIFunctionDefinition } from "../IAIFunctionDefinition";
 export const MoveVaultFiles: IAIFunctionDefinition = {
     name: AIFunction.MoveVaultFiles,
     description: `Moves or renames one or more files within the vault to new locations.
-Use this when reorganizing vault structure, moving files between folders, renaming
-files for better organization, or consolidating related notes into appropriate
-directories. This operation preserves file content while updating paths and names.
-If renaming within the same folder, source and destination folders will be identical
-with only the filename changing. For safety, consider reading files first to confirm you're
-moving the correct content, especially when performing batch operations.`,
+This operation preserves file content while updating paths and names.
+
+Call this function:
+- When reorganizing vault structure and moving files between folders
+- When renaming files for better organization (source and destination folders identical, only filename changes)
+- When consolidating related notes into appropriate directories
+- When archiving files to a different location instead of deleting them
+
+Do NOT use this function:
+- Before reading files to confirm you're moving the correct content (especially for batch operations)`,
     parameters: {
         type: "object",
         properties: {

AIClasses/FunctionDefinitions/Functions/PatchVaultFile.ts

@@ -7,13 +7,18 @@ export const PatchVaultFile: IAIFunctionDefinition = {
 
 This tool modifies specific sections of a file by matching exact content and replacing it with new content. It works by performing a direct string match and replace operation.
 
-**When to use this tool:**
-- Making small, targeted edits to large files (a few lines changed)
-- Edits in the middle of a file where you have clear surrounding context
-- Simple line additions, deletions, or replacements with minimal changes
+**CRITICAL:** The content to match must be EXACTLY as it appears in the file - including all whitespace, indentation, blank lines, and line breaks.
+
+Call this function:
+- When making small, targeted edits to large files (a few lines changed)
+- When making edits in the middle of a file where you have clear surrounding context
+- When making simple line additions, deletions, or replacements with minimal changes
 - When you know the exact content that needs to be changed
 
-**CRITICAL:** The content to match must be EXACTLY as it appears in the file - including all whitespace, indentation, blank lines, and line breaks.`,
+Do NOT use this function:
+- When rewriting most or all of a file's content
+- When you haven't read the file first to know the exact content to match
+- When the match might be ambiguous (appears multiple times in the file)`,
     parameters: {
         type: "object",
         properties: {

AIClasses/FunctionDefinitions/Functions/ReadVaultFiles.ts

@@ -9,15 +9,19 @@ export const ReadVaultFiles: IAIFunctionDefinition = {
 and PDFs. When users ask about image or PDF files, USE THIS FUNCTION to
 read them—do not claim you cannot see images.**
 
-Call this when you need to access existing file content to answer questions,
-provide summaries, verify information, or gather context before making updates.
-Use proactively before updating files to understand current content and avoid
-data loss. Essential for any operation that references or builds upon existing notes.
+Supports text files (.md, .txt, etc.), images (.png, .jpg, .jpeg, etc), and PDFs (.pdf).
 
-For multiple files: Use when comparing content, gathering related context, or
-analyzing information across several documents.
+Call this function:
+- When you need to access existing file content to answer questions
+- When providing summaries or verifying information from specific files
+- Before updating files to understand current content and avoid data loss
+- When comparing content or gathering related context across multiple files
+- When analyzing information across several documents
+- When users ask about images or PDFs (this function allows you to see them)
 
-Supports text files (.md, .txt, etc.), images (.png, .jpg, .jpeg, etc), and PDFs (.pdf).`,
+Do NOT use this function:
+- When you need to search for files by content - search instead
+- When you need to browse directory structure - list directory contents instead`,
   parameters: {
     type: "object",
     properties: {

AIClasses/FunctionDefinitions/Functions/Replan.ts

@@ -5,11 +5,15 @@ export const Replan: IAIFunctionDefinition = {
   name: AIFunction.Replan,
   description: `Signals that the current plan needs to be revised before execution can continue.
 
-- A planned step fails and you need an alternative approach
-- Execution reveals the original plan was based on incorrect assumptions
-- The user provides new information mid-execution
-- You've completed part of the plan but the remaining steps are no longer valid
-- Do NOT use this if the failure is unrecoverable or if the goal is no longer achievable.`,
+Call this function:
+- When a planned step fails and you need an alternative approach
+- When execution reveals the original plan was based on incorrect assumptions
+- When the user provides new information mid-execution that changes the plan
+- When you've completed part of the plan but the remaining steps are no longer valid
+
+Do NOT use this function:
+- When the failure is unrecoverable or the goal is no longer achievable
+- When you can continue with the current plan without changes`,
   parameters: {
     type: "object",
     properties: {

AIClasses/FunctionDefinitions/Functions/SearchVaultFiles.ts

@@ -5,12 +5,17 @@ export const SearchVaultFiles: IAIFunctionDefinition = {
   name: AIFunction.SearchVaultFiles,
   description: `Searches the content of all vault files using regex pattern matching.
 Returns files containing any of the search terms with contextual snippets showing where matches appear.
-Use this function when you need to:
-- Find specific concepts, keywords, or text within note contents
-- Locate content matching multiple patterns or phrases
-- Answer questions about what the user has written about a topic
-- Search across both file names and file contents simultaneously
-- Search for multiple related terms or variations in a single query`,
+
+Call this function:
+- When you need to find specific concepts, keywords, or text within note contents
+- When locating content matching multiple patterns or phrases
+- When answering questions about what the user has written about a topic
+- When searching across both file names and file contents simultaneously
+- When searching for multiple related terms or variations in a single query
+
+Do NOT use this function:
+- When you need to browse directory structure - list directory contents instead
+- When you already know the exact file path to read - read the file directly`,
   parameters: {
     type: "object",
     properties: {

AIClasses/FunctionDefinitions/Functions/SubmitPlan.ts

@@ -4,8 +4,16 @@ import type { IAIFunctionDefinition } from "../IAIFunctionDefinition";
 export const SubmitPlan: IAIFunctionDefinition = {
     name: AIFunction.SubmitPlan,
     description: `Submits an execution plan with ordered, actionable steps.
-Use this function after analyzing the goal and vault context to provide a structured
-plan that will be followed step-by-step. Each step should be clear and executable.`,
+
+Call this function:
+- After analyzing the goal and vault context to provide a structured plan
+- When you have a clear sequence of steps that will achieve the goal
+- When each step is clear, actionable, and executable
+
+Do NOT use this function:
+- Before exploring the vault context and understanding the current state
+- When you still need more information from the user
+- When the plan is incomplete or steps are unclear`,
 
     parameters: {
       type: "object",

AIClasses/FunctionDefinitions/Functions/WriteVaultFile.ts

@@ -5,10 +5,14 @@ export const WriteVaultFile: IAIFunctionDefinition = {
     name: AIFunction.WriteVaultFile,
     description: `Writes content to a file, creating it if it doesn't exist or replacing its contents if it does.
 
-**When to use this tool:**
-- Creating new notes, documents, or files from scratch
-- Completely rewriting a file's contents (when most/all content needs to change)
-- Generating new files from templates or structured data`,
+Call this function:
+- When creating new notes, documents, or files from scratch
+- When completely rewriting a file's contents (when most/all content needs to change)
+- When generating new files from templates or structured data
+
+Do NOT use this function:
+- When making small, targeted edits to existing files
+- Before reading existing file content to avoid accidentally overwriting important data`,
     parameters: {
         type: "object",
         properties: {