> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-corex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute Tool Endpoint

> Complete reference for the /execute_tool API endpoint with detailed examples, parameter specifications, and comprehensive error handling strategies for tool execution

## Execute Tool Endpoint

**POST** `/v1/execute_tool`

Execute a tool with specified parameters and get results.

***

## Request Body

```json theme={null}
{
  "tool_name": "create-pull-request",
  "params": {
    "repository": "owner/repo",
    "title": "Add new feature",
    "from_branch": "feature/x",
    "to_branch": "main"
  },
  "timeout": 30000
}
```

### Parameters

| Parameter   | Type    | Required | Default | Description              |
| ----------- | ------- | -------- | ------- | ------------------------ |
| `tool_name` | string  | Yes      | -       | Name of tool to execute  |
| `params`    | object  | Yes      | -       | Tool-specific parameters |
| `timeout`   | integer | No       | 30000   | Timeout in milliseconds  |

***

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "tool_name": "create-pull-request",
    "status": "success",
    "result": {
      "pr_number": 123,
      "pr_url": "https://github.com/owner/repo/pull/123",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "execution_time_ms": 245,
    "tokens_used": {
      "input": 150,
      "output": 200
    }
  },
  "meta": {
    "request_id": "exec_def456",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

***

## Examples

### Create GitHub PR

```bash theme={null}
curl -X POST "https://api.agent-corex.com/v1/execute_tool" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "create-pull-request",
    "params": {
      "repository": "owner/repo",
      "title": "Fix critical bug",
      "from_branch": "hotfix/bug-123",
      "to_branch": "main",
      "body": "This PR fixes a critical production bug"
    }
  }'
```

### Deploy to AWS

```bash theme={null}
curl -X POST "https://api.agent-corex.com/v1/execute_tool" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "deploy-aws-lambda",
    "params": {
      "function_name": "my-function",
      "zip_file": "function.zip",
      "environment": "production"
    }
  }'
```

### Using SDK

```javascript theme={null}
const result = await agent.executeTool({
  toolName: 'create-pull-request',
  params: {
    repository: 'owner/repo',
    title: 'New feature',
    from_branch: 'feature/x',
    to_branch: 'main'
  }
});

console.log(`PR created: ${result.result.pr_url}`);
```

***

## Error Responses

### Tool Not Found (404)

```json theme={null}
{
  "success": false,
  "error": {
    "code": "TOOL_NOT_FOUND",
    "message": "Tool 'create-pull-request' not found or not connected"
  }
}
```

### Invalid Parameters (400)

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required parameter: repository",
    "details": {
      "parameter": "repository",
      "reason": "required"
    }
  }
}
```

### Timeout (504)

```json theme={null}
{
  "success": false,
  "error": {
    "code": "TIMEOUT",
    "message": "Tool execution timed out after 30000ms"
  }
}
```

### Execution Failed (500)

```json theme={null}
{
  "success": false,
  "error": {
    "code": "EXECUTION_ERROR",
    "message": "Failed to create PR: Branch does not exist",
    "details": {
      "tool_error": "Invalid branch name"
    }
  }
}
```

***

## Best Practices

1. **Always handle errors**
   ```javascript theme={null}
   try {
     const result = await agent.executeTool({...});
   } catch (error) {
     if (error.code === 'TOOL_NOT_FOUND') {
       // Guide user to connect tool
     }
   }
   ```

2. **Set appropriate timeouts**
   * Quick operations: 5-10 seconds
   * API calls: 15-30 seconds
   * Infrastructure tasks: 60+ seconds

3. **Validate parameters** before executing
   * Check required fields
   * Validate formats (URLs, names, etc.)

4. **Implement retry logic**
   ```javascript theme={null}
   const executeWithRetry = async (toolName, params, maxRetries = 3) => {
     for (let i = 0; i < maxRetries; i++) {
       try {
         return await agent.executeTool({ toolName, params });
       } catch (error) {
         if (error.code === 'RATE_LIMITED' && i < maxRetries - 1) {
           await delay(1000 * Math.pow(2, i)); // Exponential backoff
         } else {
           throw error;
         }
       }
     }
   };
   ```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Retrieve Tools" href="/api-reference/retrieve-tools">
    Find tools before executing.
  </Card>

  <Card title="Real Examples" href="/examples/sample-queries">
    See execution flows.
  </Card>

  <Card title="Error Handling" href="/api-reference/overview">
    Common error codes.
  </Card>
</CardGroup>

***

Ready to execute tools? See [sample queries](/examples/sample-queries) for real workflows! 🚀