> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Agent context

Solvimon is built to be run headless and by agents. Every operation in Desk is available through the [API](/api-reference), the [MCP server](/mcp/claude-integration) puts the billing lifecycle in an agent's hands, and the catalog carries something most billing systems leave out: the reasoning behind it. Products, product items, pricing plans and quote templates have an `agent_context` object whose `guidance` field is written for an AI agent, not for a customer. It says when to pick this plan, what the item actually covers, and which deals it suits. In Desk, the same field is called **Guidance**.

---

## Why this matters

When billing runs without a person clicking through a UI, the agent doing the work only knows what the API tells it. A typical billing API tells it what a plan *is*: a name, a reference, prices, a status. It does not tell it what the plan is *for*: why it exists, which of two similar plans fits this deal, or that an item named "Platform fee" covers onboarding but not migration. `description` does not carry that either, because it is often shown to customers and is frequently left empty.

Without that knowledge an agent guesses from names. With it, the agent reads your intent. Agent context turns the catalog from a list of SKUs into one an agent can reason about.

| Without agent context                                                                        | With agent context                                                            |
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| "Use our most extensive plan" lands on whichever plan has the longest name or highest price. | The agent picks the plan whose guidance says it is the enterprise tier.       |
| Two near-identical plans look interchangeable.                                               | Guidance says which one to pick, and when.                                    |
| An agent combines a legacy plan with a new add-on.                                           | Guidance names the combinations that must not happen.                         |
| The rules of your catalog live in a sales engineer's head.                                   | They live on the resource, and travel with it to every agent and integration. |

## Built for headless and agent-first billing

Agent context is useful wherever software, not a person in Desk, decides which part of your catalog to use.

#### Agent-led quoting

A sales rep asks an assistant to quote a prospect. The agent reads the guidance on your quote templates and plans, picks the right ones, and drafts the quote for the rep to approve.

#### Self-serve signup through an agent

Your own product's agent recommends a plan to a user and creates a [checkout link](/platform-guides/customers-and-billing/hosted-checkout). Guidance tells it which plan fits the usage the user described.

#### RevOps and finance copilots

An internal assistant that builds plans, versions prices, or answers "which customers are on the legacy tier" reads the same guidance, so it respects the boundaries your team set.

#### Headless integrations

Your own backend or workflow reads `agent_context` from the API like any other field and passes it to the model that makes the decision. No Desk, no MCP required.

## How it works

`agent_context` is an object with one field today, `guidance`, holding up to 2,500 characters of free text. Line breaks are allowed, so you can write a short list rather than one paragraph. It is available on four resources:

| Resource                                                                         | What belongs in it                                                               |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [Product](/platform-guides/products-and-pricing/product-catalog/products-1)      | What the product is in commercial terms, and which customers it is for.          |
| Product item                                                                     | What the item actually covers, and what it does not. Units and their meaning.    |
| [Pricing plan](/platform-guides/products-and-pricing/pricing-plans)              | When to choose this plan over a neighbouring one, and the deal shape it suits.   |
| [Quote template](/platform-guides/customers-and-billing/quoting/quote-templates) | Which situation the template is for, and what the sales rep still has to decide. |

The field is read and written like any other field on those resources. It is not shown to customers: it does not appear on an invoice, in the [customer portal](/platform-guides/customers-and-billing/customer-portal), or on a quote the customer sees.

### How agents read it

* **Through the MCP server.** Solvimon's MCP server gives the guidance to the agent together with the catalog metadata. The [`get_agent_context`](/mcp/developing-for-solvimon#get_agent_context) tool returns only a resource's identity fields plus its guidance, so an agent can compare plans or templates cheaply before it chooses one.
* **Through the API.** `agent_context` is part of the resource in every response, so your own agent or integration gets it with no extra call.

### Guidance is advisory

Guidance informs the agent's choice. It does not grant permissions. It never outranks the user, and it cannot authorise a discount, skip an approval, or trigger any action the user has not asked for. If guidance conflicts with the user's request, the MCP server tells the agent to follow the user and point out the conflict. Approvals and Desk permissions apply as they always do.

## Implementation

### Via MCP

Ask your agent to write it, or call the tools directly. [`write_agent_context`](/mcp/developing-for-solvimon#write_agent_context) **replaces** the whole guidance string, so read the current text with `get_agent_context` first and write back the merged version. An empty string clears it.

**`Set guidance on a pricing plan`**

```json Set guidance on a pricing plan
{
  "resource_type": "pricing_plans",
  "id": "ppla_5RmXe2QbtKfYuA9DcNH3P",
  "guidance": "Mid-market plan, 50 to 500 seats. Pick this over Starter once a prospect asks for SSO or a custom contract."
}
```

When an agent creates a product or product item with `write_product_catalog`, it can include `agent_context: {guidance}` in the body to record who the resource is for from the start.

> **Tip**
>
> A good first prompt: *"Go through our active pricing plans and quote templates, and draft agent guidance for each one. Show me the drafts before writing anything."* Review the drafts, then let the agent write them.

### Via API

Set it with a `PATCH` on the resource, for example [PATCH /v1/pricing-plans/\{id}](https://docs.solvimon.com/api-docs/configuration-api/pricing-plans/patch-pricing-plans-by-resource-id-or-reference):

**`Add guidance to a pricing plan`**

```bash Add guidance to a pricing plan
curl -X PATCH https://test.api.solvimon.com/v1/pricing-plans/growth-2026 \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_context": {
      "guidance": "Mid-market plan, 50 to 500 seats. Pick this over Starter once a prospect asks for SSO or a custom contract, and over Enterprise when they do not need a dedicated environment. The committed API volume is annual, not monthly; overage is billed per 1,000 calls. Do not combine with the legacy Growth 2024 plan on the same subscription."
    }
  }'
```

**`Response`**

```json Response
{
  "object_type": "PRICING_PLAN",
  "id": "ppla_5RmXe2QbtKfYuA9DcNH3P",
  "reference": "growth-2026",
  "agent_context": {
    "guidance": "Mid-market plan, 50 to 500 seats. Pick this over Starter once a prospect asks for SSO ..."
  }
}
```

The same shape applies to [products](https://docs.solvimon.com/api-docs/configuration-api/products/patch-products-by-resource-id-or-reference), [product items](https://docs.solvimon.com/api-docs/configuration-api/product-items/patch-product-items-by-resource-id-or-reference) and [quote templates](https://docs.solvimon.com/api-docs/configuration-api/quote-templates/patch-quote-templates-by-resource-id-or-reference). Send `"agent_context": null` to clear it.

### Via Desk

Open a product, product item, pricing plan or quote template and fill in the **Guidance** field on its detail screen. An empty field shows suggestions for what to write. The text is saved with the resource and is what the API returns as `agent_context.guidance`.

## What to write

Write what you would tell a new sales engineer in their first week, not what you would print in a brochure.

* **The decision, not the description.** "Pick this over Starter once they ask for SSO" is useful. "Our flexible mid-market plan" is not.
* **The boundaries.** What the item does not cover is often what an agent gets wrong.
* **The traps.** Plans that must not be combined, units that are annual rather than monthly, items that look interchangeable and are not.
* **Keep it current.** It is free text, so nothing validates it against the plan. Guidance describing last year's pricing is worse than none, because an agent will act on it.

> **Warning**
>
> Treat guidance as instructions an agent may act on. Do not put credentials, customer names, internal cost prices, or anything you would not want repeated back in an agent's answer into this field.

## Edge cases

* **It does not change billing.** Nothing in `guidance` affects pricing, invoicing or entitlements. It informs the agent that reads it, and nothing else.
* **2,500 characters is the limit.** A longer value is rejected on the field. If you need more, the plan is usually carrying a distinction that belongs in two plans.
* **Only four resources carry it today.** Subscriptions, customers and invoices do not. The object exists so more fields can be added to it later without a new field on every resource.

---

See also: [Claude integration](/mcp/claude-integration) to connect an agent to your account, [Developing for Solvimon](/mcp/developing-for-solvimon) for the full MCP tool reference, and [Product catalog](/platform-guides/products-and-pricing/product-catalog) for how products and items fit together.