# Insights and hosting tools

Beyond authoring, your agent can read how your docs perform and configure how they are hosted. That closes a loop unique to agent-native docs: the same tool that writes your articles can see which questions visitors asked that the docs could not answer, then fix the gap.

## At a glance

| Tool | What it does | Who can use it |
| --- | --- | --- |
| `list_conversations` | Lists visitor AI conversations | Any member |
| `get_conversation` | Fetches one conversation transcript | Any member |
| `get_insights` | Summarizes 30 days of docs activity | Any member |
| `set_docs_base_url` | Hosts docs under your own path, like yoursite.com/docs | Owner or admin |
| `remove_docs_base_url` | Reverts to your clayo.site address | Owner or admin |
| `set_widget_questions` | Sets the widget's starter questions | Owner or admin |
| `clear_widget_questions` | Reverts starter questions to automatic | Owner or admin |

## Conversations

Visitors ask questions through [Ask AI on your docs site](/articles/ask-ai) and the [support widget](/articles/add-the-widget). Those conversations are stored anonymously for 30 days, and your agent can read them.

### list_conversations

Lists recent conversations with filters that make gap-hunting practical: only unanswered conversations, text search, conversations since a date, or conversations that cited a specific article. Returns up to 25 per call with paging.

### get_conversation

Fetches a full transcript: every question, every answer, which articles were cited, and where the AI could not answer from the docs.

## Analytics

### get_insights

Returns a 30-day summary in one call: docs reads split between AI agents and humans, question and conversation counts, the answered rate, token spend on your OpenAI key, the most cited articles, and recent questions the AI could not answer.

The same numbers, with charts, live in the dashboard under Insights. See [Insights: metrics and conversations](/articles/insights).

```
What are my docs missing? Check the unanswered questions from the last month and draft articles to cover the top three gaps.
```

That single prompt is the whole insights workflow. The agent calls `get_insights`, reads the failed questions, and gets to work.

## Hosting

### set_docs_base_url

Moves your docs' canonical address under a domain you own with a single path segment, like `https://yoursite.com/docs`. The response includes the exact reverse-proxy configuration for Vercel, nginx, or Cloudflare Workers, plus a verification command, because you still need to route the path to Clayo on your side. The full walkthrough is [Host docs at yoursite.com/docs](/articles/subpath-hosting).

### remove_docs_base_url

Removes the base URL. Your docs' canonical address returns to your clayo.site subdomain (or your custom domain, if one is active).

:::callout{type="info"}
Hosting and widget tools are limited to project owners and admins, since they change what visitors see and where your docs live. Roles are covered in [Roles and permissions](/articles/roles-and-permissions).
:::

## Widget

### set_widget_questions

Sets the one to three starter questions shown as tappable chips when a visitor opens the widget's Ask tab. Each can be up to 120 characters. Good starter questions mirror what new users actually ask.

### clear_widget_questions

Clears custom questions. The widget falls back to suggesting your first published article titles automatically.

```
Look at the most common visitor questions this month and set them as the widget starter questions.
```

Widget behavior and settings are covered in [Configure the widget](/articles/configure-the-widget).