Tool Improvement: Refine replace schema and description

[mattKorwel]

Overview

Part of the tool augmentation effort to optimize tool definitions for Gemini 3.0.

Proposed Changes

Update tool descriptions to provide better guidance on required context. Investigate the "at least 3 lines of context" constraint (identified as potentially brittle in planning) for potential flexibility improvements.

Audit and minimize/remove "how-to" sections in tool definitions to optimize the context budget.

Context from Planning

{
  "name": "replace",
  "description": "Replaces text within a file. By default, replaces a single occurrence, but can replace multiple occurrences when `expected_replacements` is specified. This tool requires providing significant context around the change to ensure precise targeting. Always use the read_file tool to examine the file's current content before attempting a text replacement.\n      \n      The user has the ability to modify the `new_string` content. If modified, this will be stated in the response.\n      \n      Expectation for required parameters:\n      1. `old_string` MUST be the exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code etc.).\n      2. `new_string` MUST be the exact literal text to replace `old_string` with (also including all whitespace, indentation, newlines, and surrounding code etc.). Ensure the resulting code is correct and idiomatic and that `old_string` and `new_string` are different.\n      3. `instruction` is the detailed instruction of what needs to be changed. It is important to Make it specific and detailed so developers or large language models can understand what needs to be changed and perform the changes on their own if necessary. \n      4. NEVER escape `old_string` or `new_string`, that would break the exact literal text requirement.\n      **Important:** If ANY of the above are not satisfied, the tool will fail. CRITICAL for `old_string`: Must uniquely identify the single instance to change. Include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string matches multiple locations, or does not match exactly, the tool will fail.\n      5. Prefer to break down complex and long changes into multiple smaller atomic calls to this tool. Always check the content of the file after changes or not finding a string to match.\n      **Multiple replacements:** Set `expected_replacements` to the number of occurrences you want to replace. The tool will replace ALL occurrences that match `old_string` exactly. Ensure the number of replacements matches your expectation.",
  "parametersJsonSchema": {
    "properties": {
      "file_path": { "description": "The path to the file to modify.", "type": "string" },
      "instruction": { "description": "A clear, semantic instruction for the code change, acting as a high-quality prompt for an expert LLM assistant. It must be self-contained and explain the goal of the change...", "type": "string" },
      "old_string": { "description": "The exact literal text to replace, preferably unescaped. For single replacements (default), include at least 3 lines of context BEFORE and AFTER the target text...", "type": "string" },
      "new_string": { "description": "The exact literal text to replace `old_string` with, preferably unescaped. Provide the EXACT text. Ensure the resulting code is correct and idiomatic.", "type": "string" },
      "expected_replacements": { "type": "number", "description": "Number of replacements expected. Defaults to 1 if not specified.", "minimum": 1 }
    },
    "required": [ "file_path", "instruction", "old_string", "new_string" ],
    "type": "object"
  }
}

Parent: #15331