# `announcement_create`

**Draft announcement.** Saves an announcement as a draft for a person to review and publish in PorchQ.

**Who can use it:** Owners and managers with a role in the community. A management company's owners and managers can't draft announcements through MCP yet.

| Scope | Effect | Hints |
|---|---|---|
| `community:write` | draft | changes data |

## Description shown to assistants

> Use this when an owner or manager asks to create or post an announcement. It saves a draft in PorchQ for a person to review and publish. Drafts are not visible to residents and send no notifications until someone publishes them in PorchQ.

## Arguments

| Argument | Type | Required | About |
|---|---|---|---|
| `property_id` | string | No | The community's public id (`prop_web…`). Pass it on every call. |
| `title` | string | Yes | The announcement's title. |
| `body` | string | Yes | The announcement's text. |
| `priority` | string | No | `low`, `normal`, `high` or `urgent`. |
| `idempotency_key` | string | No | Optional. A unique value for this change; sending the same value again does nothing twice. At most 200 characters. |

## What it returns

Every result has `content` (one short sentence for the person) and `structuredContent` (the data below). A tool that could not run answers with `isError: true` and a sentence saying why; see [Errors and limits](/developers/mcp/errors-and-limits).

- `status`: always `draft`, and `visible_to_residents`: always `false`.
- `review_url`: the community's Announcements page, where a person publishes it.
- `announcement`: the draft.

`structuredContent` follows this JSON Schema, also in `tools/list` as `outputSchema`:

```json
{
  "type": "object",
  "properties": {
    "property": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "addressLine1": { "type": ["string", "null"] },
        "addressLine2": { "type": ["string", "null"] },
        "city": { "type": ["string", "null"] },
        "state": { "type": ["string", "null"] },
        "postalCode": { "type": ["string", "null"] },
        "timezone": { "type": ["string", "null"] },
        "billingFrequency": { "type": ["string", "null"] },
        "demoClone": { "type": "boolean" },
        "demoPersona": { "type": ["string", "null"] },
        "demoExpiresAt": { "type": ["string", "null"] }
      },
      "required": ["id", "name"]
    },
    "status": { "const": "draft" },
    "visible_to_residents": { "const": false },
    "review_url": { "type": "string" },
    "announcement": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "title": { "type": "string" },
        "body": { "type": ["string", "null"] },
        "priority": { "type": ["string", "null"] },
        "published_at": { "type": ["string", "null"] },
        "expires_at": { "type": ["string", "null"] },
        "active": { "type": ["boolean", "null"] }
      },
      "required": ["id", "title"]
    }
  },
  "required": ["property", "status", "visible_to_residents", "review_url", "announcement"]
}
```

## Notes

- Nothing reaches residents from this tool. Publishing, and the notifications that come with it, is a step a person takes in PorchQ.
- `priority` is `low`, `normal`, `high` or `urgent`.

## Example

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "announcement_create",
    "arguments": {
      "property_id": "prop_web4k2m9q7x1v8c3n5b6z0a2s4d",
      "title": "Pool closed Friday",
      "body": "The pool will be closed on Friday for maintenance and reopens Saturday at 8 am.",
      "priority": "normal"
    }
  }
}
```