docs(tools): add README for brevo, csv, runtime_logs, account_info tools

tools/src/aden_tools/tools/account_info_tool/README.md

@@ -0,0 +1,104 @@
+# Account Info Tool
+
+Query connected accounts and their identities at runtime.
+
+## Features
+
+- **get_account_info** - List connected accounts with provider and identity details
+
+## Overview
+
+This tool allows agents to discover which external accounts are connected and available for use. It queries the credential store to retrieve account metadata without exposing secrets.
+
+## Setup
+
+No additional configuration required. The tool reads from the configured credential store.
+
+## Usage Examples
+
+### List All Connected Accounts
+```python
+get_account_info()
+```
+
+Returns:
+```python
+{
+    "accounts": [
+        {
+            "account_id": "google_main",
+            "provider": "google",
+            "identity": "user@gmail.com"
+        },
+        {
+            "account_id": "slack_workspace",
+            "provider": "slack",
+            "identity": "My Workspace"
+        }
+    ],
+    "count": 2
+}
+```
+
+### Filter by Provider
+```python
+get_account_info(provider="google")
+```
+
+Returns only Google-connected accounts:
+```python
+{
+    "accounts": [
+        {
+            "account_id": "google_main",
+            "provider": "google",
+            "identity": "user@gmail.com"
+        }
+    ],
+    "count": 1
+}
+```
+
+## API Reference
+
+### get_account_info
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| provider | str | No | Filter by provider type (e.g., "google", "slack") |
+
+### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| accounts | list | List of connected account objects |
+| count | int | Number of accounts returned |
+
+### Account Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| account_id | str | Unique identifier for the account |
+| provider | str | Provider type (google, slack, github, etc.) |
+| identity | str | Human-readable identity (email, username, workspace) |
+
+## Supported Providers
+
+Common providers that may appear:
+- `google` - Google accounts (Gmail, Drive, Calendar)
+- `slack` - Slack workspaces
+- `github` - GitHub accounts
+- `hubspot` - HubSpot CRM accounts
+- `brevo` - Brevo email/SMS accounts
+- And any other configured OAuth or API integrations
+
+## Error Handling
+```python
+{"accounts": [], "message": "No credential store configured"}
+```
+
+## Use Cases
+
+- **Multi-account workflows**: Determine which accounts are available before making API calls
+- **User context**: Show users which accounts are connected in chat interfaces
+- **Conditional logic**: Route tasks to different accounts based on availability

tools/src/aden_tools/tools/csv_tool/README.md

@@ -0,0 +1,168 @@
+# CSV Tool
+
+Read, write, and query CSV files with SQL support via DuckDB.
+
+## Features
+
+- **csv_read** - Read CSV file contents with pagination
+- **csv_write** - Create new CSV files
+- **csv_append** - Append rows to existing CSV files
+- **csv_info** - Get CSV metadata without loading all data
+- **csv_sql** - Query CSV files using SQL (powered by DuckDB)
+
+## Setup
+
+No API keys required. Files are accessed within the session sandbox.
+
+For SQL queries, DuckDB must be installed:
+```bash
+pip install duckdb
+# or
+uv pip install tools[sql]
+```
+
+## Usage Examples
+
+### Read a CSV File
+```python
+csv_read(
+    path="data/sales.csv",
+    workspace_id="ws_123",
+    agent_id="agent_1",
+    session_id="session_1",
+    limit=100,
+    offset=0
+)
+```
+
+### Write a New CSV
+```python
+csv_write(
+    path="output/report.csv",
+    workspace_id="ws_123",
+    agent_id="agent_1",
+    session_id="session_1",
+    columns=["name", "email", "score"],
+    rows=[
+        {"name": "Alice", "email": "alice@example.com", "score": 95},
+        {"name": "Bob", "email": "bob@example.com", "score": 87}
+    ]
+)
+```
+
+### Append Rows
+```python
+csv_append(
+    path="data/log.csv",
+    workspace_id="ws_123",
+    agent_id="agent_1",
+    session_id="session_1",
+    rows=[
+        {"timestamp": "2024-01-15", "event": "login", "user": "alice"}
+    ]
+)
+```
+
+### Get File Info
+```python
+csv_info(
+    path="data/large_file.csv",
+    workspace_id="ws_123",
+    agent_id="agent_1",
+    session_id="session_1"
+)
+# Returns: columns, row count, file size (without loading all data)
+```
+
+### Query with SQL
+```python
+csv_sql(
+    path="data/sales.csv",
+    workspace_id="ws_123",
+    agent_id="agent_1",
+    session_id="session_1",
+    query="SELECT category, SUM(amount) as total FROM data GROUP BY category ORDER BY total DESC"
+)
+```
+
+## API Reference
+
+### csv_read
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| path | str | Yes | Path to CSV file (relative to sandbox) |
+| workspace_id | str | Yes | Workspace identifier |
+| agent_id | str | Yes | Agent identifier |
+| session_id | str | Yes | Session identifier |
+| limit | int | No | Max rows to return (None = all) |
+| offset | int | No | Rows to skip (default: 0) |
+
+### csv_write
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| path | str | Yes | Path for new CSV file |
+| workspace_id | str | Yes | Workspace identifier |
+| agent_id | str | Yes | Agent identifier |
+| session_id | str | Yes | Session identifier |
+| columns | list[str] | Yes | Column names for header |
+| rows | list[dict] | Yes | Row data as dictionaries |
+
+### csv_append
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| path | str | Yes | Path to existing CSV file |
+| workspace_id | str | Yes | Workspace identifier |
+| agent_id | str | Yes | Agent identifier |
+| session_id | str | Yes | Session identifier |
+| rows | list[dict] | Yes | Rows to append |
+
+### csv_info
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| path | str | Yes | Path to CSV file |
+| workspace_id | str | Yes | Workspace identifier |
+| agent_id | str | Yes | Agent identifier |
+| session_id | str | Yes | Session identifier |
+
+### csv_sql
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| path | str | Yes | Path to CSV file |
+| workspace_id | str | Yes | Workspace identifier |
+| agent_id | str | Yes | Agent identifier |
+| session_id | str | Yes | Session identifier |
+| query | str | Yes | SQL query (table name is `data`) |
+
+## SQL Query Examples
+```sql
+-- Filter rows
+SELECT * FROM data WHERE status = 'pending'
+
+-- Aggregate data
+SELECT category, COUNT(*) as count, AVG(price) as avg_price 
+FROM data GROUP BY category
+
+-- Sort and limit
+SELECT name, price FROM data ORDER BY price DESC LIMIT 5
+
+-- Case-insensitive search
+SELECT * FROM data WHERE LOWER(name) LIKE '%phone%'
+```
+
+**Note:** Only SELECT queries are allowed for security.
+
+## Error Handling
+```python
+{"error": "File not found: path/to/file.csv"}
+{"error": "File must have .csv extension"}
+{"error": "CSV file is empty or has no headers"}
+{"error": "CSV parsing error: ..."}
+{"error": "File encoding error: unable to decode as UTF-8"}
+{"error": "DuckDB not installed. Install with: uv pip install duckdb"}
+{"error": "Only SELECT queries are allowed for security reasons"}
+```

tools/src/aden_tools/tools/runtime_logs_tool/README.md

@@ -0,0 +1,121 @@
+# Runtime Logs Tool
+
+Query the three-level runtime logging system for agent execution history.
+
+## Features
+
+- **query_runtime_logs** - Level 1: Run summaries (did the graph succeed?)
+- **query_runtime_log_details** - Level 2: Per-node results (which node failed?)
+- **query_runtime_log_raw** - Level 3: Full step data (what exactly happened?)
+
+## Overview
+
+The runtime logging system captures agent execution at three levels of detail:
+
+| Level | Tool | Purpose | Data |
+|-------|------|---------|------|
+| L1 | `query_runtime_logs` | Run summaries | Success/failure, duration, entry point |
+| L2 | `query_runtime_log_details` | Node-level results | Per-node outcomes, errors, retries |
+| L3 | `query_runtime_log_raw` | Full step data | Complete execution trace, LLM calls |
+
+## Setup
+
+No API keys required. Logs are read from the agent's working directory.
+
+## Usage Examples
+
+### Get Run Summaries (Level 1)
+```python
+query_runtime_logs(
+    agent_work_dir="/path/to/agent/workdir",
+    limit=10
+)
+```
+
+Returns recent runs with:
+- Run ID and session ID
+- Start/end timestamps
+- Success/failure status
+- Entry point used
+- Duration
+
+### Get Node Details (Level 2)
+```python
+query_runtime_log_details(
+    agent_work_dir="/path/to/agent/workdir",
+    run_id="run_20240115_143022"
+)
+```
+
+Returns per-node execution details:
+- Node ID and name
+- Execution status (success/failure/skipped)
+- Error messages if failed
+- Retry count
+- Input/output keys
+
+### Get Raw Step Data (Level 3)
+```python
+query_runtime_log_raw(
+    agent_work_dir="/path/to/agent/workdir",
+    run_id="run_20240115_143022",
+    node_id="gather_info"  # Optional: filter by node
+)
+```
+
+Returns complete execution trace:
+- Every LLM call with prompts/responses
+- Tool invocations and results
+- State changes
+- Timing information
+
+## API Reference
+
+### query_runtime_logs
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| agent_work_dir | str | Yes | Path to agent working directory |
+| limit | int | No | Max runs to return (default: 20) |
+| status | str | No | Filter: "success", "failure", "degraded", "in_progress", "needs_attention" |
+
+### query_runtime_log_details
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| agent_work_dir | str | Yes | Path to agent working directory |
+| run_id | str | Yes | Run ID from Level 1 query |
+| needs_attention_only | bool | No | If true, only return flagged nodes (default: false) |
+| node_id | str | No | Filter to specific node |
+
+### query_runtime_log_raw
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| agent_work_dir | str | Yes | Path to agent working directory |
+| run_id | str | Yes | Run ID from Level 1 query |
+| node_id | str | No | Filter to specific node |
+| step_index | int | No | Specific step index, or -1 for all steps (default: -1) |
+
+## Log Storage Locations
+```
+{agent_work_dir}/
+├── sessions/{session_id}/logs/    # New location
+│   ├── summary.json               # L1: Run summary
+│   ├── details.jsonl              # L2: Node details
+│   └── tool_logs.jsonl            # L3: Raw steps
+└── runtime_logs/runs/{run_id}/    # Legacy location (deprecated)
+```
+
+## Error Handling
+```python
+{"runs": [], "total": 0, "message": "No runtime logs found"}
+{"error": "No details found for run <run_id>"}
+{"error": "No tool logs found for run <run_id>"}
+```
+
+## Use Cases
+
+- **Debugging failed runs**: Start with L1 to find failures, drill into L2 for the failing node, then L3 for exact error
+- **Performance analysis**: Use L1 durations to identify slow runs, L3 for detailed timing
+- **Audit trails**: L3 provides complete execution history for compliance