# Point, don't describe

> Use Agentation to click an element in your running app, write a two-line critique, and hand your agent the exact selector and file, by paste or straight over MCP.

Module: Directing your agent · Level: beginner · 7 min · https://school.agents.org.in/foundations/agents/point-with-agentation

"The button in the top right, no, the other one, the grey one next to the title." You have typed a sentence like this. The agent edited the wrong button.

Now watch the same feedback given by pointing.

*[Interactive demo: Click the element, write two lines, and the fix session gets the selector, the file and your words.]*

## What just happened

The toolbar in the corner is Agentation (Benji Taylor's development toolbar: click any element in your running app, write a short note, and it hands an agent the element's selector, file and your words), by Benji Taylor. It runs inside your app while you develop it. You click an element, type a short critique, and it turns that into structured notes an agent can read: the element's selector (The address of an element on a page, like button.export-btn. It tells code (or an agent) exactly which element you mean), the file it lives in, its computed styles and your words.

Pointing beats describing. The agent no longer guesses which button. It is handed the button.

> **In plain words.** Your app runs on your own computer while you build it, at an address like `localhost:3000`. That's the **dev server**. Agentation only appears there, never on the real site.

## Set it up once

  **Step: Install the package.** Add it as a development-only dependency.

  **Step: Mount it in development only.** Render it in your root layout behind a development check, so it never ships.

  **Step: Optional: connect your agent.** Add Agentation's MCP server so the agent reads notes directly instead of you pasting them.

```bash
npm install --save-dev agentation
```

**Mount it, development only (paste into your agent):**

```text
Install agentation as a dev dependency and mount its toolbar in the root layout,
after the page content, only when process.env.NODE_ENV === "development".
Keep the layout a server component. Don't add a second mount if one exists.
```

Not on Next.js? Benji ships an `agentation` skill that knows how to mount it in Vite, Remix, Astro and the Pages Router. Ask your agent to "set up Agentation" with that skill installed.

## Two ways to hand the notes over

**Paste.** Click Annotate, click the element, write your note, submit. Agentation gives you markdown: selector, file path, styles, critique. Copy it into your agent. No server needed.

**Over MCP.** Here a little vocabulary helps. Theo Browne describes an agent as a model plus a harness (The hidden layer of ordinary code around a model: it lists the tools, notices when the model asks for one, runs it and sends the result back. Model + harness = agent): the hidden layer that hands the model its tools and runs them. An MCP (Model Context Protocol: a standard way for an agent to use tools that live somewhere else, by sending a request to a server, like this course's exam server) server is a tool that lives somewhere else, reached by an address. Agentation's server is one such tool. Connect it, and your agent can read new annotations the moment you add them.

```bash
claude mcp add agentation -- npx -y agentation-mcp server
```

*(A green "healthy" check isn't proof. Add one test note and make sure the agent reads that exact note.)*

## The two-session loop

With MCP connected, you can split the work across two agent sessions, each with one job.

| Session 1: critique | Session 2: fix |
|---|---|
| opens your app in a visible browser | watches for new annotations |
| adds 5–8 annotations per page | reads each selector, file and note |
| names the principle in each | makes the smallest fix it can defend |
| | moves to the next one |

The annotation is the contract between them: the same selector and note a person would have written. Session 1 can be you, clicking around, or an agent driving the browser on its own. Either way, you review the resulting commits, not every single note.

The skill's own verb for session 2 is short:

```bash
/design-engineering agentation
```

It pulls the annotations, fixes them one at a time with minimal diffs you could defend as review rows, and commits only if you ask.

## Write notes the agent can act on

Agentation's own guidance for a good note, paraphrased:

- **Two or three sentences.** Longer reads as an essay; shorter is too vague.
- **Specific and actionable.** Not "this section needs work". Instead: "Use a three-column card grid with icons."
- **Name the principle.** Hierarchy, grouping, whitespace. Those words are how the agent finds the right pattern.
- **Point at a product that does it right.** "Like Linear's command bar."

  **Vague note (avoid):**

This button looks weird.

  **Actionable note (do this):**

Main action, but it reads as secondary: grey fill, 11px. Use the primary fill and 14px, like Linear's primary button. Hierarchy.

**Turn notes into fixes (paste into your agent):**

```text
Read my pending Agentation annotations.
For each one: open the file it names, make the smallest change that answers the note, and give me a Before | After | Why row.
One annotation at a time. Don't commit until I say so.
```

## Where it doesn't fit

- **Production.** It is a development tool; it should never ship.
- **A one-off marketing page.** Pointing by screenshot is faster than setting up the toolbar.
- **No running app.** It needs something on `localhost` to click.

> **Selectors go stale.** An annotation on `.card > div:nth-child(3)` points somewhere else once someone reorders the divs. Prefer stable hooks like `data-testid`, and clear old annotations instead of letting them pile up. Also read Agentation's licence (PolyForm Shield) before using it inside a product that competes with it.

**Check yourself:** Why does an Agentation note fix the right element when a typed description often doesn't?

- [ ] It uses a stronger model
- [x] It hands the agent the element's selector and file instead of a description to interpret
- [ ] It edits the code itself, without an agent
- [ ] It only works on buttons

*Why:* The note carries the exact selector, the file path and the computed styles, so the agent doesn't have to guess which element 'the grey one next to the title' means.

## In the skill

- https://school.agents.org.in/skill/meta/agentation-workflow.md