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

# MCP tools

> The generate_template and list_templates tools — contract, input/output shapes, and integration patterns.

Canvas exposes two MCP tools in the **Planning** toolset. Both are visible to any agent connected to your Deal Brain MCP server with a valid session.

| Tool                | Purpose                                             |
| ------------------- | --------------------------------------------------- |
| `list_templates`    | Enumerate templates visible to the calling user.    |
| `generate_template` | Render a template by key, against optional context. |

A third internal tool (`get_template`) is used by Deal Brain's own agent runtimes to hydrate a template before rendering. It is not exposed publicly over MCP.

## `list_templates`

Returns all templates the calling user can see, deduplicated by scope precedence (User > Organization > System).

### Input

No parameters. The tool always operates against the calling user's identity.

### Output

Returns two content blocks: a `structuredContent` JSON payload and a human-readable text summary.

<CodeGroup>
  ```json structuredContent theme={null}
  {
    "templates": [
      {
        "key": "daily-brief",
        "name": "Daily deal brief",
        "description": "A 3-section brief of today's deal priorities.",
        "scope": "system",
        "status": "active"
      },
      {
        "key": "user-templates/opportunity-readout-3p",
        "name": "Opportunity readout (3-paragraph)",
        "description": "Three-paragraph brief covering context, last meeting, and next steps.",
        "scope": "user",
        "status": "active"
      }
    ]
  }
  ```

  ```text text block theme={null}
  You have 14 templates available:
    • daily-brief (system) — Daily deal brief
    • meeting-debrief (system) — Post-meeting debrief
    • drafts/follow-up (system) — Quick follow-up message draft
    • user-templates/opportunity-readout-3p (user) — Opportunity readout (3-paragraph)
    …
  ```
</CodeGroup>

### Behavior

* Returns only `active` templates. Drafts are invisible.
* Returns only templates the calling user can see, with scope precedence applied — the user sees the most-specific version of each key.
* Sort order: System templates first (alphabetical by key), then Organization, then User.

### Example agent prompt

> Show me all the available templates and pick the one closest to a "deal qualification readout."

The agent calls `list_templates`, scans the descriptions, and chooses the best match by key.

## `generate_template`

Renders a template by key, binding optional context (most commonly an opportunity ID), and returns the system prompt + rendered body ready for the LLM.

### Input

<ParamField path="key" type="string" required>
  The template's stable key. Examples: `daily-brief`, `user-templates/opportunity-readout-3p`.
</ParamField>

<ParamField path="opportunityId" type="string">
  The UUID of the opportunity to bind. If the template uses opportunity variables and this is omitted, those variables render as empty.
</ParamField>

<ParamField path="contextOverrides" type="object">
  Optional key-value pairs that override specific variables at render time. Useful for testing or for binding values not in the data layer.

  Example: `{ "company tone of voice": "casual and warm" }`
</ParamField>

### Output

Returns two text blocks:

1. **System prompt** — Deal Brain's standard model directive plus any instruction variables compiled from the template.
2. **Rendered body** — The template's content with all `data` variables substituted.

<CodeGroup>
  ```text Block 1 — system prompt theme={null}
  You are an AI assistant rendering a Canvas template for [user name]
  at [organization name]. Today is [current date].

  Template instructions (follow all):
  - Summarize the last meeting in 2 sentences. Only use facts present in the data.
  - Limit total output to under 300 words.
  - Use a confident, direct tone. Avoid hedging.

  Do not include instruction text in your output. Only emit the rendered body.
  ```

  ```text Block 2 — rendered body theme={null}
  # Opportunity readout

  Deal: Acme — Platform expansion with Acme Inc., stage Proposal sent.

  Pat walked us through the security review checklist on Tuesday and committed
  to looping in their legal team this week. We've heard nothing back on the
  MSA redlines we sent.

  Next steps:
  - Follow up with Pat on legal timeline by EOW
  - Schedule a Jordan check-in for next Tuesday
  - Re-send MSA with executive summary attached
  ```
</CodeGroup>

### Behavior

* **Scope precedence applies.** The key resolves to User > Organization > System for the calling user.
* **Status gate.** If the resolved template is `draft`, the tool returns an error.
* **Missing opportunity.** If `opportunityId` refers to a deal the calling user can't see, the tool returns an authorization error — not an empty render.
* **Missing variables.** If a `data` variable's value isn't present in the bound context, it renders as an empty string. The template should be written to handle this gracefully.

### Task-handoff semantics

For date-anchored templates (daily/meeting briefs and debriefs), `generate_template` supports MCP task handoff:

* The first call kicks off the render asynchronously and returns a task ID.
* Subsequent polling resolves to the final two-block output.
* The result is cached per (template key, opportunity ID or date, calling user) for the cache window.

This avoids long-running blocking calls in agent conversations. Your MCP client handles polling automatically.

<Note>
  Draft-message templates (e.g., `drafts/follow-up`) do **not** support task handoff — they're synchronous and not cached, because each draft is bespoke.
</Note>

### Errors

| Error                      | Cause                                                                         |
| -------------------------- | ----------------------------------------------------------------------------- |
| `TEMPLATE_NOT_FOUND`       | No template with the given key is visible to the calling user.                |
| `TEMPLATE_NOT_ACTIVE`      | Template resolved but its status is `draft`.                                  |
| `OPPORTUNITY_NOT_FOUND`    | `opportunityId` was provided but the deal is not visible to the calling user. |
| `INVALID_CONTEXT_OVERRIDE` | `contextOverrides` contains a key that doesn't match any known variable.      |

### Example agent flow

```
Agent: list_templates()
  → Picks "user-templates/opportunity-readout-3p"

Agent: generate_template({
  key: "user-templates/opportunity-readout-3p",
  opportunityId: "0192f73e-…"
})
  → Receives system prompt + rendered body
  → Sends to its own LLM with the system prompt and rendered body as user content
  → Returns the model's response to the human user
```

## Integration patterns

### Customer-authored templates in a custom agent

If you're building an agent on top of Deal Brain and want customers to author their own templates inside Deal Brain's Canvas UI, the pattern is:

1. Customer authors the template in Canvas, sets it to Active, and uses a key prefix you control (e.g., `your-product/<feature>`).
2. Your agent calls `list_templates`, filters to keys starting with `your-product/`, and presents them to the customer as choices.
3. Your agent calls `generate_template({ key, opportunityId })` and sends the result to your LLM.

This lets your customers customize behavior without you shipping code.

### Caching for repeated reads

For date-anchored templates that the agent calls repeatedly within the same window (e.g., a `daily-brief` checked multiple times in a morning), rely on the built-in task-handoff cache documented above — Deal Brain caches by `(template key, opportunity ID or date, calling user)` for the cache window, so repeated calls within the window hit the same render.

## See also

* [Publishing](/canvas/publishing) — status, scope, and how a template becomes visible to `list_templates`.
* [Variables](/canvas/variables) — the data and instruction tokens that templates resolve at render time.