> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt > Use this file to discover all available pages before exploring further. # Variable suggestions > Every token that resolves, for the place you are about to use it. A `{{token}}` is only valid in some places. This returns the ones that actually resolve for a given `phase`, so you can offer a picker instead of letting someone discover a typo at call time. ```http theme={"dark"} GET /v1/agents/ag_7f3.../variable-suggestions?phase=prompt ``` ```json theme={"dark"} [ { "value": "{{callee_name}}", "category": "custom" }, { "value": "{{order_id}}", "category": "custom" }, { "value": "{{pre.get_customer.tier}}", "category": "pre" }, { "value": "", "category": "activate" } ] ``` ## One notation Everything is `{{...}}`, with one exception: angle brackets mark a tool the agent may **call** during the conversation, which is an instruction rather than a value. | Looks like | Is | | --------------------------- | -------------------------------------------------------- | | `{{order_id}}` | one of the agent's own `variables` | | `{{pre.get_customer.tier}}` | a value a pre-call tool returned | | `{{api.lookup.status}}` | a value an on-call tool returned | | `{{call.from_number}}` | a detail of the call in progress | | `{{agent.agent_id}}` | an identifier for the agent or workspace | | `` | **not a value** — it arms that tool for the conversation | `category` tells you which group a row belongs to, for headings in a picker: `custom`, `pre`, `api`, `call`, `agent`, and `activate` for the `` rows. ## Which phase to ask for | `phase` | Where you are writing | What comes back | | ---------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | | `prompt` | the system prompt or a greeting | the agent's variables, `` activations, and any tool's results | | `pre_call` | the request body of a tool that runs **before** the call connects | the agent's variables, other pre-call results, plus `call.` and `agent.` | | `on_call` | the request body of a tool the agent calls **during** the conversation | the agent's variables, pre-call results, and other on-call results | `phase` is required — the answer is different for each, and defaulting would hand someone a token that silently resolves to nothing. **Tools are built in the dashboard.** The two tool phases describe what a tool's request may reference; they do not let you create one. If your agent has no tools, `pre_call` and `on_call` return your variables plus the `call.` and `agent.` sets. `version_id` takes a version **number** or a uuid, like every other version-taking route, and defaults to the newest version. Pass it to ask about a specific draft, since a tool added to one draft does not exist in another. **`agent.` and `call.` are pre-call only.** By the time an on-call tool runs, the call's own facts are already in the conversation — so they are offered where they are needed to *open* the call, and not where they would be noise. ## Writing a variable in a prompt Both `{{order_id}}` and `{{custom.order_id}}` resolve at call time. Prefer the **bare** form, which is what this endpoint returns and what the [agent schema](/developers/agents/update) documents: saving a prompt that contains a bare `{{order_id}}` also **registers** the variable if it does not exist yet, so you can set its default afterwards. The dotted form is not picked up that way — it reads as a namespace reference, so nothing is created and, if you never declared `order_id` yourself, the token resolves to nothing. Inside a tool's request body, either form works the same way. ## OpenAPI ````yaml developers/openapi.json GET /v1/agents/{agent_id}/variable-suggestions openapi: 3.1.0 info: title: Vocily API description: >- Public REST API for Vocily. Build and configure an agent, publish a version and put it live, place outbound calls, and read back calls, chats and what the agent remembered. Authenticate with a workspace API key as a Bearer token. Some things stay in the dashboard, by design: creating an API key, buying or connecting a phone number, setting an agent's webhook URL, connecting WhatsApp and its templates, building HTTP tools, and running batch campaigns. version: v1 servers: - url: https://api.vocily.ai description: Production security: [] paths: /v1/agents/{agent_id}/variable-suggestions: get: tags: - api-tools summary: List Agent Variable Suggestions description: >- Every `{{token}}` this agent can reference, for one position. What is available differs by position: a prompt can arm a tool and read any tool's output, a pre-call request can read the call's own details, and an on-call request can read what pre-call produced. Asking for the wrong list is how a token silently renders as itself. operationId: >- list_agent_variable_suggestions_v1_agents__agent_id__variable_suggestions_get parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id description: The agent's id, as `GET /v1/agents` returns it. - name: phase in: query required: true schema: type: string description: >- Which position the token will be used in. `prompt` — the system prompt or a greeting, which is the list a prompt editor wants. `pre_call` — inside the request body of a tool that runs before the call connects. `on_call` — inside the request body of a tool the agent calls mid-conversation. Tools themselves are built in the dashboard; these two lists say what their requests may reference. title: Phase description: >- Which position the token will be used in. `prompt` — the system prompt or a greeting, which is the list a prompt editor wants. `pre_call` — inside the request body of a tool that runs before the call connects. `on_call` — inside the request body of a tool the agent calls mid-conversation. Tools themselves are built in the dashboard; these two lists say what their requests may reference. - name: version_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Agent version; defaults to the newest one. title: Version Id description: Agent version; defaults to the newest one. responses: '200': description: Every token that resolves in the place you asked about. content: application/json: schema: type: array items: type: object properties: value: type: string description: The token to paste, exactly as it must appear. category: type: string description: >- What kind of token it is, for grouping a picker: `custom`, `call`, `agent`, `pre`, `api`, or `activate` for an `` row. example: - value: '{{callee_name}}' category: custom - value: '{{callee_number}}' category: custom '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: detail: Invalid API key code: UNAUTHORIZED '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded — honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: rate_limited security: - bearerAuth: [] components: schemas: ApiError: type: object description: >- Error envelope. `code` is derived from the HTTP status, so branch on it for the CLASS of failure; the specific reason is `detail.code`. Every public refusal carries both. properties: detail: type: object description: >- The reason. `code` is the domain reason (e.g. `call_not_found`) and `message` is a sentence safe to log. On a `422` it also carries `errors[]`, one entry per rejected field — see `HTTPValidationError`. properties: code: type: string example: call_not_found message: type: string example: Call not found required: - code - message code: type: string description: Derived from the HTTP status, not the domain reason. example: NOT_FOUND HTTPValidationError: type: object title: HTTPValidationError description: >- A request the API could not read: a field of the wrong type, out of range, missing, or one we do not accept. Same envelope as every other error. properties: detail: type: object description: >- What was wrong, as `code`, a one-line `message`, and every offending field in `errors`. required: - code - message - errors properties: code: type: string enum: - validation_error message: type: string description: >- The first problem in one line, with a count of the rest — e.g. `model.temperature: Input should be less than or equal to 2 (and 1 more)`. errors: type: array items: $ref: '#/components/schemas/ValidationError' description: >- One entry per offending field. **Every problem is reported at once**, not just the first, so a malformed body needs one round trip to fix rather than one per field. code: type: string enum: - VALIDATION_ERROR description: Derived from the HTTP status, as on every error. ValidationError: type: object title: ValidationError required: - field - message - type properties: field: type: string description: >- The offending field as a path from the root of your request — `voice.speed`, `variables[0].key`, or `query.limit` for a query parameter. **This is the field to read.** message: type: string description: What is wrong with it, in plain language. type: type: string description: >- A stable machine code for the kind of failure, e.g. `extra_forbidden` for a field we do not accept, `missing` for a required one, or `less_than_equal` for a number out of range. Switch on this rather than on `message`, which may be reworded. securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.' ````