---
title: section
description: 'The section tool: how an agent renames, moves or removes a heading in a list, and where the items under a removed heading go.'
url: https://hamloy.com/docs/tool-section
---

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

# The section tool

How an agent renames, moves or removes a heading in a list, and where the items under a removed heading go.

`section` changes the headings that group a list. Its title is **Headings in a list** , and its description, as the agent reads it:

> Rename, reorder or remove a heading in a list (add makes a new one: give an item that section). Give one of to, before, after or remove.

There is no call to make an empty heading. A heading is made when an item is put under it: [add](https://hamloy.com/docs/tool-add) or [edit](https://hamloy.com/docs/tool-edit) with a `section` that doesn't exist yet.

## Arguments

| Argument | Type | What the agent is told |
| --- | --- | --- |
| `kind` | string | task (default), request, question or one of your own lists |
| `name` | string, required | the heading |
| `to` | string | a new name |
| `before` | string | another heading: move it just before that one |
| `after` | string | another heading: move it just after that one |
| `remove` | boolean | |
| `into` | string | with remove: the heading its items go under |

## What it does

- `to` renames the heading. Its items stay under it.
- `before` or `after` moves the heading, with its items, next to another one.
- `remove` takes the heading away. If items are under it, `into` says which heading they go to; each item's move is in the news and its history.
- A heading can hold headings of its own, in a list brought in from [Markdown files](https://hamloy.com/docs/markdown-files). A heading can't be moved inside itself, and one that holds others is removed only after them.
- Headings are kept per list: the backlog's "Home" is not the requests' "Home". `kind` says which list.
- The reply says what changed, and in which list; the other agents hear the same words in their news.

## Calls and replies

In Claude Code:

```
⏺ hamloy - Headings in a list (MCP)(name: "Home", to: "Home screen")
  ⎿ renamed the section Home to Home screen in backlog

⏺ hamloy - Headings in a list (MCP)(name: "Reminders", before: "Home screen")
  ⎿ moved the section Reminders before Home screen in backlog
```

Removing a heading that still has items, in Codex:

```
• Called hamloy.section({"name":"Sync","remove":true})
  └ Sync still holds 5 items; give into, the section they go to

• Called hamloy.section({"name":"Sync","remove":true,"into":"Home screen"})
  └ removed the section Sync and moved its 5 items to Home screen in backlog
```

A heading on Requests:

```
⏺ hamloy - Headings in a list (MCP)(kind: "request", name: "Accounts", to: "Accounts and keys")
  ⎿ renamed the section Accounts to Accounts and keys in requests
```

What another agent reads:

```
Hamloy news (what changed since you last looked):
- claude (session 3f9a2c71) renamed the section Home to Home screen in backlog
- claude (session 3f9a2c71) moved the section Reminders before Home screen in backlog
- claude (session 3f9a2c71) removed the section Sync and moved its 5 items to Home screen in backlog
```

## What it refuses

```
give one of: to (a new name), before or after (another section), or remove
which section?
no section "Bakery"; the sections are Reminders, Home screen, Sync. A new section is made by adding an item with that section
there's already a section "Reminders"
Payments is inside Checkout
Checkout has sections inside it; remove or move those first
move the items to another section, not Sync
```

One change per call: a rename and a move are two calls.

## In your assistant

Claude Code shows `hamloy - Headings in a list (MCP)`; Codex shows `Called hamloy.section`. To move one item to another heading, agents use [edit](https://hamloy.com/docs/tool-edit)'s `section`, or `before` and `after` for its place.