---
title: view
description: 'The view tool: how an agent makes, changes or removes a saved list, board or table on your board when you ask to see the lists a certain way.'
url: https://hamloy.com/docs/tool-view
---

[Docs](https://hamloy.com/docs)

# The view tool

How an agent makes, changes or removes a saved list, board or table on your board when you ask to see the lists a certain way.

`view` saves a way of looking at the lists, for the board. Its title is **Views of the lists** , and its description, as the agent reads it:

> Make, change or remove a saved view of a list on the page when the human asks to see the lists a certain way, and say what it shows; no arguments lists them. E.g. most urgent first: layout table, sort [-prio]; a board: layout board, group prio, order [high, medium, low]; blocked: filter [blocked=waiting]; everything for Sara: list all, filter [for=Sara]. Fields: the items' own or section, done, blocked, claimed, by, at, doneat, needs, list. Fix what the reply warns about.

You ask in words ("show me a board by priority"), and the agent makes the view. It appears on the board for everyone on the project. See [Views](https://hamloy.com/docs/views).

## Arguments

| Argument | Type | What the agent is told |
| --- | --- | --- |
| `key` | string | the view to change (V-…); leave out for a new one |
| `delete` | boolean | |
| `name` | string | |
| `list` | string | backlog (default), requests, questions, one of your own lists, or all: every list at once, each item with its list (a field to filter, group or sort by) |
| `layout` | string | list, board or table |
| `group` | string | field to group by; a board's columns |
| `order` | array | the groups in order |
| `sort` | array | fields to sort by; -prio is high to low |
| `filter` | array | all must hold: field=value, field!=value, field=a|b |
| `show` | array | fields shown on each item |
| `suggest` | string | only for a view nobody asked for: why it helps; the human keeps or dismisses it |

## What it does

- With no arguments it lists the saved views, and only reads.
- The reply describes the view and says what it shows right now: how many items pass, and a board's columns with their counts.
- A warning follows when the view would show nothing right now, or when a column names a value no item has and a near one exists. The description asks the agent to fix it.
- With `key`, only the arguments given change. Views have versions, as items do.
- `suggest` marks a view nobody asked for. It waits on the board until you keep or dismiss it.

## Calls and replies

In Claude Code:

```
⏺ hamloy - Views of the lists (MCP)(name: "Most urgent", layout: "table", sort: ["-prio"], show: ["prio","due"])
  ⎿ V-3ap6@1 Most urgent: table of backlog, sorted by -prio, showing prio, due
       shows: Table of backlog: 11 of 11 tasks; sorted by prio high to low (most important or newest first); showing prio, due

⏺ hamloy - Views of the lists (MCP)(name: "By priority", layout: "board", group: "prio", order: ["high","medium","low"])
  ⎿ V-6kzv@1 By priority: board of backlog, grouped by prio (high, medium, low)
       shows: Board of backlog: 11 of 11 tasks; columns by prio: high 1, medium 1, low 0, no prio 8, hihg 1
```

Everything for you, across every list, in Codex:

```
• Called hamloy.view({"name":"For me","list":"all","filter":["for=you"]})
  └ V-91k7@1 For me: list of every list (all), only for=you
      shows: List of every list (all): 1 of 15 items (only where for is you)
```

A view the agent suggests:

```
V-8pge@1 Most urgent: table of backlog, sorted by -prio (suggested by claude, waiting for the human to keep or dismiss it: see what's urgent first)
  shows: Table of backlog: 1 of 1 tasks; sorted by prio high to low (most important or newest first)
```

A view that shows nothing yet gets a warning:

```
V-jck1@1 Blocked: list of backlog, only blocked=waiting
  shows: List of backlog: 0 of 2 tasks (only where blocked is waiting)
  warning: it shows nothing right now: no task passes its filters
```

## What it refuses

```
no item has a "prioo" field; did you mean "prio"?; fields in use: due, for, prio; built in: status, section, done, blocked, claimed, by, at, doneat, needs, list. To use a new field, set it on the items first (the edit tool), then make the view
layout is list, board or table, not "kanban"
a new view needs a name
remove which view? give its key (V-…)
say why the view helps, e.g. suggest: "see what's urgent first"
view takes key, delete, name, list, layout, group, order, sort, filter, show, suggest, not for
```

A view is only a way of looking. It changes no item, and removing it removes no item:

```
• Called hamloy.view({"key":"V-3ap6","delete":true})
  └ removed V-3ap6
```

The rules ask agents to make a view only when you ask for one, or to suggest it. Claude Code shows `hamloy - Views of the lists (MCP)`; Codex shows `Called hamloy.view`.