Purpose: Check that the configured RawTree API endpoint is reachable.

NOT for: Validating project permissions or checking whether a specific table exists. Use list-tables or run-query for authenticated checks.

Returns: The RawTree health response.

When to use:

• User asks whether RawTree is up

• You changed RAWTREE_URL and need to confirm the server responds

• You are debugging MCP configuration before using authenticated tools

Purpose: Execute a read-only SQL query against the configured RawTree project and return JSON rows, column metadata, statistics, and hints.

NOT for: Inserting, updating, deleting, or mutating data. RawTree validates queries as read-only and rejects unsafe statements.

Returns: RawTree's query response: meta, data, rows, statistics, and optional hints.

When to use:

• User asks questions about data already in RawTree

• You need to verify an insert

• You need a quick aggregate, sample, or schema-oriented SELECT

• You need RawTree query hints after an error

Workflow: Start with a bounded SELECT. For exploratory queries, include LIMIT and order by a time column when available.

Key trigger phrases: "query RawTree", "run SQL", "count rows", "show sample rows", "check the data"

Purpose: Insert one JSON object or an array of JSON objects into a RawTree table. RawTree auto-creates the table on first insert.

NOT for: Loading data from a public URL (use insert-from-url). Not for transformed URL ingest; transforms only apply to JSON request bodies.

Returns: Insert confirmation, usually { "inserted": <row_count> }. Firehose transform returns request metadata.

When to use:

• User wants to send events, logs, traces, metrics, or arbitrary records to RawTree

• You need to create a table by inserting the first row

• You need to validate that RawTree accepts a payload shape

• You have OTLP, CloudWatch Logs, CloudTrail, or Firehose JSON that should be flattened by RawTree

Workflow: Choose a table name → send a small representative payload → run describe-table or run-query to verify.

Key trigger phrases: "insert this", "send event", "write to RawTree", "create table with data", "ingest JSON"

Purpose: Ask RawTree to ingest JSON/JSONL data from a public URL into a table. RawTree streams progress as NDJSON.

NOT for: Private files on your machine, authenticated URLs, or built-in transforms. Host transformed data first or use insert-json with transform.

Returns: The RawTree NDJSON progress stream as text.

When to use:

• User has a public JSON or JSONL file URL

• You need RawTree to fetch and ingest the file directly

• The data is too large or inconvenient to paste into the MCP call

Workflow: Confirm the URL is public → call insert-from-url → use list-logs and run-query to verify.

Key trigger phrases: "ingest this URL", "load JSONL from", "import from public file"

Purpose: List all tables in the configured RawTree project with row and byte counts.

NOT for: Reading table rows. Use run-query for data and describe-table for columns.

Returns: Tables plus project and organization context.

When to use:

• User asks what data exists

• You need a table name before querying

• You want to verify that an insert auto-created a table

Purpose: Inspect a RawTree table's columns, row count, byte count, project, and organization.

NOT for: Sampling actual row values. Use run-query for SELECT queries.

Returns: Table metadata and columns.

When to use:

• You need to know available fields before writing SQL

• A query fails because a column may not exist

• You just inserted data and want to inspect the dynamic schema

Purpose: Permanently delete a RawTree table and its data.

NOT for: Clearing a query result or undoing a single insert. This deletes the whole table.

Returns: Deletion confirmation.

Safety: You MUST ask the user to confirm the exact table name before calling this tool. This action requires an admin key and cannot be undone.

Purpose: List recent RawTree insert/query/describe/explain activity for the configured project.

NOT for: Reading application log files from disk or infrastructure logs. This tool reads RawTree's product query and insert logs.

Returns: Log entries with time, type, status, origin, query, exception, rows, duration, bytes, tables, projections, hints, and pagination.

When to use:

• An insert or query failed and you need the RawTree exception or hints

• You need to verify whether an agent, CLI, API, or UI call reached RawTree

• You need recent activity for a table

• You want the exact SQL RawTree saw

Workflow: Start with status=error for the last hour. Narrow by table or type if needed. Use next_offset for pagination.

Key trigger phrases: "check RawTree logs", "why did the insert fail", "show query history", "recent errors"

Purpose: List API keys for the configured RawTree project.

NOT for: Creating or revoking credentials. Use create-api-key or delete-api-key for those workflows.

Returns: API key names, IDs, token hints, permissions, project, organization, and creation dates.

Auth: Unscoped /v1/keys requires an admin project API key. When RAWTREE_ORG and RAWTREE_PROJECT are configured, this uses RawTree's scoped route.

When to use:

• User asks what API keys exist

• You need the key ID before revoking a key

• You need to audit permissions for a project

Purpose: Create a new RawTree API key for the configured project.

NOT for: User login or creating projects. Use RawTree auth/CLI or the dashboard for those workflows.

Returns: The new API key token. The token is only shown once, so you MUST display it to the user.

Auth: Requires admin permission for unscoped project API key auth. When RAWTREE_ORG and RAWTREE_PROJECT are configured, this uses RawTree's scoped route.

When to use:

• User needs a key for CI, an agent, a connector, or a script

• User wants a read-only, write-only, read-write, or admin credential

• User asks to rotate credentials by creating a replacement before revoking the old key

Purpose: Permanently revoke and delete a RawTree API key by UUID or full token.

NOT for: Deleting a table, project, or user session.

Returns: Deletion confirmation.

Safety: You MUST list or identify the key first, ask the user to confirm the exact key name or ID, and warn that services using it will lose access. This action cannot be undone.

Purpose: Return the configured RawTree project identity using the current token.

NOT for: Listing tables inside a project. Use list-tables for project data.

Returns: A compact project shape: { "name": "...", "organization": { "name": "..." } }.

Auth: Uses GET /v1/keys and parses the project and organization from that response. If the current project API key cannot list keys, it falls back to GET /v1/tables, which exposes the same project identity for read-capable keys.

When to use:

• You need to know which RawTree project the current API key belongs to

• You are setting up an MCP client and want to confirm the active project

• You want the organization name without requiring a separate project endpoint