CH 03 · Tool Design · 04/18
Read as one pageReal 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] 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_NAMEholds the nameread_file, so this sentence chains the two tools. - [2] "Exact literal text" is the rule the description gives the model. The matcher still accepts a miss that is only indentation or spacing:
calculateFlexibleReplacementcompares trimmed lines, andcalculateRegexReplacementallows any whitespace between tokens, before a fuzzy pass and before any failure. - [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]
parametersJsonSchemais the JSON Schema for the arguments. Theinstructionfield is a plain-English summary of the change, with its own examples, and it is what the repair model reads.edit.tscallsFixLLMEditWithInstructiononly whengetErrorReplaceResultstill reports an error after exact, trimmed-line, regex, and fuzzy matching: no match, more than one match whenallow_multipleis 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 returnedsearchandreplace. It is skipped when LLM correction is disabled, or for a.json,.ipynb,.jsonc, or.json5file.
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.