# Add images and captions

To add a screenshot or diagram to an article, point your agent at the file:

```
Add ~/Desktop/settings.png to the branding article,
under the "Accent color" heading, with a caption explaining the picker.
```

The agent uploads the image to Clayo and embeds it in the article in one step. There is no media library to manage and nothing to host yourself; images are served from Clayo's CDN.

## How uploads work

When your agent adds an image, it requests a one-time upload link from Clayo, uploads the file, and writes the resulting image URL into the article's markdown. The link expires after five minutes, which the agent handles transparently. You keep working in plain language.

## Formats and limits

- **Formats**: PNG, JPEG, GIF, and WebP
- **Size**: up to 10 MB per image
- **SVG is not supported** for article images. Export SVGs as PNG first; your agent can usually do this for you.

## Captions

How an image renders depends on where it sits:

- An image on its own line gets figure treatment: displayed as a centered block, with room for a caption.
- An image inside a sentence renders inline.

To add a visible caption, use markdown's title syntax. The quoted text after the URL becomes the caption under the image:

```text
![Metrics overview](https://cdn.example.com/metrics.png "The Metrics tab reports a rolling 30 day window.")
```

For inline images, the title shows as a hover tooltip instead of a caption.

![An article figure with a visible caption beneath the image](https://d1fz24v557o32j.cloudfront.net/project-images/0319adcc-8d8c-4b62-8847-5f6ca52a92ff/cc4437fd-d398-46d9-b344-6ca197530f0c.png)

## Write real alt text

The text in the square brackets is the image's alt text. It is what screen readers announce and what appears if the image fails to load, so describe what the image shows rather than repeating the caption:

```text
![Widget settings page with three starter question fields](https://cdn.example.com/widget.png)
```

If you tell your agent what the screenshot depicts, it will write sensible alt text for you.

## Updating images

To replace an image, ask the agent to swap in a new file; it uploads the new image and updates the markdown. Old image URLs keep working, so previously published versions and cached pages do not break.

For the underlying upload tool, see [Content tools](/articles/mcp-content-tools).