Mastering Agentic Coding - Essential Tool Calls for AI-Powered Development

Mastering Agentic Coding - Essential Tool Calls for AI-Powered Development

The Power of Knowing Your Tools

In the world of agentic coding tools like Windsurf and Cursor, understanding your AI's available tool calls is like having a master key to development efficiency. Just as a skilled artisan knows each tool in their workshop, developers who understand their agent's capabilities can collaborate more effectively, solve problems faster, and unlock new levels of productivity. This guide will walk you through the various tool calls, when to use them, and how to activate them for maximum impact. The research for this article came directly from Windsurf. I experimented a little bit with Cursor and found it also uses some of the same tools, but there may be differences.

The Agentic Coding Toolbox

Core Development Tool Calls

1. codebase_search

  • What it does: Finds relevant code snippets across your project.
  • When to use: It provides much more surrounding context than `grep_search`, which is useful for understanding _how_ the code works, not just where it's located.
  • How to use: "do a codebase search for sessionId"
  • Example: Search for "user authentication" to find all related authentication logic.

2. find_by_name

  • What it does: Searches for files and directories by name.
  • When to use: When you know the file name but not its location.
  • How to use: "find the directory named test-db"
  • Example: Find all `*.test.js` files in your project.

3. grep_search

  • What it does: Searches for exact pattern matches within files.
  • When to use: When you need to find specific text patterns across files.
  • How to use: "do grep search to find "dbConnect()""
  • Example: Search for all instances of `deprecatedFunction()` in your codebase.

File Operations

4. view_file

  • What it does: Displays the full contents of a file.
  • When to use: When you need the AI to examine a file's contents.
  • How to use: "view file @filename"
  • Example: View `src/components/Header.js` to understand its implementation.

5. edit_file (write mode) / propose_code (chat mode)

  • What it does: Modifies an existing file.
  • When to use: When you need to make changes to existing code.
  • How to use: "edit @filename to add a comment at the top describing the page"
  • Example: Update a function to fix a bug or add new features.

6. write_to_file

  • What it does: Creates a new file with specified content.
  • When to use: When you need to create a new component, utility, or configuration file.
  • How to use: "in the types folder write a new file named models.ts, leave it empty."
  • Example: Create a new React component file.

7. replace_file_content

  • What it does: Makes precise edits by replacing specific text chunks.
  • When to use: When you need to make targeted changes without rewriting entire files.
  • How to use: "replace the @date in the @chat.ts with today's date."
  • Example: Update API endpoint URLs across multiple files.

System Interaction

8. run_command

  • What it does: Executes terminal commands.
  • When to use: For running scripts, package managers, or system commands.
  • How to use: "run command to delete this file @models.ts"
  • Example: Run `npm install` or start a development server.

9. command_status

  • What it does: Checks the status of a previously executed command.
  • When to use: After running a long-running or background command.
  • How to use: "what is the status of the last run command?"
  • Example: Check the status of a database migration.

Web & Deployment

10. read_deployment_config (not tested)

  • What it does: Verifies deployment readiness and gathers settings.
  • When to use: Before deploying to ensure all configurations are correct.
  • Example: Check deployment settings before pushing to production.

11. deploy_web_app (not tested)

  • What it does: Deploys a web application to a hosting provider.
  • When to use: When you're ready to publish your application.
  • Example: Deploy a Next.js app to Vercel.

12. check_deploy_status (not tested)

What it does: Polls a Windsurf deployment ID to report whether a site build succeeded and if it has been claimed.

When to use: Use this tool immediately after the AI has used the deploy_web_app tool.

Example: Check status of the app deployment.

13. open_browser_url

  • What it does: Opens a URL in the default browser.
  • When to use: When you need to quickly access a web resource.
  • How to use: "use open_browser_url to open the onboarding page"
  • Example: Open API documentation or a deployed application.

14. browser_preview

  • What it does: Opens an interactive browser window for a locally running web server. Can only view the root page, not sub pages like http://localhost:3000/onboarding
  • When to use: When you need to visually test a web application during development.
  • How to use: "run the browser_preview tool to open the app.", "open a web browser so I can test the changes"
  • Example: After starting a local development server, use this to preview your React app.

Information & Research

15. search_web

  • What it does: Performs web searches.
  • When to use: When you need to find documentation or solutions.
  • How to use: "I'm curious about changing my implementation of AI models to allow users to select models from other providers than Google. search_web for langchain documentation."
  • Example: Search for "best practices for React hooks".

16. read_url_content

  • What it does: Fetches content from a URL.
  • When to use: When you need to reference external documentation.
  • How to use: "read_url_content from: https://github.com/langchain-ai/langchainjs"
  • Example: Read the latest React release notes.

Collaboration & Context

17. create_memory

  • What it does: Saves important context for future reference.
  • When to use: When you want to remember specific preferences or decisions.
  • How to use: "Create a memory that my project uses React v19, not 18."
  • Example: Save a note about the project's coding conventions.

18. suggested_responses (may not be a tool)

NOTE: During testing I was not able to get the agent to use this tool. It may not be an actual tool it can use.

  • What it does: Provides quick reply options.
  • When to use: When you want to guide the conversation.
  • Example: Offer "Yes/No" options for a confirmation.

19. update_plan

  • What it does: Creates, reviews, and modifies a high-level, step-by-step plan for your project.
  • When to use: When you provide new tasks or change the requirements for an existing one. When the AI discovers new information from web or code searches and it impacts the current strategy.
  • How to use: "Update the plan to include the switch to LangChain."
  • Example: Update the plan when you decide on a new task to work on.

Advanced Features

20. list_dir

  • What it does: Allows AI to see all the files and subdirectories inside a specific folder. For each item, it tells the AI if it's a file or a directory, its size (if it's a file), and how many items are inside it (if it's a directory). It's like running `ls -l` or `dir` in your terminal.
  • When to use: At the beginning of a task to orient the AI on your codebase and help it find the right files to work on.
  • How to use: "list_dir `C:\Users\Reid\Documents\Programming\Creator Space\src\app\api`"
  • Example: List all the files and subfolders in a directory.

21. list_resources

  • What it does: Manages MCP server resources.
  • When to use: When working with Model Context Protocol integrations.
  • How to use: "list all resources for MCP servers"
  • Example: List available resources from a connected service.

22. read_resources

  • What it does: Reads data from a specific MCP server resource.
  • When to use: To obtain data from an MCP server resource.
  • How to use: "read my open github issues"
  • Example: Read your GitHub issues

23. view_code_item

  • What it does: Shows specific code items like functions or classes.
  • When to use: When you need to examine a specific function's implementation.
  • How to use: "review the main function in the page.ts file and explain how it works"
  • Example: View the `User.authenticate` method definition.

24. view_content_chunk

  • What it does: Displays specific chunks of web document or knowledge base content.
  • When to use: When working with large web documents or knowledge bases. Use after the AI has used `read_url_content` to view the contents of a webpage.
  • How to use: "Show me the list of chunks from the URL you read", it lists position numbers, then "Read position ##"
  • Example: View a specific section of API documentation.

Real-World Example: Adding a New Feature

Let's say you're tasked with adding a dark mode toggle to a web application. Here's how you might use these tools:

  1. Research: Use `search_web` to find best practices for implementing dark mode in React.
  2. Code Exploration: Use `codebase_search` to find where theming is handled.
  3. File Creation: Use `write_to_file` to create a new `ThemeToggle.js` component.
  4. Implementation: Use `edit_file` to update the main layout to include the theme provider.
  5. Testing: Use `run_command` to start the development server and `browser_preview` to test the changes.
  6. Documentation: Use `create_memory` to document the theming approach for future reference.

The Power of Mastery

Understanding and effectively commanding these tools transforms your interaction with agentic coding assistants from passive suggestion to active collaboration. When you know exactly what your AI pair programmer can do, you can:

  • Delegate tasks more effectively
  • Provide clearer instructions
  • Anticipate potential challenges
  • Streamline your development workflow
  • Maintain better control over the development process

This knowledge creates a powerful synergy between human creativity and AI capabilities, allowing you to focus on high-level problem-solving while efficiently managing implementation details. By mastering these tools, you're not just coding—you're orchestrating a more productive development experience.