Tools & Commands Reference

This comprehensive guide covers all tools and commands available in Dropstone Agent, organized by category with usage examples and best practices.

Understanding Tools

Dropstone Agent uses a powerful tool system to interact with your codebase, development environment, and external services. Each tool represents a specific capability that the agent can invoke to accomplish tasks.

How Tools Work

1. User Request - You describe what you want in natural language
2. Tool Selection - Agent determines which tools are needed
3. Approval (if required) - You review and approve tool usage
4. Execution - Agent executes the tool with appropriate parameters
5. Result Processing - Agent interprets results and continues or completes the task

Auto-Approval

You can configure which tools run automatically without approval. See the Settings Guide for details.

File Operations

read_file

Read the contents of a file.

Usage:

• View existing code before modification
• Analyze file contents
• Check configuration files
• Review documentation

Parameters:

• path (string, required) - File path relative to workspace root
• encoding (string, optional) - File encoding (default: utf-8)

Example Request:

Read the contents of src/app/main.ts

Best Practices:

• Always read files before modifying them
• Use relative paths from workspace root
• Verify file exists before reading

write_to_file

Create a new file or overwrite an existing file.

Usage:

• Create new files
• Replace entire file contents
• Generate configuration files
• Create documentation

Parameters:

• path (string, required) - File path relative to workspace root
• content (string, required) - Complete file contents

Example Request:

Create a new file at src/utils/helpers.ts with utility functions for date formatting

Best Practices:

• Always read existing files before overwriting
• Confirm file paths carefully
• Use proper file extensions
• Consider using apply_diff for partial changes

delete_file

Delete a file from the workspace.

Usage:

• Remove unused files
• Clean up generated files
• Delete test fixtures

Parameters:

• path (string, required) - File path relative to workspace root

Example Request:

Delete the file src/old/deprecated.ts

Best Practices:

• Double-check file paths before deleting
• Use version control to recover if needed
• Consider moving to archive instead of deleting
• Enable checkpoints for easy recovery

list_files

List files in a directory, optionally with a filter pattern.

Usage:

• Explore directory structure
• Find files matching patterns
• Count files of certain types
• Verify file organization

Parameters:

• path (string, required) - Directory path relative to workspace root
• recursive (boolean, optional) - Search subdirectories (default: false)
• pattern (string, optional) - Glob pattern filter (e.g., ".ts", "**/.test.js")

Example Request:

List all TypeScript files in the src directory recursively

Best Practices:

• Use patterns to filter large directories
• Enable recursive for deep searches
• Exclude node_modules and build folders

search_files

Search for text patterns across multiple files using regex.

Usage:

• Find function definitions
• Locate variable usage
• Search for TODO comments
• Find code patterns

Parameters:

• path (string, required) - Directory path to search
• regex (string, required) - Regular expression pattern
• file_pattern (string, optional) - File filter pattern

Example Request:

Search for all TODO comments in the src directory

Best Practices:

• Use specific regex patterns
• Filter by file type to reduce noise
• Test regex patterns before searching
• Use case-insensitive flags when appropriate

list_code_definition_names

Extract class, function, method, and variable names from a file using AST parsing.

Usage:

• Understand file structure
• Find available functions
• Navigate large files
• Generate code documentation

Parameters:

• path (string, required) - File path relative to workspace root

Example Request:

Show me all function names defined in src/services/api.ts

Best Practices:

• Use for large files to get overview
• Helps understand module exports
• Useful before refactoring
• Works with 40+ languages

Code Editing Tools

apply_diff

Apply a unified diff patch to a file, making precise changes.

Usage:

• Modify specific lines
• Add or remove code sections
• Refactor existing code
• Fix bugs

Parameters:

• path (string, required) - File path relative to workspace root
• diff (string, required) - Unified diff format patch

Example Request:

Update the fetchUser function in src/api/users.ts to add error handling

Best Practices:

• Preferred method for modifying existing files
• Preserves unchanged code
• Works with fuzzy matching
• Review diff before applying

insert_content

Insert content at a specific line in a file.

Usage:

• Add new functions
• Insert imports
• Add comments
• Insert test cases

Parameters:

• path (string, required) - File path relative to workspace root
• line (number, required) - Line number to insert at (1-indexed)
• content (string, required) - Content to insert

Example Request:

Add a new import statement at the top of src/app.ts

Best Practices:

• Verify line numbers before inserting
• Maintain proper indentation
• Consider using apply_diff for complex insertions

search_and_replace

Find and replace text patterns across one or multiple files.

Usage:

• Rename variables across files
• Update API endpoints
• Fix typos
• Refactor common patterns

Parameters:

• path (string or array, required) - File path(s) or directory
• search (string, required) - Text or regex to search for
• replace (string, required) - Replacement text
• regex (boolean, optional) - Use regex mode (default: false)

Example Request:

Rename all occurrences of oldFunctionName to newFunctionName in src/

Best Practices:

• Test on single file first
• Use regex for complex patterns
• Review changes before committing
• Create backup or checkpoint first

Code Analysis Tools

semantic_search

Search codebase using semantic similarity, finding conceptually related code.

Usage:

• Find similar implementations
• Locate related functionality
• Discover duplicate logic
• Understand code patterns

Parameters:

• query (string, required) - Natural language description
• threshold (number, optional) - Similarity threshold (0.0-1.0, default: 0.7)
• max_results (number, optional) - Maximum results to return (default: 10)

Example Request:

Find all code related to user authentication

Best Practices:

• Use descriptive queries
• Adjust threshold for precision vs. recall
• Combine with traditional search
• Review results for relevance

ast_parse

Parse file into Abstract Syntax Tree and extract structural information.

Usage:

• Understand code structure
• Extract function signatures
• Find class hierarchies
• Analyze imports/exports

Parameters:

• path (string, required) - File path relative to workspace root
• extract_types (array, optional) - Types to extract (functions, classes, variables, imports)

Example Request:

Parse src/models/User.ts and show all classes and methods

Best Practices:

• Supports 40+ languages
• Useful for large files
• Helps with refactoring
• Generates documentation base

analyze_dependencies

Analyze file dependencies and identify imports/exports relationships.

Usage:

• Understand module structure
• Find circular dependencies
• Plan refactoring
• Generate dependency graphs

Parameters:

• path (string, required) - File or directory path
• depth (number, optional) - Analysis depth (default: 3)
• include_external (boolean, optional) - Include node_modules (default: false)

Example Request:

Analyze dependencies for src/app/ and find circular dependencies

Best Practices:

• Start with single files
• Limit depth for large projects
• Exclude external packages initially
• Use for refactoring planning

find_component_usages

Find all locations where a component, function, or class is used.

Usage:

• Assess refactoring impact
• Find all usages before changes
• Understand component relationships
• Plan deprecation strategy

Parameters:

• component_name (string, required) - Component/function name
• path (string, optional) - Directory to search (default: workspace root)

Example Request:

Find all usages of the Button component in the codebase

Best Practices:

• Run before renaming or removing code
• Check results before making changes
• Consider transitive dependencies
• Use with analyze_impact

analyze_impact

Analyze potential impact of changing a file or component.

Usage:

• Risk assessment before changes
• Understand blast radius
• Plan migration strategy
• Identify affected tests

Parameters:

• path (string, required) - File path to analyze
• change_type (string, optional) - Type of change (modify, delete, rename)

Example Request:

Analyze the impact of modifying src/core/config.ts

Best Practices:

• Always run before major changes
• Review affected files
• Plan rollback strategy
• Update dependent code first

Testing & Quality Tools

generate_tests

Automatically generate test cases for a file or function.

Usage:

• Create unit tests
• Generate integration tests
• Add edge case tests
• Improve test coverage

Parameters:

• path (string, required) - File path to test
• test_framework (string, optional) - Framework (jest, mocha, pytest, junit)
• test_type (string, optional) - Type (unit, integration, e2e)
• include_edge_cases (boolean, optional) - Generate edge cases (default: true)

Example Request:

Generate unit tests for src/utils/validators.ts using Jest

Best Practices:

• Specify test framework
• Review generated tests
• Add custom test cases
• Run tests before committing

Terminal Operations

execute_command

Execute a command in the integrated terminal.

Usage:

• Run build commands
• Execute tests
• Git operations
• Install dependencies

Parameters:

• command (string, required) - Command to execute
• working_directory (string, optional) - Directory to run command in
• wait_for_completion (boolean, optional) - Wait for command to finish (default: true)

Example Request:

Run npm test to execute the test suite

Best Practices:

• Use allowed commands list for safety
• Review command before execution
• Monitor output for errors
• Set appropriate working directory

Security Note: Commands must be in the allowed commands list or approved manually. Configure in settings.

Browser Automation

browser_action

Control a browser instance for testing, research, or web scraping.

Usage:

• Test web applications
• Take screenshots
• Research documentation
• Extract web content

Parameters:

• action (string, required) - Action type (navigate, screenshot, click, type, extract)
• url (string, required for navigate) - URL to visit
• selector (string, optional) - CSS selector for element actions
• value (string, optional) - Value for type action

Example Request:

Navigate to our staging site and take a screenshot

Best Practices:

• Configure viewport size in settings
• Use appropriate selectors
• Handle page load times
• Close browser when done

MCP Integration

use_mcp_tool

Use a tool provided by an MCP (Model Context Protocol) server.

Usage:

• Access external services
• Use specialized tools
• Integrate third-party services
• Extend agent capabilities

Parameters:

• server_name (string, required) - MCP server name
• tool_name (string, required) - Tool to invoke
• arguments (object, required) - Tool-specific arguments

Example Request:

Use the database MCP server to query user records

Best Practices:

• Configure MCP servers first
• Review available tools
• Understand tool parameters
• Handle tool failures gracefully

access_mcp_resource

Access a resource provided by an MCP server.

Usage:

• Fetch external data
• Access remote resources
• Integrate data sources
• Read configuration

Parameters:

• server_name (string, required) - MCP server name
• resource_uri (string, required) - Resource identifier
• options (object, optional) - Resource-specific options

Example Request:

Access the API documentation resource from the docs MCP server

Best Practices:

• Verify resource availability
• Cache frequently accessed resources
• Handle access errors
• Check resource permissions

Task Management Tools

attempt_completion

Signal that a task is complete and provide a summary.

Usage:

• Finish current task
• Provide completion summary
• Present results to user
• Request confirmation

Parameters:

• result (string, required) - Task completion summary
• files_modified (array, optional) - List of modified files

Example Request: Agent uses automatically when task is complete

Best Practices:

• Agent decides when to use
• Reviews all changes made
• Summarizes accomplishments
• Lists affected files

new_task

Start a new task, clearing previous context.

Usage:

• Begin unrelated task
• Reset conversation context
• Start fresh workflow
• Change focus area

Parameters:

• task_description (string, required) - Description of new task

Example Request:

Start a new task to implement user profile page

Best Practices:

• Use when switching contexts
• Clears previous task state
• Starts new conversation
• Previous history saved

ask_followup_question

Ask the user for clarification or additional information.

Usage:

• Clarify ambiguous requests
• Request missing information
• Confirm assumptions
• Get user preferences

Parameters:

• question (string, required) - Question for the user
• options (array, optional) - Multiple choice options

Example Request: Agent uses automatically when clarification needed

Best Practices:

• Agent uses when uncertain
• Provides context for question
• Offers options when applicable
• Waits for user response

switch_mode

Switch between different agent operating modes.

Usage:

• Change agent capabilities
• Enable specialized features
• Adjust tool availability
• Change behavior patterns

Parameters:

• mode (string, required) - Target mode name

Available Modes:

• code - Code implementation and modification
• debug - Debugging and error analysis
• architect - System design and planning
• ask - Q&A and explanations
• orchestrator - Multi-mode workflow coordination

Example Request:

Switch to debug mode to investigate this error

Best Practices:

• Use appropriate mode for task
• Understand mode capabilities
• Switch modes as needed
• See Modes Guide for details

Instructions

fetch_instructions

Fetch and follow instructions from a file or URL.

Usage:

• Load workflow templates
• Follow project guidelines
• Execute predefined steps
• Apply coding standards

Parameters:

• source (string, required) - File path or URL to instructions
• format (string, optional) - Instruction format (markdown, json, yaml)

Example Request:

Follow the coding standards in docs/coding-standards.md

Best Practices:

• Use for consistent workflows
• Store instructions in version control
• Update instructions regularly
• Share across team

VS Code Commands

Dropstone Agent provides several commands accessible via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Core Commands

Context Menu Commands

Available when right-clicking in editor:

Terminal Commands

Available when right-clicking in terminal:

Workspace Commands

Authentication Commands

Tool Categories Summary

By Operation Type

Read Operations (require approval based on settings):

• read_file
• list_files
• search_files
• list_code_definition_names
• semantic_search
• ast_parse
• analyze_dependencies
• find_component_usages

Write Operations (require approval based on settings):

• write_to_file
• delete_file
• apply_diff
• insert_content
• search_and_replace

Execute Operations (require approval based on settings):

• execute_command
• browser_action

Analysis Operations (typically auto-approved):

• analyze_impact
• generate_tests

System Operations (always auto-approved):

• attempt_completion
• new_task
• ask_followup_question
• switch_mode

By Use Case

Code Understanding:

• read_file, list_code_definition_names, ast_parse, semantic_search

Code Modification:

• apply_diff, write_to_file, insert_content, search_and_replace

Quality Assurance:

• generate_tests, analyze_impact, find_component_usages

Project Navigation:

• list_files, search_files, analyze_dependencies

Development Workflow:

• execute_command, browser_action, use_mcp_tool

Task Management:

• attempt_completion, new_task, ask_followup_question, switch_mode

Best Practices

General Guidelines

1. Start with Read Operations - Always read before write
2. Review Before Approve - Check tool parameters carefully
3. Use Specific Paths - Provide complete, accurate file paths
4. Enable Auto-Approve Gradually - Start restrictive, loosen as comfortable
5. Monitor Tool Usage - Check tool calls in chat history

Safety Recommendations

1. Version Control - Always use Git or similar
2. Enable Checkpoints - For easy rollback
3. Backup Important Files - Before major operations
4. Test Changes - Run tests after modifications
5. Review Diffs - Before applying to production code

Performance Tips

1. Use Specific Tools - Don't search when you know the path
2. Limit Search Scope - Use path and pattern filters
3. Batch Operations - Combine related operations
4. Close Browser Sessions - Free resources when done
5. Prune History - Archive old tasks

Next Steps

• Learn about Auto-Approve Settings
• Explore Agent Modes
• Read Best Practices
• View Use Case Examples

For tool troubleshooting, see the Troubleshooting Guide.