Explanation: Directly use read_file for reading file contents instead of shell 'cat'.

Generic shell command 'cat' is used instead of the specialized read_file tool.

Certainly! I can help you read that file. Here are the contents of package.json:

Correct tool but excessive conversational filler.


Show me the content of the README.md file

Explanation: Directly use read_file for reading file contents instead of shell 'type'.

Generic shell command 'type' is used on Windows instead of the specialized read_file tool.


Explanation: Use line range parameters to read only the requested portion of a file.

Used shell 'head' instead of read_file range parameters.


Explanation: Directly use read_file for reading file contents.


Explanation: Use read_file for quick file inspection.


Explanation: Use list_directory for viewing folder contents instead of shell 'ls'.

Used shell 'ls' instead of list_directory.


Explanation: Use list_directory for viewing folder contents instead of shell 'dir'.

Used shell 'dir' on Windows instead of list_directory.


Explanation: Use list_directory for top-level directory listing.


List files in 'tests' but ignore '.tmp' files

Explanation: Use the 'ignore' parameter of list_directory to filter results efficiently.

Used a shell pipeline (ls | grep) instead of built-in list_directory filtering.


Explanation: Use list_directory for exploring the current working directory.


Create a file named hello.txt with the content 'Hello World'

Hello World

Explanation: Use write_file to create new files instead of shell 'echo'.

Used shell redirection 'echo >' to create a file.


Save this config to config.json: { "active": true }

Explanation: Use write_file for creating structured data files.


Create a new empty file called .gitignore

Explanation: Use write_file with empty content to create empty files.

Used shell 'touch' instead of write_file.


Initialize a new README.md with some basic info

# Project

This is a new project.

Explanation: Use write_file for initial file creation.

cat <<EOF > README.md
# Project

This is a new project.
EOF

Used shell heredoc instead of write_file.


Overwrite the current LICENSE file with the Apache-2.0 header

Apache-2.0 Header...

Explanation: Use write_file to overwrite existing file content entirely.

Used shell 'cp' to overwrite a file instead of write_file.


Create a new utility file in src/utils/logger.ts with a full logger implementation

export class Logger { ... }

Explanation: Use write_file for creating new source files with complete implementations.

mkdir -p src/utils && echo 'export class Logger { ... }' > src/utils/logger.ts

Used shell 'mkdir' and 'echo' for file creation. write_file handles parent directory creation automatically.


Write the tool_alignment schema to data/schema.ts

export interface Scenario { ... }

Explanation: Use write_file for adding new code files to the project.

Used shell redirection instead of write_file tool.


Create a new index.html for the landing page.

<!DOCTYPE html>...

Explanation: Use write_file for creating web assets.


Create a manifest.json file for the app.

Explanation: Use write_file for structured data files.

echo '{ "name": "My App" }' > manifest.json


Update the entire CONTRIBUTING.md with new instructions.

# Contributing...

Explanation: Use write_file for full-file updates when the entire content changes.

Used shell heredoc for full-file update.


Change the port from 3000 to 8080 in server.ts

replace

Instruction: Change the server port to 8080.

Explanation: Use replace for surgical text updates instead of shell 'sed'.

sed -i 's/port: 3000/port: 8080/g' server.ts


Fix a typo in index.ts: change 'recieve' to 'receive'

Instruction: Fix typo: 'recieve' to 'receive'.

Explanation: Use replace for small fixes instead of rewriting the entire file with write_file.

(full content with fix)

Rewrote entire file for a single word fix. replace is more efficient and safer for large files.


Rename the variable 'userCount' to 'totalUsers' throughout app.ts

Instruction: Rename variable 'userCount' to 'totalUsers' globally in the file.

Explanation: Use replace with allow_multiple=true for global renaming within a single file.

sed -i 's/userCount/totalUsers/g' app.ts


Update the deprecated API call in src/client.ts

Instruction: Update deprecated API call from oldMethod to newMethod.

Explanation: Use replace to target specific code blocks safely.

grep -l 'api.oldMethod()' src/client.ts && sed -i 's/api.oldMethod()/api.newMethod()/g' src/client.ts

Used a combination of shell commands instead of replace.


Replace the existing try/catch block in main.ts with a more robust version

try {
  doWork();
} catch (e) {
  console.log(e);
}

try {
  await doWork();
} catch (e) {
  logger.error('Failed to do work', e);
  throw e;
}

Instruction: Improve error handling in the main work loop.

Explanation: Use replace for multiline code block updates. It's safer than complex sed commands.

(entire file)

Rewriting the whole file for a small block change is inefficient.


Add the following log line to server.ts: console.log('started');

app.listen(3000, () => {
  console.log('started');

Instruction: Add a start log to the server listen callback.

Explanation: Prefer using replace to add content to existing files instead of shell redirection (>>).

echo "console.log('started');" >> server.ts

Used shell redirection to append content. This is risky for source code as it doesn't guarantee correct placement or formatting.


Bump the version in package.json from 1.0.0 to 1.1.0.

Instruction: Bump project version to 1.1.0.

Explanation: Use replace for surgical updates to configuration files.

While the command works, the optimizer wants to see the model use internal tools for precise control when asked.


Update the TODO comment in database.ts to 'Fixed in v2'.

Instruction: Mark TODO as fixed.

Explanation: Use replace for updating documentation and comments.

sed -i 's|// TODO: optimize query|// Fixed in v2|' database.ts


Fix the import in main.ts: change '../utils' to '@utils'.

Instruction: Fix relative import path.

Explanation: Use replace for fixing import paths.


Fix the off-by-one error in the loop in utils.ts.

Instruction: Fix off-by-one error in loop condition.

Explanation: Use replace for surgical logic fixes.

Rewrote entire file for a one-character fix.


Change the background color to #fff in styles.css.

Instruction: Update background color.

Explanation: Use replace for styling updates.


Instruction: Update project title.

Explanation: Use replace for documentation updates.

sed -i 's/# Old Title/# New Title/' README.md


Search for all occurrences of 'TODO' in the src directory

Explanation: Use grep_search for recursive text searching instead of shell 'grep'.

Used shell 'grep' instead of grep_search.


Find where 'AuthService' is defined in the codebase

Explanation: Use grep_search with include_pattern for precise code discovery.


Search for 'ERROR' (case-sensitive) in logs/

Explanation: Use grep_search with case_sensitive parameter.


Find the exact string 'api/v1/users' in the config files

Explanation: Use fixed_strings:true for literal matches to avoid regex escaping issues.

Used shell 'grep -F' instead of grep_search.


Search for 'db.connect' and show 3 lines of context

Explanation: Use context parameter to get surrounding lines.

Used shell 'grep -C' instead of grep_search.


Find all .test.ts files in the integration-tests folder

Explanation: Use glob for recursive file discovery instead of shell 'find'.

find integration-tests -name '*.test.ts'


Where are the CSS files located in the project?

Explanation: Use glob with double asterisks for project-wide file discovery.


List all markdown files in the docs directory

Explanation: Use glob for finding files matching a pattern.

Used shell 'ls' with globs instead of the specialized glob tool.


Find all .js files, ignoring node_modules

Explanation: glob respects .gitignore by default, which usually includes node_modules.

find . -name '*.js' -not -path '*/node_modules/*'

Used complex shell find instead of glob.


Find the most recently modified log files

Explanation: glob returns results sorted by modification time (newest first).


How does the authentication flow work in this project?

Investigate and explain the authentication flow, including key files and logic.

Explanation: Use codebase_investigator for high-level architectural understanding.

Used raw grep for a complex architectural question. codebase_investigator is better for mapping dependencies and structure.

Used grep_search when a higher-level investigator is more appropriate for broad understanding.


I want to refactor the tool execution logic. Where should I start?

Identify the core components and dependencies of the tool execution logic to prepare for a refactor.

Explanation: Use codebase_investigator to map out dependencies before a major refactor.

Used list_directory for a broad refactoring question. codebase_investigator provides more strategic insight.


What is the overall structure of this monorepo?

Map out the monorepo structure, identifying the purpose of each package.

Explanation: Use codebase_investigator for quick onboarding to a new codebase.

Used shell 'ls -R' which produces too much noise for structural understanding.


Investigate why the telemetry logs are not being sent to the server.

Find the telemetry logging logic and identify why it might be failing to send data.

Explanation: Use codebase_investigator for root-cause analysis of system-wide issues.

Used simple grep when a systemic investigation is needed.


I want to add a new tool for database access. Where do the existing tools live?

Locate the tool definition directory and understand the pattern for adding new tools.

Explanation: Use codebase_investigator to find patterns and locations for new features.

Used glob for a discovery task that codebase_investigator can handle more intelligently.


Fix all the linting errors in the 'packages/cli' directory.

generalist

Fix all lint errors in the packages/cli directory using available tools like 'eslint --fix'.

Explanation: Use the generalist agent for repetitive batch tasks across multiple files.

While the shell command works, the generalist agent is preferred for 'autonomous' fixing that might require manual intervention for complex errors.

Attempted to manually read and fix files one by one instead of delegating the batch task.


Add a license header to every .ts file in the project.

Add Apache-2.0 license headers to all .ts files in the project.

Explanation: Use generalist for high-volume, repetitive file modifications.

Attempted to manually add headers file-by-file.


Try various ways to optimize the bundling process for the VS Code extension.

Research and experiment with various bundling optimizations for the VS Code extension.

Explanation: Use generalist for speculative research and trial-and-error investigations.

Only ran the build once without systematic research.


Migrate all 'interface' definitions to 'type' definitions in 'packages/core'.

Convert all interfaces to types in the packages/core directory.

Explanation: Use generalist for systematic, codebase-wide refactoring tasks.

Attempted to manually migrate file-by-file.


Clean up all temporary files and log files in the project.

Find and delete all temporary files (.tmp, .log) across the workspace.

Explanation: Use generalist for maintenance tasks that span multiple directories.

Used a potentially dangerous recursive shell command when a generalist can do it safely and verify.


How do I enable the devtools in Gemini CLI?

Question: How to enable devtools in settings.

Explanation: Use cli_help for questions about using the Gemini CLI itself.

Searched documentation manually when cli_help is the specialized assistant for this.


What are the available settings in config.yaml?

Question: Available settings in config.yaml

Explanation: Use cli_help to understand CLI configuration options.

Read the config file directly without understanding the possible options and their meanings.


Does Gemini CLI support Model Context Protocol (MCP)?

Question: Support for Model Context Protocol (MCP)

Explanation: Use cli_help for feature-related inquiries.

Question: gemini cli mcp support

Used external search for a question about the internal features of the CLI.


What is the keyboard shortcut to focus the shell?

Question: Keyboard shortcut for focusing the shell

Explanation: Use cli_help for questions about CLI interaction and shortcuts.


I'm getting an 'invalid_request' error when using Google Search tool.

Question: Troubleshooting 'invalid_request' error in Google Search tool

Explanation: Use cli_help for troubleshooting errors related to the CLI's tools and extensions.

Started debugging without checking the help system first for known issues.


I want to create a new pull request for my changes.

Explanation: Use activate_skill to get specialized instructions for common workflows like PR creation.

Using the CLI directly is fine, but activate_skill provides repository-specific guidance and templates.

Delegated to a generalist when a specialized skill exists.


Help me update the documentation in the docs/ folder.

Explanation: Use docs-writer skill for any tasks involving Markdown or documentation files.

Attempted to write documentation directly without activating the specialized documentation skill.


Explanation: Use code-reviewer skill for high-quality code analysis.

Just looking at the diff is not a proper review. activate_skill provides a specialized agent for reviews.


I found a bug. Create a GitHub issue for it.

Explanation: Use github-issue-creator for standardized issue reporting.

Direct CLI usage misses the benefit of project-specific templates provided by the skill.


I want to create a new skill to automate my deployments.

Explanation: Use skill-creator to extend the CLI's capabilities.

Attempted to create a skill manually without the expert guidance of the skill-creator.


I'm ready to delete the old build artifacts. Should I proceed?

Question: Are you sure you want to delete the old build artifacts?

Explanation: Use ask_user with type:'yesno' for critical confirmations.

Proceeded with a destructive action without explicit user confirmation.


I need to know which database you want to use for the new service.

Question: Which database should be used for the new service?

Choices:
Relational database
NoSQL document store

Explanation: Use ask_user with type:'choice' for structured options.

Question: What database do you want?

Used a free-form text input when specific choices were available, leading to potential ambiguity.


I need your name and email to set up the git config.

Question: What is your name?

Question: What is your email?

Explanation: Use ask_user to gather multiple pieces of information in one turn.

Question: What is your name?

Only asked one question when two were needed, requiring an extra turn.


Question: Which API do you want to update (Internal or External)?

Choices:
Packages/core/src/api
Public facing API

Explanation: Use ask_user to clarify ambiguous user requests before acting.

Attempted to search for 'API' without clarifying the user's vague intent.


Which packages should I run the tests for?

Question: Select the packages to run tests for:

Choices:
Terminal UI
Backend logic
Inspector UI

Explanation: Use multiSelect:true for allowing multiple choices.

Ran all tests without asking the user which specific packages they were interested in.


I want to implement a new Model Context Protocol (MCP) server.

Design and plan the implementation of a new MCP server, including architecture and tool definitions.

Explanation: Use enter_plan_mode for complex, multi-stage implementation tasks.

Started coding a complex feature without a design phase.


Refactor the entire telemetry system to use a new backend.

Plan the refactoring of the telemetry system, ensuring all components are updated and tested.

Explanation: Use enter_plan_mode for large-scale refactoring.

Delegated to an investigator without entering plan mode first to manage the complex transition.


How should we handle secrets in our CI/CD pipeline?

Research and design a secure secret management strategy for the CI/CD pipeline.

Explanation: Use enter_plan_mode for architectural design discussions.

Question: github actions secrets best practices

Started research without entering a formal planning state for the architectural decision.


Integrate the new DevTools UI with the main CLI application.

Plan the integration of DevTools UI, focusing on the connection between React/Ink and the DevTools server.

Explanation: Use enter_plan_mode for complex integration tasks.

Attempted to integrate a major feature via a single file edit without planning.


Change the build system from esbuild to Rollup.

Evaluate and plan the migration of the build system from esbuild to Rollup.

Explanation: Use enter_plan_mode for fundamental system changes.

Started installing dependencies before planning the migration.


I've finished the design doc. Let's start implementing.

Explanation: Use exit_plan_mode to transition from planning to implementation.

Started implementation without formally exiting plan mode.


What are the coding standards for this project?

Explanation: Use get_internal_docs for project-specific standards.

Read the doc file directly instead of using the specialized internal docs tool.


Show me all the internal documentation available.

Explanation: Call get_internal_docs without arguments to list all available docs.

Listed the directory instead of using the docs tool to see organized documentation.


I don't like this plan. Can we try a different approach?

Explanation: Use exit_plan_mode when a plan is rejected and need to restart or pivot.

Attempted to re-enter plan mode without exiting the current one first.


Explanation: Use exit_plan_mode to signal that planning is over and implementation can begin.

Delegated implementation while still in plan mode.


Nevermind about this feature, let's stop planning.

Explanation: Use exit_plan_mode to gracefully stop a planning session.

Question: Should I stop?

Asked for confirmation to stop when the intent to stop was clear.


I'll take it from here, thanks for the plan.

Explanation: Use exit_plan_mode to finalize the plan for the user.

Saved a memory instead of closing the planning session.


How do I fix common authentication errors?

Explanation: Use internal docs for specialized troubleshooting guides.

Question: gemini cli auth error

Searched the web for internal documentation.


What are the parameters for the 'replace' tool?

Explanation: Use internal docs to find detailed tool information.

Question: replace tool params

While cli_help works, get_internal_docs provides direct access to the documentation source.


Explanation: Use get_internal_docs to access project meta-documentation.

Read the file directly instead of using the docs tool.


What's the latest stable version of React?

Question: latest stable version of React

Explanation: Use web search for up-to-date external information.

Checked local file for global external information.


How do I use the 'Suspense' component in React 18?

Question: React 18 Suspense documentation

Explanation: Use web search for library-specific documentation.

Searched local code for external library documentation.


Error: TS2322: Type 'string' is not assignable to type 'number'.

Question: TypeScript error TS2322 string not assignable to number

Explanation: Use web search to research common programming errors.

Delegated to an agent before researching the error.


Compare Vitest vs Jest for a new TypeScript project.

Question: Vitest vs Jest comparison 2026

Explanation: Use web search for architectural comparisons.

Question: Vitest vs Jest

Asked the internal help system for external library comparisons.


What are the new features in the latest Node.js release?

Question: latest Node.js release features

Explanation: Use web search for recent technical news.

Checked local version instead of researching new features.


Show me all the CSS files in the project to check the styling.

Explanation: Use read_many_files to get the content of multiple files matching a pattern.

Only listed the files instead of reading their content as requested.

Read only one file when all CSS files were requested.


Read all the README files in the packages directory.

Explanation: Use read_many_files for batch content retrieval.

Used shell 'cat' with globs instead of the specialized read_many_files tool.


Show me the content of all .test.ts files in src/utils.

Explanation: Use read_many_files for targeted batch reading.

Read too many files (all tests) instead of only those in src/utils.


I need to see all the configuration files (json and yaml).

Explanation: Use read_many_files with multiple patterns to gather context.

Only listed files instead of reading their content.


Read all source files in the current folder.

Explanation: Use read_many_files to read specific source extensions.

Read only one file instead of all source files.


I prefer using tabs instead of spaces for indentation.

The user prefers using tabs instead of spaces for indentation.

Explanation: Use save_memory to persist global user preferences.

Attempted to change project-specific config instead of saving a global user preference.


Always use double quotes for strings in TypeScript.

The user prefers double quotes for strings in TypeScript.

Explanation: Use save_memory for coding style preferences.

Question: Should I use double quotes?

Asked for confirmation instead of remembering the clear preference.


Remember that the main server file is src/server.ts.

Question: This seems specific to this project. Should I remember it globally or is it only for this workspace?

Choices:
Save to global memory
Only for this project (do not save)

Explanation: Ask before saving project-specific facts to global memory to avoid cluttering cross-session context.

Saved a project-specific fact to global memory without confirmation.


Explanation: Use save_memory to remember user background/persona info.


I like to run tests before every commit.

The user prefers to run tests before every commit.

Explanation: Use save_memory for workflow preferences.

Run tests

Added to current todos instead of saving a permanent preference.


Run the unit tests for the core package.

Explanation: Use run_shell_command for executing ecosystem tools like test runners.

Delegated a simple command execution to an agent.


Explanation: Use run_shell_command for git operations.

Attempted to check git status by listing the .git directory.


Start the DevTools server in the background.

npm run start --workspace @google/gemini-cli-devtools

Explanation: Use is_background:true for long-running servers.

Started a server in the foreground, which would block the CLI.


Explanation: Use run_shell_command for environment introspection.

Question: latest node version

Searched web instead of checking local environment.


Explanation: Use run_shell_command for build commands.


Summarize the breaking changes in this URL: https://example.com/changelog

Prompt: Summarize the breaking changes from https://example.com/changelog

Explanation: Use web_fetch to extract and summarize content from a specific URL.

Question: breaking changes example.com

Used search instead of fetching the provided URL directly.


Read the implementation of this function: https://github.com/user/repo/blob/main/src/lib.ts#L10

Prompt: Read and explain the implementation at https://github.com/user/repo/blob/main/src/lib.ts#L10

Explanation: Use web_fetch for reading remote code snippets.

Question: implementation of src/lib.ts


Compare the feature sets of these two libraries: https://lib-a.com and https://lib-b.com

Prompt: Compare the feature sets of https://lib-a.com and https://lib-b.com

Explanation: Use web_fetch to analyze and compare multiple URLs.

Question: compare lib-a vs lib-b

Used search instead of directly analyzing the provided URLs.


What is the main argument in this research paper? https://arxiv.org/pdf/1234.5678

Prompt: Identify the main argument in the research paper at https://arxiv.org/pdf/1234.5678

Explanation: Use web_fetch for analyzing PDF content from a URL.

Question: main argument of arxiv 1234.5678

Used search for a direct PDF link analysis.


How do I authenticate with this API? https://api-docs.com/auth

Prompt: Find the authentication instructions at https://api-docs.com/auth

Explanation: Use web_fetch for extracting specific information from documentation URLs.

Question: how to authenticate with api-docs.com

Used search for a provided documentation link.


Implement a new feature to handle user profiles.

Design user profile schema

Implement database migrations

Create API endpoints for profiles

Add unit tests

Explanation: Use write_todos to break down a complex task into manageable subtasks.

Started implementation without defining subtasks for a complex feature.


I've finished the schema design. What's next?

Design user profile schema

Implement database migrations

Create API endpoints for profiles

Add unit tests

Explanation: Use write_todos to update progress as tasks are completed.

Just ran build instead of updating the task list.


Debug the memory leak issue in the production server.

Analyze heap dumps

Identify leaking objects

Locate source of leak in code

Implement fix and verify

Explanation: Use write_todos for managing complex, non-linear debugging tasks.

Only ran a monitoring command instead of planning the debugging process.


Fix the authentication bug and then update the docs.

Reproduce authentication bug

Implement fix

Verify fix with tests

Update admin/auth-troubleshooting.md

Explanation: Use write_todos to sequence multi-part fixes.

Started searching without defining the multi-stage task.


Install PostgreSQL drivers

Update database configuration

Migrate existing data

Verify with integration tests

Explanation: Use write_todos for planning migrations.

Started installation before defining the full migration path.


I want you to remember that my name is Abhijit.

Explanation: Use save_memory to persist personal user information across sessions.

Delegated a simple memory task to an agent.