Skip to slide
031 / 221

CH 03 · Tool Design · 04/18

Read as one page

Real code: Gemini CLI's edit tool teaches through its description

Gemini CLI is Google's open-source coding agent for the terminal, and replace is its file-editing tool. Every model except Gemini 3 receives the definition below. Gemini 3 gets the same tool with a shorter description and shorter field descriptions. Other tools in that set are rewritten too, and some of those descriptions are longer. The // [1] markers and the // ... lines inside the quoted text are added here. They are not part of the description the model receives.

replace: {
  name: EDIT_TOOL_NAME,
  description: `Replaces text within a file. By default, the tool expects to find and replace exactly ONE occurrence of \`old_string\`. If you want to replace multiple occurrences of the exact same string, set \`allow_multiple\` to true. This tool requires providing significant context around the change to ensure precise targeting. Always use the ${READ_FILE_TOOL_NAME} tool to examine the file's current content before attempting a text replacement. // [1]
    // ... (2 lines: the user may edit new_string; a heading)
    1. \`old_string\` MUST be the exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code etc.). // [2]
    // ... (3 lines: rules for new_string, instruction, and escaping)
    **Important:** If ANY of the above are not satisfied, the tool will fail. CRITICAL for \`old_string\`: Must uniquely identify the instance(s) 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 and \`allow_multiple\` is not true, the tool will fail. // [3]
    // ... (2 lines: prefer small atomic calls; how allow_multiple works)
  parametersJsonSchema: {
    type: 'object',
    properties: {
      // ... (4 lines: the file_path parameter)
      [EDIT_PARAM_INSTRUCTION]: { // [4]
        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.
        // ... (6 lines: answer WHY, WHERE, WHAT, the desired outcome; a GOOD example)
        **BAD Examples:**
        - "Change the text." (Too vague)
        - "Fix the bug." (Doesn't explain the bug or the fix)
        - "Replace the line with this new line." (Brittle, just repeats the other parameters)

Source: google-gemini/gemini-cli, packages/core/src/tools/definitions/model-family-sets/default-legacy.ts (Apache-2.0)

What to notice

  1. [1] Only the first sentence says what the tool does. The rest is usage: one match by default, plenty of context, and "always read the file first". READ_FILE_TOOL_NAME holds the name read_file, so this sentence chains the two tools.
  2. [2] "Exact literal text" is the rule the description gives the model. The matcher still accepts a miss that is only indentation or spacing: calculateFlexibleReplacement compares trimmed lines, and calculateRegexReplacement allows any whitespace between tokens, before a fuzzy pass and before any failure.
  3. [3] The failure rule arrives before the model can trip on it, together with the fix: three lines of context on each side, so the match is unique.
  4. [4] parametersJsonSchema is the JSON Schema for the arguments. The instruction field is a plain-English summary of the change, with its own examples, and it is what the repair model reads. edit.ts calls FixLLMEditWithInstruction only when getErrorReplaceResult still reports an error after exact, trimmed-line, regex, and fuzzy matching: no match, more than one match when allow_multiple is not set, or old and new text that are identical. The call receives the instruction, both strings, the error text, and the current file, then retries with the returned search and replace. It is skipped when LLM correction is disabled, or for a .json, .ipynb, .jsonc, or .json5 file.

A one-line "Replaces text in a file" would leave these rules for the model to learn by failing.

Read it yourself: open model-family-sets/gemini-3.ts and search for replace:. List which rules that description drops. Then read getToolFamily in modelFamilyService.ts to see which models receive which set.

Finished this idea?

Your learning progress stays in this browser.