feat: simplify ask_followup_question prompt documentation (#7191)

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/architect-mode-prompt.snap

@@ -270,29 +270,22 @@ Examples:
 </search_and_replace>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -302,16 +295,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/ask-mode-prompt.snap

@@ -167,29 +167,22 @@ Examples:
 </list_code_definition_names>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -199,16 +192,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/mcp-server-creation-disabled.snap

@@ -269,29 +269,22 @@ Examples:
 </search_and_replace>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -301,16 +294,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/mcp-server-creation-enabled.snap

@@ -319,29 +319,22 @@ Example: Requesting to access an MCP resource
 </access_mcp_resource>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -351,16 +344,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/partial-reads-enabled.snap

@@ -275,29 +275,22 @@ Examples:
 </search_and_replace>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -307,16 +300,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/system-prompt/consistent-system-prompt.snap

@@ -270,29 +270,22 @@ Examples:
 </search_and_replace>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -302,16 +295,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/system-prompt/with-computer-use-support.snap

@@ -323,29 +323,22 @@ Example: Requesting to click on the element at coordinates 450,300
 </browser_action>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -355,16 +348,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/system-prompt/with-diff-enabled-false.snap

@@ -270,29 +270,22 @@ Examples:
 </search_and_replace>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -302,16 +295,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/system-prompt/with-diff-enabled-true.snap

@@ -358,29 +358,22 @@ Examples:
 </search_and_replace>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -390,16 +383,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/system-prompt/with-diff-enabled-undefined.snap

@@ -270,29 +270,22 @@ Examples:
 </search_and_replace>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -302,16 +295,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/system-prompt/with-different-viewport-size.snap

@@ -323,29 +323,22 @@ Example: Requesting to click on the element at coordinates 450,300
 </browser_action>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -355,16 +348,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/system-prompt/with-mcp-hub-provided.snap

@@ -319,29 +319,22 @@ Example: Requesting to access an MCP resource
 </access_mcp_resource>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -351,16 +344,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/__tests__/__snapshots__/system-prompt/with-undefined-mcp-hub.snap

@@ -270,29 +270,22 @@ Examples:
 </search_and_replace>
 
 ## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -302,16 +295,6 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 </follow_up>
 </ask_followup_question>
 
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
-</ask_followup_question>
-
 ## attempt_completion
 Description: After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
 IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must ask yourself in <thinking></thinking> tags if you've confirmed from the user that any previous tool uses were successful. If not, then DO NOT use this tool.

src/core/prompts/tools/ask-followup-question.ts

@@ -1,28 +1,21 @@
 export function getAskFollowupQuestionDescription(): string {
 	return `## ask_followup_question
-Description: Ask the user a question to gather additional information needed to complete the task. This tool should be used when you encounter ambiguities, need clarification, or require more details to proceed effectively. It allows for interactive problem-solving by enabling direct communication with the user. Use this tool judiciously to maintain a balance between gathering necessary information and avoiding excessive back-and-forth.
+Description: Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
 Parameters:
-- question: (required) The question to ask the user. This should be a clear, specific question that addresses the information you need.
-- follow_up: (required) A list of 2-4 suggested answers that logically follow from the question, ordered by priority or logical sequence. Each suggestion must:
-  1. Be provided in its own <suggest> tag
-  2. Be specific, actionable, and directly related to the completed task
-  3. Be a complete answer to the question - the user should not need to provide additional information or fill in any missing details. DO NOT include placeholders with brackets or parentheses.
-  4. Optionally include a mode attribute to switch to a specific mode when the suggestion is selected: <suggest mode="mode-slug">suggestion text</suggest>
-     - When using the mode attribute, focus the suggestion text on the action to be taken rather than mentioning the mode switch, as the mode change is handled automatically and indicated by a visual badge
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers, each in its own <suggest> tag. Suggestions must be complete, actionable answers without placeholders. Optionally include mode attribute to switch modes (code/architect/etc.)
+
 Usage:
 <ask_followup_question>
 <question>Your question here</question>
 <follow_up>
-<suggest>
-Your suggested answer here
-</suggest>
-<suggest mode="code">
-Implement the solution
-</suggest>
+<suggest>First suggestion</suggest>
+<suggest mode="code">Action with mode switch</suggest>
 </follow_up>
 </ask_followup_question>
 
-Example: Requesting to ask the user for the path to the frontend-config.json file
+Example:
 <ask_followup_question>
 <question>What is the path to the frontend-config.json file?</question>
 <follow_up>
@@ -30,15 +23,5 @@ Example: Requesting to ask the user for the path to the frontend-config.json fil
 <suggest>./config/frontend-config.json</suggest>
 <suggest>./frontend-config.json</suggest>
 </follow_up>
-</ask_followup_question>
-
-Example: Asking a question with mode switching options
-<ask_followup_question>
-<question>How would you like to proceed with this task?</question>
-<follow_up>
-<suggest mode="code">Start implementing the solution</suggest>
-<suggest mode="architect">Plan the architecture first</suggest>
-<suggest>Continue with more details</suggest>
-</follow_up>
 </ask_followup_question>`
 }