amcs/llm/core_tools.md

# AMCS Core Tools — Implementation Plan

Tools that expose runtime context to agents and provide general-purpose capabilities: time, location, connectivity, health, data quality, credentials, background jobs, change detection, HTTP, computation, secrets, webhooks, and context management.

---

## 1. Date / Time / Timezone

**Tool:** `get_datetime`

- Return current UTC time, local server time, and timezone identifier (IANA)
- Include Unix timestamp, ISO 8601 string, day-of-week, week number
- Relative helpers: is_business_hours, start_of_day, start_of_week (relative to server TZ)

---

## 2. Location

**Tool:** `get_location`

Three scopes returned in one call:

| Scope | Data |
|-------|------|
| Server | hostname, OS, datacenter/cloud region if detectable |
| Project | active project name, working directory, git repo root, current branch, last commit hash+message |
| User | IP-derived city/country (GeoIP), configurable home location override in config |

---

## 3. Connectivity & Health

**Tool:** `get_health`

- AMCS server version and uptime
- Database connection status and round-trip latency (ms)
- pgvector extension present and version
- LiteLLM / OpenRouter reachability (HEAD ping, latency, last-ok timestamp)
- Configured integration endpoints (n8n, Telegram, etc.) — status and last-ok timestamp
- Overall status: `ok` / `degraded` / `down`

---

## 4. Data Quality & Maintenance

**Tool:** `get_data_quality`

- Total thoughts, plans, learnings, projects
- Thoughts missing embeddings (count + oldest)
- Failed metadata reparse queue depth
- Orphaned records: thoughts with no project, broken thought links, plans with missing dependencies
- Last embedding backfill run timestamp and result

---

## 5. Security & Credentials

**Tool:** `get_credential_status`

- Per-configured integration: name, valid/expired boolean, days until expiry (no values exposed)
- Last successful authentication timestamp per integration
- AMCS token expiry if applicable

---

## 6. Background Job Status

**Tool:** `get_job_status`

- List of known async job types (embedding backfill, metadata reparse, file indexing)
- Per job: status (idle/running/failed), last run timestamp, last run duration, error if failed
- Pending queue depth per job type

---

## 7. Change Detection

**Tool:** `get_changes`

Parameters:
- `since` — ISO 8601 timestamp or relative shorthand (`1h`, `24h`, `7d`)
- `scope` — `all` | `thoughts` | `plans` | `learnings` | `projects`

Returns:
- Counts of created, updated, deleted per entity type since the given time
- Top 5 most recently modified items per type (id, title, updated_at)
- Active project changes highlighted separately

---

---

## 8. HTTP Client

**Tool:** `http_request`

Parameters:
- `method` — GET | POST | PUT | PATCH | DELETE
- `url` — target URL
- `headers` — optional map of header key/value pairs
- `body` — optional string body (JSON, form, etc.)
- `timeout_seconds` — default 30

Returns: status code, response headers, body (truncated at configurable limit), latency (ms)

Restrictions:
- Blocklist for private/internal IP ranges (configurable allow-override)
- Max response body size configurable (`http_client.max_body_bytes`)
- Requires `tools.http_client: true` in config to enable

---

## 9. Token Counter

**Tool:** `count_tokens`

Parameters:
- `text` — string to count
- `model` — optional model name to select tokenizer (default: configured primary model)

Returns: token count, estimated cost (input only), tokenizer used

- Uses tiktoken-compatible tokenizer; falls back to char/4 estimate if model unknown

---

## 10. Text Diff

**Tool:** `diff_text`

Parameters:
- `a` — original text
- `b` — revised text
- `format` — `unified` | `side_by_side` | `summary` (default: `summary`)

Returns: diff output and change stats (lines added, removed, unchanged)

---

## 11. Data Parser

**Tool:** `parse_data`

Parameters:
- `input` — raw string
- `format` — `json` | `csv` | `xml` | `toml` | `yaml`
- `query` — optional JSONPath / XPath / key path to extract a subset

Returns: parsed structure as JSON, or extracted value if query provided

---

## 12. Template Renderer

**Tool:** `render_template`

Parameters:
- `template` — Go `text/template` or Mustache string
- `vars` — key/value map of variables to inject

Returns: rendered string

Use case: build dynamic prompts or messages from stored templates and runtime context.

---

## 13. Secret Retrieval

**Tool:** `get_secret`

Parameters:
- `name` — secret name as configured in AMCS secrets store

Returns: secret value (transmitted but never logged by server)

- Secrets defined in config or environment under `secrets.*`
- Access requires authenticated token with `secrets:read` scope
- Audit log entry written on every retrieval (name, caller, timestamp — not value)

---

## 14. Webhook Trigger

**Tool:** `trigger_webhook`

Parameters:
- `name` — named webhook as configured in `webhooks.*`
- `payload` — optional JSON body to merge with default payload

Returns: HTTP status from target, latency (ms)

- Named webhooks defined in config (URL + default headers/auth) — agents never see the raw URL or credentials
- Supports n8n, Zapier, generic HTTP targets

---

## 15. Summarize / Compress

**Tool:** `summarize`

Parameters:
- `text` — content to summarize
- `max_tokens` — target output length in tokens (default: 200)
- `style` — `bullets` | `paragraph` | `headline` (default: `paragraph`)
- `focus` — optional hint string ("focus on action items", "focus on errors")

Returns: summarized text, input token count, output token count

- Calls the configured LLM; billed against the AMCS service account
- Useful for compressing large file loads or long thought chains before embedding

---

## 16. Chunk Text

**Tool:** `chunk_text`

Parameters:
- `text` — content to split
- `chunk_size` — max tokens per chunk (default: 512)
- `overlap` — token overlap between chunks (default: 50)
- `model` — tokenizer model (default: configured primary)

Returns: array of chunk strings with index and token count per chunk

---

## 17. Schedule Action

**Tool:** `schedule_action`

Parameters:
- `run_at` — ISO 8601 datetime or cron expression
- `tool` — tool name to invoke
- `args` — arguments for the tool
- `label` — optional human-readable label

Returns: scheduled action ID

**Tool:** `list_scheduled_actions`
- Returns pending actions: id, label, tool, run_at, status

**Tool:** `cancel_scheduled_action`
- Parameter: `id`

---

## Implementation Notes

**Context & read-only tools (1–7):**
- All read-only, no write permissions required
- GeoIP opt-in via config (`core_tools.geoip: true`), offline MaxMind GeoLite2 DB
- Credential expiry checks never log or return secret values — metadata only
- `get_health` callable unauthenticated (mirrors existing `/health` endpoint)
- `get_changes` is query-heavy — 30s cache TTL to avoid repeated aggregation

**Agent utility tools (8–17):**
- `http_request` disabled by default; requires `tools.http_client: true` in config; private IP ranges blocked
- `get_secret` requires `secrets:read` token scope; every retrieval audit-logged (name + caller only)
- `trigger_webhook` never exposes raw URLs or credentials to agents — named config only
- `summarize` and `chunk_text` call the configured LLM; usage billed to AMCS service account
- `schedule_action` backed by the existing cron/trigger infrastructure
- All tools registered under the `core` category in `describe_tools`