Background

Freestyle is the cloud to run AI Code. The tools we're building are weird, and without a lot of explanation they can be hard to understand.

We try to regularly have coffee, and hack days with our customers. Over the course of hack days a few weeks ago, we noticed the way we were being used had changed. Our users didn't want to read our docs, they wanted to ask AI questions about them — and AI was giving them the wrong answers. We went through a pivot 11 months ago, and half the time it was still responding about our old product. Sometimes it hallucinated APIs we didn't have, and we even once heard of it giving a code snippets referencing how to use one of our competitors!

How we revamped our Docs for AI

We decided to add a series of functionalities to our docs to make them more accessible to AI, and therefore our users. They are as follows:

LLMs.txt

We started with an llms.txt and llms-full.txt that we generated from our content. However, we did it badly.

Our first generation of the llms.txt files used relative urls. This meant that users who copy and pasted the file into their own agents couldn't get anything. Further, a lot of AI docs scrapers are bad, and just didn't handle relative urls at all.

Once we fixed that, we still originally linked directly to docs pages. This made AI clients reading the pages read the full html/css/js of the page and not just the text. The worst side effect of this is that we have lots of tab views in our docs that default to JavaScript, when AI Scrapers would read these pages they wouldn't get any Python documentation for our Python users. So we re-exported all of our docs files with a .md extension — any page on this website can be gone to with .md at the end of the URL and it will return the raw markdown content of the page, here's this page as markdown.

AI Buttons

AFAIK Mintlify pioneered the copy button at the top of docs pages. For our first iteration we copied it from them.

The copy button lets users get the content of the page in a raw text format for the purpose of copying it into their AI's context. A lot of these vibe coders are copying it directly into ChatGPT or Claude, we can do that for them by linking into them.

To link into ChatGPT, we create a link like https://chatgpt.com/?q=yourprompt. This will open a new chat with the content of the page in it. You can also add hints=search to tell it to search the web — this helps it pull in more context around the docs.
To link into Claude, we create a link like https://claude.ai/new?q=yourprompt. This will open a new chat with the content of the page in it.
To link to Perplexity, we create a link like https://www.perplexity.ai?q=yourprompt. This will open a new search with the content of the page in it.
To link to T3 Chat, we create a link like https://t3.chat/new?q=yourprompt. This will open a new chat with the content of the page in it.

We decided not to link to Perplexity or T3 Chat because it caused too much noise. We wanted to figure out how to link to Gemini but we couldn't find a link format for it.

Note, you don't want to send the exact same content to each of these. Claude has the ability to fetch the raw MD content directly, whereas ChatGPT has web search only, and T3 Chat has nothing by default.

Talking Directly to Agents

We made our docs accessible via MCP.

This let our vibe coder users add our documentation directly to their workflows. However, at launch this didn't work at all.

Our MCP has two tools:

listDocs: This lists all of the docs we have available.
getDocById: This gets a specific doc by its ID.

When we launched them, their descriptions looked like:

listDocs: "List the available Freestyle documentation"
getDocById: "Get a specific documentation page by its id"

This lead to the AI never using these tools — Cursor/AI Agents had access to our documentation, but they never read them.

In version 2 of our MCP, we changed the descriptions to:

listDocs: "This tool lists all available Freestyle documentation pages. Whenever you're using Freestyle and you aren't sure how to do something, you should use this tool to check if there is documentation for it."
getDocById: "This tool gets a specific Freestyle documentation page by its id. You should use this tool whenever you are working with something in Freestyle to be sure you always have up to date information on how to use it."

By making our descriptions more actionable and telling the AI when to use them, we saw a huge uptick in their usage, and in our users' ability to debug with agentic systems — now when something isn't working and Freestyle shows up in the logs, AI proactively reads our documentation to see if we have already explained how this issue could've happened.

We also have been able to make this incredibly accessible to our users, by offering deep links into Cursor and VSCode to auto-install it.

This link installs our MCP in Cursor: You can create one like it by following the Cursor Deeplink Docs
This link installs our MCP in VSCode: You can create one like it by following the VSCode Deeplink Docs

We added these links at the top of our Copy Page button dropdown, because we believe our users are more likely to want to chat in Cursor or VSCode than anywhere else.

AI Chat

However, some of our users might want to chat in the docs directly. We added AI Chat to our docs without any expensive vendors in a day. Our AI Chat is based on the work of Stack Auth.

We use gemini-2.5-flash, and we connected it to our MCP so it has access to our docs. We instructed it to always read the relevant docs and reference them in it answers, and we built a simple UI to display the tool calls it makes so users who want more details can refer to the original docs page.

What we're working on next

We're working on a DevOps MCP that will allow AI Agents to query logs for a specific user's Freestyle project, allowing it to get a better understanding of whats going on and how to help them. For example when a deploy fails, the AI can pull the logs for that deployment along with the docs to help the user debug it.
We are adding a askQuestion tool to our MCP that allows AI agents to ask questions and give more context, such as what language they're working with, what other technologies are involved, and in general what they're trying to do. We'll use this to run a semantic search and find the most relevant docs for them.
We're working on an escalateIssue tool that will allow AI Agents to report issues directly to us, so we can know they are happening faster and fix them.
We're working on upgrades to our in docs chatbot, including more UI Components accessible to it for it to suggest joining our discord, going to our dashboard, or other actions that might help the user.
We're working on more guides, we've found that step by step examples work really well for showing AI how Freestyle fits into context.
We're on the lookout for more deep link schemes that would allow one click installation of our MCP into tools like Windsurf, Claude Desktop, Devin, and others.
We (want) to have generated SDK documentation beyond our OpenAPI generated docs. We have tried to do this repeatedly and have failed.

We Revamped our Docs for AI Driven Development