> ## Documentation Index
> Fetch the complete documentation index at: https://learn.mintlify.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Write content agents can use
> The specific writing and structural habits that make your content reliable context for agents.
export const Quiz = ({question, answers, correctFeedback, incorrectFeedback}) => {
const [selected, setSelected] = React.useState(null);
const [checked, setChecked] = React.useState(false);
const quizId = React.useId();
const isCorrect = checked && answers[selected]?.correct;
const reset = () => {
setSelected(null);
setChecked(false);
};
return
;
};
Building on the principles from the previous lesson about how agents read your content, this lesson introduces specific writing and structural habits that make your content agent-friendly.
## Make every page self-contained
Write every page as if the reader has never seen any other page on your site.
That means:
* Define terms and acronyms the first time they appear on each page
* Include prerequisites and information about who can access features
* Document all the steps required to complete a task
* Don't write "as mentioned in the overview" or "once you've completed the previous step" without making it clear what that refers to
* If a page depends on something being set up first, say so explicitly at the top: "This guide assumes you've already authenticated. If you haven't, see [Authentication](/path/to/authentication)."
Each page is a document instead of a chapter.
## Write specific titles and descriptions
Every page must have a title and a description. These are the primary signal an agent uses to decide whether a page is relevant to a user's question.
**Titles** should be specific enough that their content is unambiguous:
| Vague title | Specific title |
| ---------------------- | --------------------------------------- |
| Advanced configuration | Configure rate limits for API requests |
| Authentication | Authenticate API requests with API keys |
| Troubleshooting | Fix common webhook delivery failures |
**Descriptions** should answer "why would someone read this page?" in one concrete sentence. What task it serves and what specific topics it covers.
A weak description:
> "Learn about our authentication system and how to use it in your application."
A strong description:
> "Authenticate API requests using API keys. Covers generating keys, passing them in request headers, and handling 401 errors."
The second version tells an assistant exactly what the page contains. When a user asks, "Why is my API call returning a 401?", the assistant routes them to the right page because the description mentions 401 errors explicitly.
A useful test: if you covered the title and showed only the description to someone unfamiliar with your product, could they tell what the page is about?
## Use headings that stand alone
Headings serve as navigation aids for both humans and agents. A heading like "Part three" or "More options" tells an agent nothing about what's in the section. A heading like "Set a retry policy for failed requests" is specific enough to match against a user's question.
Apply the same principle as titles: specific enough to stand alone.
## Keep pages focused on one thing
A page that covers installation, configuration, and troubleshooting in one place asks an agent to extract a specific answer from a mixed-topic document. Sometimes it succeeds. Often it doesn't.
If users frequently need multiple topics together, link between them rather than combining them. The navigation overhead is lower than the cost of imprecise agent responses.
If your site has many mixed-topic pages, start revising your highest-traffic pages and the ones most often surfaced in support tickets. You can improve your content over time, starting with the pages that are most important to your users.
## Use consistent terminology
Pick one name for each concept and use it everywhere. This is especially important for:
* Product features and UI elements
* Role names and permissions
* Core concepts your users must understand to succeed with your product
If you've used multiple terms for the same thing in the past, add a terminology section to your `CLAUDE.md` or Cursor rules file so coding agents that help maintain your content apply the right terms:
```markdown theme={null}
## Terminology
- Use "workspace" not "organization" or "team"—these are the same thing; workspace is correct
- Use "API key" not "token" or "secret" when referring to authentication credentials
- Use "publish" not "deploy" or "push" when describing sending changes live
```
This shapes every AI-assisted edit and prevents terminology drift as your content grows.
## Write complete examples
When you include a code example, make it runnable. Agents surface examples to answer user questions, and coding agents like Claude Code or Cursor use them to generate code. An example with unexplained placeholder values, or that's missing an import or initialization step, might produce errors when users try to use it.
A complete example:
* Can be run as-is, or includes clear placeholders that explain what to substitute
* Includes all necessary imports and initialization
* Shows the expected output or result where it isn't obvious
If a full working example would be very long, break it up and make each section self-contained.
## Avoid implicit references
Phrases like "the above," "as mentioned," "this value," and "it" create ambiguity that humans resolve through context but AI assistants often can't. Be explicit:
| Implicit reference | Explicit reference |
| ------------------------------------ | ------------------------------------------------------------ |
| Pass this value to the next function | Pass the `session_token` returned above to `createSession()` |
| As mentioned in the previous section | As explained in [Authentication](/...) |
| It will return an error | The API returns a `401 Unauthorized` error |
This precision also makes content easier for humans to read. They don't have to hold information in their memory across pages to understand a sentence.
You've learned how to write content agents can use.
Next up: [Control what agents see](/courses/agent-friendly-content/control-what-agents-see) — Configure what agents have access to, and give them the context they need.