Adding a New Agent Tool

Follow these steps to add a new tool that the agent can use during autonomous operations.

Step 1: Create the Tool File

Create a new file in src/agent/tools/ (e.g. src/agent/tools/myTool.ts):

import { Tool } from '../../types/agent';

export const myToolTool: Tool = {
  name: 'my_tool',
  description: 'What this tool does - be specific so the LLM knows when to use it',
  schema: {
    type: 'object',
    properties: {
      param1: { type: 'string', description: 'Param description' }
    },
    required: ['param1']
  },
  execute: async (params, context) => {
    // context.workspace is available for file operations
    // Implementation here
    return 'Result string shown to LLM';
  }
};

Argument Flexibility

For tools that accept file paths, accept multiple argument names for robustness (LLMs may use different names). Use the shared resolveWorkspacePath utility from pathUtils.ts:

import { resolveWorkspacePath } from './pathUtils';

const filePath = params.path || params.file || params.filePath;

The existing tools read_file, write_file, and get_diagnostics all follow this pattern.

Step 1b: Register in the Barrel Export

Add the new tool to src/agent/tools/index.ts:

import { myToolTool } from './myTool';

export const builtInTools: Tool[] = [
  // ... existing tools ...
  myToolTool,
];

export { myToolTool };

The ToolRegistry.registerBuiltInTools() iterates over builtInTools and registers them all automatically.

Step 2: Add UI Representation

In src/views/toolUIFormatter.ts, add a case to getToolActionInfo() so the UI shows an appropriate icon and description when the tool runs:

case 'my_tool':
  return {
    icon: '🔧',
    text: `Running my tool on ${args.param1}`,
    detail: 'Additional detail shown in collapsed view'
  };

Step 3: Understand Execution Routing

Tool execution is handled by the decomposed agent executor in src/services/agent/. The orchestrator (agentChatExecutor.ts) delegates tool execution to agentToolRunner.ts, which calls ToolRegistry.execute() for standard tools.

Where to add special execution logic:

• Standard tools (read/write/search): Create file in src/agent/tools/ and add to index.ts — agentToolRunner.ts calls them automatically via ToolRegistry.execute()
• Terminal commands: Handled by agentTerminalHandler.ts (approval + execution)
• File edits: Handled by agentFileEditHandler.ts (sensitivity check + approval)
• New execution category: Create a new sub-handler in src/services/agent/ — do NOT add logic to agentChatExecutor.ts

See agent-tools.instructions.md → "Agent Executor Architecture" for the full decomposition rules.

Step 3: Add to Settings UI (if toggleable)

If the tool should be individually enable/disable-able, add it to the Tools section in the settings page (src/webview/components/settings/components/ToolsSection.vue).

Step 4: Write Tests

Add tests in tests/extension/suite/agent/toolRegistry.test.ts:

test('my_tool: basic functionality', async () => {
  const result = await toolRegistry.execute('my_tool', {
    param1: 'test-value'
  }, context);
  assert.ok(result.includes('expected output'));
});

// Test argument name flexibility if applicable
test('my_tool: accepts alternative param names', async () => {
  // ...
});

Step 5: Update Instructions

If the tool introduces new conventions or critical rules, update the relevant .github/instructions/*.instructions.md file (likely agent-tools.instructions.md).

Checklist

• Tool file created in src/agent/tools/ with clear description and schema
• Tool added to builtInTools array in src/agent/tools/index.ts
• UI representation in toolUIFormatter.ts
• Tests covering happy path and argument flexibility
• npm run lint:all passes (ESLint + docs + naming)
• Settings toggle (if applicable)
• Instructions updated (if new conventions introduced)