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

# Tool catalog

> Every tool the Propal MCP exposes, grouped by domain.

The MCP server registers **68 tools** spanning the same resources as the REST
API plus a granular Propal DSL for editor content. This page is the canonical
catalog. For live discovery (with the current Zod schemas), call
[`list_propal_components`](/mcp/components-dsl) and
[`get_propal_component_schema`](/mcp/components-dsl#schema-discovery).

<Note>
  The MCP server enforces organization scoping on every call. The user's
  membership is re-checked from the OAuth token.
</Note>

## Organization

| Tool                        | Purpose                                        |
| --------------------------- | ---------------------------------------------- |
| `get_organization`          | Returns id + name of the current organization. |
| `list_organization_members` | Lists members of the current organization.     |

## Metrics

| Tool                            | Purpose                                                   |
| ------------------------------- | --------------------------------------------------------- |
| `get_metrics_overview`          | Top-level KPIs (proposals, conversion, revenue).          |
| `get_metrics_pipeline`          | Pipeline stages and value distribution.                   |
| `get_metrics_conversion`        | Conversion rates by stage.                                |
| `get_metrics_sales`             | Sales totals by period (`weekly` / `monthly` / `yearly`). |
| `get_metrics_team_performance`  | Per-member performance.                                   |
| `get_metrics_proposal_timing`   | Time-to-send / time-to-sign breakdowns.                   |
| `get_metrics_rejection_reasons` | Aggregated rejection reasons.                             |

## Themes (CRUD)

| Tool                       | Purpose                                                   |
| -------------------------- | --------------------------------------------------------- |
| `list_themes`, `get_theme` | Read themes available to the org.                         |
| `create_theme`             | Advanced mode — full `colors` + `section_styles` control. |
| `update_theme`             | Advanced patch — replace any field.                       |
| `delete_theme`             | Removes a theme (forbidden if used by a proposal).        |

## Theming (workflow)

| Tool                          | Purpose                                                                                          |
| ----------------------------- | ------------------------------------------------------------------------------------------------ |
| `list_design_presets`         | Catalog of \~25 stock presets (matcha, ocean, ink, …).                                           |
| `create_theme_from_preset`    | Snapshots a preset into a persistent theme.                                                      |
| `generate_theme_from_palette` | Smart mode — generates a full theme from `{ page_bg, accent, section_bgs? }` with WCAG warnings. |
| `update_theme_section_style`  | Patches a single slot in `section_styles[]` without rewriting the whole array.                   |
| `validate_palette`            | Returns WCAG warnings for a palette without persisting.                                          |
| `apply_theme_to_proposal`     | Sets `proposal.theme_id`.                                                                        |
| `detach_theme_from_proposal`  | Clears `theme_id`; optionally snapshots the resolved style first so the look is preserved.       |
| `get_proposal_resolved_style` | Returns the final `IProposalStyle` applied to a proposal (theme → proposal\_style → defaults).   |
| `set_proposal_section_attrs`  | Patches a section's attrs (`section_style`, `theme`, `background_image`) by index.               |

See [theming](/mcp/theming) for the full workflow.

## Catalog

| Tool                                                                | Purpose              |
| ------------------------------------------------------------------- | -------------------- |
| `list_catalog_items`, `get_catalog_item`                            | Read products/items. |
| `create_catalog_item`, `update_catalog_item`, `delete_catalog_item` | Mutate items.        |
| `list_bundles`, `get_bundle`, `delete_bundle`                       | Manage bundles.      |

## Templates

| Tool                             | Purpose                                       |
| -------------------------------- | --------------------------------------------- |
| `list_templates`, `get_template` | Read proposal templates.                      |
| `create_template_from_proposal`  | Snapshot a proposal into a reusable template. |
| `delete_template`                | Removes a template.                           |

## Leads

| Tool                                        | Purpose                                   |
| ------------------------------------------- | ----------------------------------------- |
| `list_leads`, `get_lead`                    | Read contacts.                            |
| `create_lead`, `update_lead`, `delete_lead` | Mutate contacts.                          |
| `list_lead_proposals`                       | Returns the proposals attached to a lead. |

## Media

| Tool                                                               | Purpose                                                    |
| ------------------------------------------------------------------ | ---------------------------------------------------------- |
| `list_media_files`, `get_media_file`                               | Read uploaded assets.                                      |
| `create_media_upload_url`                                          | Returns a signed URL — clients upload directly to storage. |
| `delete_media_file`                                                | Removes an asset.                                          |
| `list_media_folders`, `create_media_folder`, `delete_media_folder` | Folder structure.                                          |

## Proposals (metadata)

| Tool                                     | Purpose                                                                    |
| ---------------------------------------- | -------------------------------------------------------------------------- |
| `list_proposals`, `get_proposal`         | Read proposals (filtered by status / lead / archived).                     |
| `create_proposal`                        | Creates blank or from a template.                                          |
| `update_proposal`                        | Patches metadata (title, slug, language, theme\_id, sign/payment toggles). |
| `delete_proposal`                        | Soft-deletes.                                                              |
| `publish_proposal`, `unpublish_proposal` | Toggles `page_status`.                                                     |
| `duplicate_proposal`                     | Clones a proposal.                                                         |
| `get_proposal_signature`                 | Reads the signature on a signed proposal.                                  |
| `list_proposal_revision_requests`        | Reads pending revisions.                                                   |

## Components — Propal DSL

| Tool                                       | Purpose                                                            |
| ------------------------------------------ | ------------------------------------------------------------------ |
| `list_propal_components`                   | Live catalog of DSL components + structural rules.                 |
| `get_propal_component_schema`              | Detailed schema of a single component (props, enums, constraints). |
| `validate_propal_component_tree`           | Validates a tree without writing.                                  |
| `append_propal_component_tree_to_proposal` | Validates → assembles → atomically appends sections.               |

See [components DSL](/mcp/components-dsl) for the grammar.

## Editing

| Tool                           | Purpose                                                     |
| ------------------------------ | ----------------------------------------------------------- |
| `get_proposal_tree`            | Returns the document mapped to DSL (best-effort).           |
| `insert_section_at_index`      | Inserts BEFORE `index`.                                     |
| `update_section_at_index`      | Replaces 1 item by N sections.                              |
| `delete_section_at_index`      | Removes a root item.                                        |
| `reorder_sections`             | Permutation of indices.                                     |
| `find_and_replace_in_proposal` | Literal text replace, optional case-sensitive / whole-word. |

See [editing](/mcp/editing) for the full workflow including concurrency
semantics.

## Discovering tools at runtime

Most clients list tools automatically when they connect. To inspect the catalog
yourself, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @modelcontextprotocol/inspector https://api.propal.io/v1/mcp
```

Each tool exposes:

* **title** — short human-readable name
* **description** — when to use it, structural rules, return shape
* **inputSchema** — Zod-derived JSON Schema (clients use this to validate
  their own input before calling)

For the components DSL specifically, the descriptions and rules are accessed
via the `list_propal_components` tool — they live in code as the source of
truth.