# Tools · Parcels

> MCP tools for the Parcels module (coworking): registering letters and packages with a photo, the queue, pickup, return, discard, reopening, deletion and the member's "do I have a parcel?".

The [Parcels](/espacos/encomendas) module through the assistant: registering the parcel with a photo and notifying the member, following the queue, handling photos, marking the pickup, returning, discarding, reopening and deleting, and the member asking whether anything is waiting. There are **16 tools**.

Each tool carries a badge: <span class="tool-kind tool-kind-read">Read-only</span> changes nothing, <span class="tool-kind tool-kind-write">Changes</span> creates or changes something right away, and <span class="tool-kind tool-kind-confirm">Asks to confirm</span> only acts after your yes to a summary. See [Money and confirmation](/mcp/dinheiro-e-confirmacao).

## In short

| Tool | What it does | Minimum role | Type |
|---|---|---|---|
| [`get_parcels_overview`](#get-parcels-overview) | The space at a glance: the settings and how many are waiting | Anyone who sees the space | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`get_parcel`](#get-parcel) | One parcel, with the photos | Any (yours); team (any) | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`do_i_have_parcels`](#do-i-have-parcels) | Your parcels, pending and history, with the place and the code | Any | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`mark_parcel_picked_up`](#mark-parcel-picked-up) | Marks the pickup | Any (yours); moderator or finance (others') | <span class="tool-kind tool-kind-write">Changes</span> |
| [`search_parcel_recipients`](#search-parcel-recipients) | Finds the recipient by name | Moderator or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`register_parcel`](#register-parcel) | Registers the parcel and notifies the recipient by email | Moderator or finance | <span class="tool-kind tool-kind-write">Changes</span> |
| [`list_pending_parcels`](#list-pending-parcels) | The queue of parcels waiting for pickup | Moderator or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_parcels`](#list-parcels) | The history, with any status | Moderator or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`update_parcel`](#update-parcel) | Fixes the data and the locker code | Moderator or finance (waiting); admin (closed) | <span class="tool-kind tool-kind-write">Changes</span> |
| [`add_parcel_photo`](#add-parcel-photo) | Adds a photo | Moderator or finance | <span class="tool-kind tool-kind-write">Changes</span> |
| [`replace_parcel_photo`](#replace-parcel-photo) | Replaces a photo | Moderator or finance | <span class="tool-kind tool-kind-write">Changes</span> |
| [`return_parcel`](#return-parcel) | Returns to the sender | Moderator or finance | <span class="tool-kind tool-kind-write">Changes</span> |
| [`remove_parcel_photo`](#remove-parcel-photo) | Removes a photo for good | Moderator or finance | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`discard_parcel`](#discard-parcel) | Discards a parcel nobody picked up | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`reopen_parcel`](#reopen-parcel) | Undoes a closing | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`delete_parcel`](#delete-parcel) | Deletes a record made by mistake | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |

The space is created with [`create_space`](/mcp/ferramentas-comunidade#create-space) and `module: "parcels"`, with the `parcels` argument for the settings; [`update_space`](/mcp/ferramentas-comunidade#update-space) changes only what you send and keeps the rest.

The team, here, is the owner, the admin, the moderator and finance. The roles are the routes' roles: the assistant never does more than the connected person could do on screen. The owner and the admin see all 16 tools; the moderator and finance, 13 (no discarding, reopening or deleting); the member, 4 (`get_parcels_overview`, `get_parcel`, `do_i_have_parcels` and `mark_parcel_picked_up`, on their own parcels).

**The locker code is a secret.** No team response carries it, and it is hidden in the MCP audit log; only `do_i_have_parcels` and `get_parcel` show it, to the recipient themselves. Whoever registers or fixes a parcel can **set** the code, never read it, and the assistant doesn't repeat it.

## The space settings

The `parcels` argument of `create_space` and `update_space` accepts:

| Field | Type | Description |
|---|---|---|
| `locker_mode` | `none` or `free` | `none`: everything stays at the front desk; `free`: the team writes where it left each parcel |
| `locker_pickup_code` | true or false | The team can set a pickup code per parcel; only the recipient sees it |
| `email_includes_photo` | true or false | The notice email carries a thumbnail of the photo (default: yes) |
| `require_staff_confirmation` | true or false | True: only the team marks the pickup. False (default): the member can too |
| `reminder_after_days`, `reminder_max_count` | numbers, or `null` | Stalled deadline and reminder cap. They are already accepted, but the reminder doesn't run yet |

## `get_parcels_overview`

<span class="tool-kind tool-kind-read">Read-only</span>

**The space at a glance.** The settings (locker mode and whether the member confirms their own pickup), how many parcels are waiting for **you** (`mine.pendingCount`) and, for the team, how many are pending and stalled. *Minimum role: anyone who sees the space.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | Yes | The Parcels space |

**Ask like this:** *"How many parcels are stalled at the Downtown location?"*

## `get_parcel`

<span class="tool-kind tool-kind-read">Read-only</span>

**One parcel.** With the photos, in signed links valid for 1 hour. The team reads any parcel in the community, without the code; the recipient reads theirs, with the place and the code while it's waiting. Anyone else gets "not found". *Minimum role: any.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `parcel_id` | id | Yes | The parcel (from `list_pending_parcels`) |

**Ask like this:** *"Show me Maria's parcel."*

## `do_i_have_parcels`

<span class="tool-kind tool-kind-read">Read-only</span>

**"Do I have a parcel?"** Only **yours**: the pending ones (all) and the history (the latest), with where to pick up, the locker code while it's waiting and the photos (1-hour links). Show the code only to the person themselves. *Minimum role: any.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | No | A specific space; without it, all |
| `history_limit` | number | No | How many from the history (1 to 100) |

**Ask like this:** *"Do I have any parcel waiting?"*

## `mark_parcel_picked_up`

<span class="tool-kind tool-kind-write">Changes</span>

**Mark the pickup.** The team marks it as `STAFF` (default, with the name of who came in `picked_up_by_name`, which defaults to the recipient) or `THIRD_PARTY` (the name is required). The recipient themselves marks it as `SELF`, only if the space doesn't require team confirmation (otherwise, refused). The locker code is deleted. It's **idempotent**: on an already closed parcel, it returns `already_closed: true`. *Minimum role: any (yours); moderator or finance (others').*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `parcel_id` | id | Yes | The parcel (from `list_pending_parcels`) |
| `method` | `STAFF`, `SELF` or `THIRD_PARTY` | No | How it was picked up |
| `picked_up_by_name` | text | No | Who came to collect it (required with `THIRD_PARTY`) |

**Ask like this:** *"Mark Maria's parcel as picked up."* · *"I already picked up my parcel."*

## `search_parcel_recipients`

<span class="tool-kind tool-kind-read">Read-only</span>

**Who receives it.** The space's members whose name starts with `q` (at least 3 letters, up to 8 results), with only id, name and initials. The `id` is the `recipient_profile_id` for `register_parcel`. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | Yes | The Parcels space |
| `q` | text | Yes | The start of the name |

**Ask like this:** *"Find Maria Souza so I can register a parcel."*

## `register_parcel`

<span class="tool-kind tool-kind-write">Changes</span>

**Register the parcel.** For a member with access to the space. It **sends the recipient the notice email** (with the thumbnail, if the space is set that way), in the community's time zone: the assistant says so. `kind` is `LETTER`, `PACKAGE` or `OTHER` (the latter requires `kind_label`). `locker_label` and `locker_pickup_code` (4 to 12 characters, a secret) only apply if the space allows it. `client_request_id` makes a repeated call return the same parcel, with no second email. The same recipient, kind and tracking within 24 hours is refused (409), unless `force` is true. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | Yes | The Parcels space |
| `recipient_profile_id` | id | Yes | From `search_parcel_recipients` |
| `kind` | `LETTER`, `PACKAGE` or `OTHER` | Yes | The kind |
| `kind_label` | text | With `OTHER` | Up to 60 characters |
| `sender_name`, `carrier`, `tracking_code` | text | No | Sender, carrier and tracking |
| `notes` | text | No | Up to 200 characters |
| `locker_label`, `locker_pickup_code` | text | No | Where it was left and the code |
| `photos` | list | No | Up to 5, each with `image_url` or `image_base64` |
| `client_request_id`, `force` | text, true/false | No | Idempotency and duplicate registration |

**Ask like this:** *"An Amazon package arrived for Maria Souza, in locker 12. Photo: [link]."*

## `list_pending_parcels`

<span class="tool-kind tool-kind-read">Read-only</span>

**The queue.** The parcels waiting for pickup, newest to oldest, with recipient, kind, sender, place, how long they've waited and `stalled_days` when past the deadline. Filters: `kind`, `q` (recipient, sender, carrier or tracking), `stalled`, `recipient_profile_id`, `from` and `to` (YYYY-MM-DD, in the community's time zone). Never the code (only `has_locker_code`). *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | Yes | The Parcels space |
| `kind`, `q`, `stalled`, `recipient_profile_id`, `from`, `to` | various | No | The filters |
| `page`, `limit` | numbers | No | Pagination (up to 100) |

**Ask like this:** *"What has been stalled at the front desk for more than 3 days?"*

## `list_parcels`

<span class="tool-kind tool-kind-read">Read-only</span>

**The history.** Same as `list_pending_parcels`, but with any status (`RECEIVED`, `PICKED_UP`, `RETURNED`, `DISCARDED`), filterable by `status`. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | Yes | The Parcels space |
| `status` | status | No | Filters by status |
| the filters of `list_pending_parcels` | various | No | |

**Ask like this:** *"Which parcels were returned this month?"*

## `update_parcel`

<span class="tool-kind tool-kind-write">Changes</span>

**Fix.** Kind, sender, carrier, tracking, note, place and locker code (which is set again, never read) of a parcel that's waiting. A closed parcel can only be corrected by an owner or admin, and never the code. Each fix goes in the log. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `parcel_id` | id | Yes | The parcel (from `list_pending_parcels`) |
| `kind`, `kind_label`, `sender_name`, `carrier`, `tracking_code`, `notes`, `locker_label`, `locker_pickup_code` | various | No | Only what changes |

**Ask like this:** *"Fix the tracking on Maria's parcel to BR123456789."*

## `add_parcel_photo`

<span class="tool-kind tool-kind-write">Changes</span>

**Add a photo.** Up to 5 per parcel, in private storage. The team; on a closed parcel, only the owner and the admin. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `parcel_id` | id | Yes | The parcel (from `list_pending_parcels`) |
| `image_url` or `image_base64` (+ `image_type`) | text | Yes | The photo: a public link or the file in base64. It's kept in private storage |

**Ask like this:** *"Attach this photo to Maria's parcel."*

## `replace_parcel_photo`

<span class="tool-kind tool-kind-write">Changes</span>

**Replace a photo.** Replaces a photo with the new file; the old one is deleted. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `parcel_id` | id | Yes | The parcel (from `list_pending_parcels`) |
| `photo_id` | id | Yes | The photo (from `get_parcel`) |
| `image_url` or `image_base64` (+ `image_type`) | text | Yes | The photo: a public link or the file in base64. It's kept in private storage |

**Ask like this:** *"Replace the parcel's first photo with this one."*

## `return_parcel`

<span class="tool-kind tool-kind-write">Changes</span>

**Return to the sender.** Requires the reason. Nothing is deleted: the parcel stays in the history as `RETURNED` and the locker code is deleted. An already closed parcel answers 409. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `parcel_id` | id | Yes | The parcel (from `list_pending_parcels`) |
| `reason` | text | Yes | The reason, up to 200 characters; it goes in the log |

**Ask like this:** *"Return Maria's parcel to the sender: refused."*

## `remove_parcel_photo`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Remove a photo.** The file is deleted for good. On the first call it returns the summary and the confirmation code. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `parcel_id` | id | Yes | The parcel (from `list_pending_parcels`) |
| `photo_id` | id | Yes | The photo (from `get_parcel`) |

**Ask like this:** *"Remove the parcel's second photo; it shows the address."*

## `discard_parcel`

<span class="tool-kind tool-kind-write">Changes</span>

**Discard.** For a parcel nobody picked up. Requires the reason. Nothing is deleted: it stays as `DISCARDED` in the history, and `reopen_parcel` undoes it. It doesn't ask for confirmation, since it's reversible. *Minimum role: admin (owner or admin).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `parcel_id` | id | Yes | The parcel (from `list_pending_parcels`) |
| `reason` | text | Yes | The reason, up to 200 characters; it goes in the log |

**Ask like this:** *"Discard Maria's parcel: expired without pickup."*

## `reopen_parcel`

<span class="tool-kind tool-kind-write">Changes</span>

**Reopen.** Undoes a pickup, return or discard made by mistake: it goes back to `RECEIVED`, with the reason. The deleted code doesn't come back; set another with `update_parcel`. *Minimum role: admin (owner or admin).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `parcel_id` | id | Yes | The parcel (from `list_pending_parcels`) |
| `reason` | text | Yes | The reason, up to 200 characters; it goes in the log |

**Ask like this:** *"Reopen Maria's parcel: the pickup was marked by mistake."*

## `delete_parcel`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Delete a record made by mistake.** It leaves the lists and the photos are deleted; the log keeps who and why. To close a parcel for real, use `mark_parcel_picked_up`, `return_parcel` or `discard_parcel`. On the first call it returns the summary and the confirmation code. *Minimum role: admin (owner or admin).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `parcel_id` | id | Yes | The parcel (from `list_pending_parcels`) |
| `reason` | text | Yes | The reason, up to 200 characters; it goes in the log |

**Ask like this:** *"Delete the record of John's parcel: I registered it for the wrong person."*

## Related

- [Parcels](/espacos/encomendas)
- [Tools](/mcp/ferramentas)
- [Money and confirmation](/mcp/dinheiro-e-confirmacao)
- [Recipes](/mcp/receitas)