---
title: "Compose agent brief"
method: POST
path: "/api/agents/{sid}/compose-brief"
tags: ["agents"]
---

# Compose agent brief

`POST /api/agents/{sid}/compose-brief`

## Request

- Base URL: `https://beta.getsales.io/unibox/v1`
- URL: `https://beta.getsales.io/unibox/v1/api/agents/{sid}/compose-brief`
- Auth: HTTP bearer and API key in header `Team-SID`

Improve an AI SDR's Brief (by sid): the composer writes it again whole, each sentence under the section it answers, the filler gone, nothing invented, and applies what the person asked when said is given. Nothing is saved: show the change, then save through update_agent with brief.text. result.notes lists what it still needs. 503 composer_unavailable; 422 compose_invalid when nothing came back.

Contract:
- MCP tool `compose_agent_brief`, registry package `mcp.unibox/agents`, mount `unibox.agent`.
- Operation `action`, response envelope `action`.
- Flags: read only.

## Path parameters

- `sid` string, required: The agent whose Brief it is (ub_ag_…).

## Request body

- ComposeAgentBriefRequest: Request body of `compose_agent_brief`.
  - `said` string, nullable: What the person asked for, as they said it; left out, the Brief is only made clearer.
  - `current` string, nullable: The Brief as the editor holds it when it is not saved yet; left out, the stored Brief.

## Response `200`

`action` success envelope.

- ComposeAgentBriefResponse
  - `success` true, required
  - `operation` 'action', required
  - `action` string, required: kebab-case verb; matches the route segment.
  - `item` unknown, required
  - `result` object, required
    - `draft` object, required
      - `brief` string, required: The whole Brief in markdown, within 49152 chars: the five headings in order, a slot left where nothing answers it.
      - `notes` string[], required: What the composer still needs to know (the booking link, who runs demos, what never to promise), one short line each.
    - `cost_usd` number, nullable, required: What the composition cost on the model, a few thousandths of a dollar.
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
    - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.

## Other responses

- `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-unibox.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-unibox/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-unibox/revisions/8f1bc317897f?raw)