> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semicola.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Demand inbox & proposal pass

> The ledger of every brief your storefront answered, and the full record of each answer.

The **demand inbox** answers three questions for a seller: what demand came in, how did my agent
respond, and did we win? Every row is one buyer brief (an **RFP**) joined to the response your
storefront agent produced and the commercial result that followed. Open a row and you get the
**proposal pass**: the complete, unchangeable record of one response.

Open the inbox with "Show me recent buyer briefs" in the app, or call `open_demand_inbox`.

## The metrics strip

| Metric             | What it counts                                                    | Shown as unavailable when   |
| ------------------ | ----------------------------------------------------------------- | --------------------------- |
| **Briefs YTD**     | Briefs received this calendar year                                | Never; zero is a real count |
| **Answered**       | Share of those briefs that got a response                         | No briefs yet               |
| **Win rate**       | Won ÷ (won + lost), counting only briefs with a decided result    | Nothing decided yet         |
| **Avg grade**      | Mean of your A–F grades, rounded to a letter                      | Nothing graded yet          |
| **Agent vs human** | How many responses the agent led, and how many a person took over | No attribution recorded     |
| **Booked YTD**     | Money won this year, per currency                                 | Nothing won yet             |

Every figure comes from records that exist. A metric with no inputs reads as unavailable rather than
a made-up zero, and money in different currencies is listed side by side, never converted and
summed. Imported historical briefs are kept out of these numbers because they describe work done
before your agent existed.

## The ledger

Each row shows the brief, the buyer and advertiser, the kind of response, the result, your grade and
who led the response.

| Response kind           | Means                                                              |
| ----------------------- | ------------------------------------------------------------------ |
| **Proposal**            | The agent returned at least one proposal with an id.               |
| **Product offer**       | The agent returned products but no proposal.                       |
| **Passed**              | The agent deliberately declined, and said why.                     |
| **Needs clarification** | The agent asked the buyer questions instead of guessing.           |
| **Failed**              | The turn could not complete; the reason and retry advice are kept. |

The **result** follows the commercial outcome: a buy that is forwarded or delivered counts as
`closed_won`, a rejected or expired one as `closed_lost`, and everything else stays pending. **Grade**
(A to F), **feedback** and **led by** (`agent` or `human`) are yours to record.

### Where a brief came from

| Origin     | Meaning                                                                   |
| ---------- | ------------------------------------------------------------------------- |
| `adcp`     | A live AdCP `get_products` call from a buyer's agent.                     |
| `manual`   | A brief you entered yourself, for example from an emailed RFP.            |
| `imported` | A historical RFP added for reference. It never counts toward the metrics. |
| `starter`  | A practice brief used to see how your agent handles a request.            |

Each RFP also has a **purpose**: `live` for real demand, `evaluation` for tests, and `draft` for work
that has not gone to a buyer. Rows that are not live carry a badge so they are never mistaken for
real demand.

## The proposal pass

A pass is one **turn** of an RFP: one request and one response. Once a turn finishes it never
changes; revising it creates a new turn that points back to its parent.

```text theme={null}
queued → processing → ready | passed | needs_clarification | failed
```

A `ready` pass shows:

* **What the seller heard.** The brief as a business document: advertiser, buyer, budget, flight,
  markets, channels, formats and any constraints. Fields the buyer did not send are simply absent.
* **The decision.** `pitch` when the agent could meet the brief, or `counter_pitch` when it offers an
  alternative, together with what was requested, what is supported, and the limitations. For
  example: "Age targeting 30 to 55 is not available; this plan uses 25 to 54."
* **The plan.** Each product with its price, the floor it was priced against, its share of the
  budget, its role in the plan and the rationale for including it. A single-product plan still
  explains why it takes 100%.
* **Pass history.** Every earlier turn on the same RFP, so you can see how the answer evolved.

A `passed` turn records the reason and the condition under which a new turn would be useful. A
`needs_clarification` turn lists the questions and the catalog facts that were missing.

## Working a brief

<Steps>
  <Step title="Grade it">
    Record a grade, who led the response and a short note. Grades feed the Avg grade metric and tell
    you where the agent needs coaching.
  </Step>

  <Step title="Coach and re-run">
    Append a revision turn with an instruction, such as "push the Marquee CTV package harder". The
    agent composes a new pass under the same rules and floors.
  </Step>

  <Step title="Endorse the good ones">
    Endorse a brief and response pair you want the agent to learn from. Removing the endorsement
    keeps the record and only stops it being used as an example.
  </Step>

  <Step title="Share it">
    Request a representation of a pass (HTML, PDF, PowerPoint or the raw JSON response) to share
    with a buyer or a colleague.
  </Step>
</Steps>

## The same records over MCP

The inbox and the pass read and write the same records your own agent can use:

| Task                         | Tool call                                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| List briefs                  | `search` with `{ "kind": "rfp" }`                                                                       |
| Read one turn                | `get` with `{ "kind": "rfp_turn", "id": "turn_…" }`                                                     |
| Grade, coach, endorse, share | `save_rfp` with `action` set to `record_feedback`, `append_turn`, `endorse` or `request_representation` |
| Metrics for a period         | `get_rfp_performance`                                                                                   |
| Open the widgets             | `open_demand_inbox`, `open_proposal_pass` with `rfpId` and `turnId`                                     |

```json save_rfp (append a revision turn) theme={null}
{
  "action": "append_turn",
  "rfpId": "rfp_01JB7Q7Q3M4K9V6Z2N8T5X1C0D",
  "parentTurnId": "turn_01JB7Q8R0W2Y4H6K8M1P3S5U7V",
  "request": {
    "brief": "Holiday gift shoppers aged 30 to 55, US, CTV, audio and display, $50,000.",
    "instruction": "Lead with the Marquee CTV package and keep display under 20%."
  }
}
```

<Note>
  Each finished response from a hosted storefront agent, whether `ready` or `passed`, is one
  merchandising cycle and costs one IU. Failed turns and turns that ask for clarification are not
  charged.
</Note>

<CardGroup cols={2}>
  <Card title="AI Business Rules" icon="scale-balanced" href="/sell/ai-business-rules">
    The policy every pass is composed under.
  </Card>

  <Card title="Glossary" icon="book" href="/help/glossary">
    RFP, turn, disposition and more.
  </Card>
</CardGroup>