# Optimizing Knowledge Base Articles for AI Agents

{% hint style="info" %}
**You rarely need to rebuild your knowledge base or even edit your existing articles**. Most standard knowledge articles are already structured in a way that allows AI agents to efficiently navigate and extract information. These best practices are best applied when creating new content or when optimizing a specific article the AI is struggling to interpret.
{% endhint %}

When an AI agent searches your provided knowledge base to answer a user's question, it doesn't read an entire article at once. Instead, our system breaks articles down into smaller "documents" based on the headings, preserving the heading hierarchy so the AI knows where the chunk came from.

To ensure the AI retrieves the right information and understands it correctly, follow these best practices when creating or updating knowledge articles.

#### 1. Write descriptive, action-oriented headings

Because EbbotGPT uses headings to create chunks of information, your headings are the most critical part of your article.

* **Be explicit**: Avoid generic headings like "Overview" or "Next Steps." Instead, use "Overview of the Onboarding Process" or "Next Steps for Password Reset."
* **Use questions or tasks**: Headings formatted as the questions users ask (e.g., "How do I request a software license?") or the tasks they want to accomplish (e.g., "Troubleshooting VPN Connection Errors") are highly effective.
* **Maintain strict hierarchy**: Ensure your H1s, H2s, and H3s follow a logical nesting order. Do not skip heading levels for visual styling. The AI relies on this hierarchy to understand the relationship between different sections.

#### 2. Make every section self-contained

When a section under a heading is pulled out as a "document," it needs to make sense on its own.

* **Minimize pronouns across sections**: If your H2 is "Setting up the Router," do not start the paragraph underneath with "Plug it in." Explicitly state "Plug the router in."
* **Re-establish context**: If a section outlines step 3 of a process, briefly remind the AI what the process is. For example, instead of just "Step 3: Click Approve," write "Step 3 of the expense approval process: Click Approve."

#### 3. Prioritize clarity and directness

AI models parse straightforward, logical sentences much better than complex, winding narratives.

* **Use Active Voice**: "The system automatically deletes temporary files" is better than "Temporary files are automatically deleted by the system."
* **Be concise**: Remove fluff, filler words, and unnecessary conversational text.
* **Standardize terminology**: Use consistent naming conventions. If an application is called "HR Portal," do not interchangeably call it the "HR App," "Employee Site," or "the system" within the same article.

#### 4. Format for machine readability

Visual structure helps the AI break down complex relationships and steps.

* **Use bulleted and numbered lists**: If you are listing three or more items, or outlining a sequential process, use lists. AI agents are excellent at extracting steps from numbered lists to feed back to the user.
* **Leverage tables for structured data**: If you are comparing features, listing error codes and their solutions, or detailing configuration parameters, use a standard markdown/HTML table. Tables clearly define the relationship between a concept and its attributes.
* **Bold key terms**: Bolding important names, buttons to click, or specific error codes can help the system weigh the importance of those terms.

#### 5. Utilize a "Q\&A" or "Problem/Solution" Format

If an article is meant to solve an issue, format the text in a way that mirrors how a user would ask the AI.

* **Problem**: \[Clearly state the user's issue or error message]
* **Cause**: \[Briefly explain why it happens]
* **Solution**: \[Provide the step-by-step fix]


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ebbot.ai/ebbot-docs/core-capabilities/ebbotgpt/ebbotgpt-best-practices/optimizing-knowledge-base-articles-for-ai-agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.