> 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.

# Guidance for AI agents

Products, product items, pricing plans and quote templates carry an `agent_context` object. Its `guidance` field is free text written for an AI agent rather than for a customer: when to pick this plan, what the item actually covers, which deals it suits.

---

## Why this matters

An agent working against your catalog, through [Solvimon's MCP server](/integrations/ai-assistants/claude) or your own integration, sees the same resources you do: names, references, prices, statuses. What it does not see is why a plan exists, which of two similar plans fits a deal, or that an item named "Platform fee" covers onboarding but not migration. `description` does not carry it either, because that field is often shown to customers, and is frequently left empty.

`agent_context.guidance` is the field for that knowledge. It travels with the resource, so the agent reads your intent instead of inferring it from a name.

## 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.

## Implementation

### 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. Send `"agent_context": null` to clear it.

### Via Desk

Each of the four resources has a guidance input on its detail screen, with suggestions on an empty field for what to write. The text is saved with the resource.

## 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](/integrations/ai-assistants/claude) for connecting an agent to your catalog, [Products](/platform-guides/products-and-pricing/product-catalog/products-1) and [Pricing plans](/platform-guides/products-and-pricing/pricing-plans).