> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/guides/conversation-context.md).
# Pass Context to Tool Parameters
Declare accepted conversation context on a service, supply values at creation, and bind them to tool parameters in an active Context Graph action state.
Use start-time conversation context to pass application values to a tool without asking the model to supply those parameters. There are three configuration points: the **service** declares accepted keys, the **conversation create request** supplies values, and the **Context Graph's state-to-tool binding** selects which parameters receive them.
This Platform API task extends [Build and Prove](/developer-guide/guides/build-and-prove.md) for an already configured service and tool. The map supplies inputs for one conversation; declaring it does not update world-model facts, create memory, or grant tool access.
## Choose the Right Context Feature
| You need to… | Use… |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Supply a typed application value to a tool for one conversation | The start-time `context` map and state binding in this guide |
| Add free-text guidance to a turn or an opening WebSocket exchange | The separate text fields in [Conversations](/developer-guide/platform-api/conversations.md) or [Sessions](/developer-guide/platform-api/platform-api/sessions.md) |
| Read or retain facts about a person across conversations | The [World Model](https://docs.concurrence.com/data/world-model) and [Functional Memory](https://docs.concurrence.com/agent/memory), under their own write and retrieval contracts |
| Supply verified identity for an integration's authentication | [External User Subject-Key Binding](/developer-guide/platform-api/integrations/external-user-subject-key-binding.md), rather than caller-supplied application context |
| Add stored user information through the Classic API | Classic [User Models and additional context](/developer-guide/classic-api/core-api/users/user-models.md) |
| Inspect a service's neutral configuration and tool descriptors | [Harness Context](/developer-guide/platform-api/functions/harness-context.md), a read-only discovery operation |
## Before You Start
Use a test workspace with permission to update its service, publish a Context Graph version, and create and inspect conversations. You need a configured read-only test tool whose input and result you can inspect. The example assumes that tool accepts two string parameters, `region` and `query`, and can report which region it actually received.
Use the regional API base and credentials assigned to that workspace; see [Choose Credentials](/developer-guide/getting-started/credentials.md). Save the current service schema and selected graph version before changing them. This guide does not provision a service, integration, or channel.
The synthetic test below uses a blocking tool with `result_persistence: "accumulate"` so its result can be inspected in history. If your workflow requires ephemeral results, keep that policy and verify the received input at the test tool instead; see [Tool Result Persistence](https://docs.concurrence.com/agent/context-graphs#tool-result-persistence).
{% hint style="warning" %}
**Current runtime limits.** The example uses a direct tool in an **action state**. Direct skill inputs do not currently receive this injection, and automatic `channel-id` has a text-session limitation. State coverage also depends on the deployed runtime. Read [Supported Tool Paths](#supported-tool-paths) and [Reserved Channel Identity](#reserved-channel-identity) before relying on either behavior.
{% endhint %}
## How the Values Reach the Tool
The service validates the values; the active state selects the binding. Verify the input received by the tool.
## 1. Declare the Schema on the Service
Set `accepted_context` in the top-level request body when creating or updating the service:
| Task | Operation |
| ------------------------------------ | ---------------------------------------------- |
| Create a service with its schema | `POST /v1/{workspace_id}/services` |
| Read the current schema | `GET /v1/{workspace_id}/services/{service_id}` |
| Replace an existing service's schema | `PUT /v1/{workspace_id}/services/{service_id}` |
Service updates use **PUT**, not PATCH. For the complete contracts, see [Services](/developer-guide/platform-api/workspaces/services.md).
For a dedicated test service, this is a complete update body:
```json
{
"accepted_context": [
{
"key": "region",
"type": "string",
"description": "Synthetic routing region for the test lookup",
"required": true
},
{
"key": "attempt",
"type": "number",
"description": "Optional test attempt number",
"required": false
}
]
}
```
Read the service back and confirm the schema before starting a conversation. A supplied list replaces the entire previous `accepted_context` list. Preserve any existing keys you still need; omission or `null` leaves the list unchanged, while `[]` accepts no caller-supplied context keys.
Each entry requires `key`, `type`, `description`, and `required`. Keys must be unique, 2-63 characters, and contain only lowercase letters, digits, and internal hyphens. Underscores and leading or trailing hyphens are invalid. Types are `string` or `number`; the service accepts at most 100 key declarations.
Adding a required key affects subsequent create requests validated against this service. Update callers together with the service schema.
`accepted_context` is service-level configuration. Selecting a previous graph version does not restore a previous context schema; save and restore that schema separately when rolling back.
## 2. Bind a Parameter in the Context Graph
The binding belongs to the **tool call specification on the state**, not the tool's create/update body. The underlying tool must already declare the parameter.
Read the service's selected Context Graph version. In the action state that calls your test tool, add `context_bindings` to its existing `action_tool_call_specs` entry, or to `exit_condition_tool_call_specs` when that is where the tool is used:
```json
{
"tool_id": "lookup_test_hours",
"execution": "blocking",
"result_persistence": "accumulate",
"context_bindings": ["region"]
}
```
This is a **ToolCallSpec fragment**, not a complete graph or tool creation request. Replace `lookup_test_hours` with the exact model-callable tool name, including a prefix such as `fn_` or `wsq_` for [Platform Functions](https://docs.concurrence.com/agent/platform-functions#using-functions-in-context-graphs). The execution and persistence values select the test behavior described above. Retain the entry's other settings and the graph's other states and bindings.
Each list item is both the accepted context key and the tool parameter name. There is no rename map: `region` binds to `region`; `patient-id` does not bind to `patient_id`. Declare the binding in each state where it is needed, using that state's tool-spec list. Keep a tool's bindings consistent across states, especially for voice runtimes that advertise one tool schema for the whole call.
Publish the complete revised graph using:
{% openapi src="" path="/v1/{workspace\_id}/context-graphs/{context\_graph\_id}/versions" method="post" %}
{% endopenapi %}
Select that graph version in the test service's [version set](/developer-guide/platform-api/workspaces/services.md#version-sets). Preserve its agent and model selections. A new graph version does not change a version set pinned to an older one.
**Check:** The selected graph version contains the binding in the action state that will execute the tool. The tool's original input schema still declares `region`; the runtime removes it from the model-visible schema for the bound call.
## 3. Supply Values When Creating the Conversation
Send the map in `context` on `POST /v1/{workspace_id}/conversations`. Replace the synthetic service UUID with your test service ID:
```json
{
"service_id": "11111111-1111-4111-8111-111111111111",
"channel": "web",
"context": {
"region": "test-east",
"attempt": 1
}
}
```
The create request accepts at most 50 context keys. String values are limited to 8,192 characters. Service validation returns `422` for unknown keys, missing required keys, and values that do not match the declared type after request parsing. Send a JSON number for `number`, not a numeric string or a boolean. Arrays, objects, and null values are not context values.
**Validation edge case:** The public contract excludes booleans, but the current conversation-create parser can coerce `true` and `false` to `1` and `0` before service validation. Validate your application's values before sending them; do not rely on a boolean producing `422`.
An empty `context` map works only when the service has no required keys. If a bound optional key is absent, the runtime does not supply a value for it; the tool can apply its own default or reject missing input. Do not bind a required tool parameter to an optional key unless that absence is handled.
Save the returned conversation ID before sending a turn. Context is stored for the conversation and restored on subsequent text turns. The turn request's text `context` field is a different feature; it does not update this map. See [Conversation operations](/developer-guide/platform-api/conversations.md).
### Outbound Requests
Outbound SMS and iMessage use the same create operation with the channel's required `recipient` and `use_case_id`. The service's `accepted_context` validates the map before dispatch. Existing channel permissions, provisioning, and delivery requirements still apply.
Outbound voice uses `POST /v1/{workspace_id}/calls/outbound` and its `context` map. Validation and routing use the service bound to the supplied `use_case_id`; this request does not select a service through `service_id`. Follow [Calls](/developer-guide/platform-api/conversations/calls.md) for the required phone, patient, and routing inputs. Its `goal` and `system_prompt` supply startup instructions; `metadata` supplies correlation data. None replaces the typed `context` map. The 50-key and 8,192-character limits above describe the conversation-create body, not a universal limit for every context-bearing route.
## 4. Verify the Bound Input
Send a message that triggers the read-only lookup, such as “Use the test lookup to show opening hours.” The model supplies `query`; the runtime supplies `region` from the conversation context when the bound action-state tool executes.
Use the test tool's observed request or a result that explicitly echoes its received parameters to verify:
```json
{
"region": "test-east",
"query": "opening hours"
}
```
The exact query wording may vary. Confirm that the tool received `region: "test-east"`, that its result reached durable conversation history under this test's accumulate policy, and that the selected service and graph versions match your test record. Ephemeral bindings retain execution metadata instead of raw arguments and results. Tool telemetry is useful when available; model narration alone does not prove which parameters reached the tool.
Repeat in a fresh conversation with a different synthetic region to check that the value is conversation-specific. Also try omitting `region`, adding an undeclared key, and sending `attempt: "one"`; each create should return `422` before a conversation is created. Resolve ambiguous network outcomes by inspecting retained state before retrying.
Close successful test conversations and verify closure through the [close and detail operations](/developer-guide/platform-api/conversations.md). Restore the saved service schema and version selection if the test configuration is temporary. Closing a conversation does not erase its retained context or undo an external operation.
## Supported Tool Paths
The runtime reviewed on September 14, 2026 resolves the tool's binding from the state where the call starts and carries that binding into execution. This includes action, decision, and data-collection states. Earlier builds resolved context bindings only from the current action state; verify the deployed behavior before using the wider coverage. The example above uses an action state in either case.
| Tool or state | Current behavior |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Direct integration endpoint | Context parameters are injected before the integration call when the launching state's spec binds that exact tool name. Integration authentication and grants still apply. |
| Direct world tool | Uses the same injection path. Its existing parameter schema, validation, and execution policy still apply. |
| SQL-backed platform function or workspace data query | Uses the direct-tool path when exposed to the conversation. Parameter names must also satisfy the SQL tool's own naming rules; a shared simple name such as `region` avoids underscore/hyphen mismatches. |
| Direct skill input | Does not currently receive this injection. Do not assume hiding a skill parameter also fills it at dispatch. |
| Decision or data-collection state | The latest runtime resolves the binding from that state's `tool_call_specs` list. Action states use `action_tool_call_specs` and `exit_condition_tool_call_specs`. Annotation states do not bind tools. |
| Standalone tool test or direct function invocation | Has no conversation context binding merely because the tool is used in a graph. Supply the endpoint's required inputs through that operation's contract. |
Context bindings are distinct from identity bindings and authorization-bound SQL parameters. Keep their parameter names separate; do not context-bind credential or access-control parameters. Caller-supplied context is application input, not proof of identity or permission. Removing a parameter from the model's tool schema does not make its value a secret: tool results, retained context, or telemetry can expose it. Do not put credentials in this map.
Tool result persistence governs the tool journal and later prompts; it does not clear the separately stored start-time context map. Apply your retention requirements to both.
## Reserved Channel Identity
The reserved key is **`channel-id`**, with a hyphen. It is not `channel_id`, a use-case ID, a conversation UUID, or the business's sending address.
The initialization rule fills a declared string `channel-id` from a non-empty caller/channel address, overriding the value in the initialization map. Voice uses the caller or destination phone number; messaging adapters carry their channel-specific sender identifier. This rule alone does not establish working end-to-end injection for every channel.
On the inbound voice path reviewed September 16, 2026, valid caller numbers are normalized to E.164. Withheld, anonymous, invalid, and non-phone caller identifiers are treated as unidentified, so they supply no phone address for automatic filling. An absent address does not erase a caller-supplied context value; do not use a supplied `channel-id` as a fallback identity. Even a valid phone address is not proof of the caller's identity or authority.
{% hint style="warning" %}
**Text-session limitation, reviewed September 14, 2026.** Current text-session setup subsequently replaces the auto-filled map with supplied or stored conversation context. Automatic `channel-id` is therefore not reliable on that path and must not be treated as a server-verified identity. Confirm the deployed behavior with the implementation owner before depending on automatic identity in SMS, iMessage, WhatsApp, email, or web tools.
{% endhint %}
When preparing a supported deployment for automatic filling, declare `channel-id` as `type: "string"` and `required: false`. API validation occurs before initialization, so `required: true` can reject a create request that omits it before any auto-fill occurs. An absent caller address also means there is nothing to auto-fill. Do not send a placeholder value to bypass that validation.
Use an explicitly supplied, non-reserved key for ordinary application context while arranging a verified channel-identity path. It remains caller-supplied data and must not replace the tool's authorization checks.
## Troubleshooting
| Symptom | Check next |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Service update returns `405` | Use `PUT /services/{service_id}`, not PATCH or PUT on the collection. |
| Schema or create request returns `422` | Check key spelling, uniqueness, scalar types, required keys, and request limits. `channel_id` is not a valid accepted-context key. |
| Bound parameter is missing | Check the selected graph version, launching state, deployed state coverage, exact tool name and parameter name, and whether the optional context key was supplied. |
| A warehouse parameter uses underscores | There is no underscore-to-hyphen translation. Choose a name allowed by both contracts or revise the tool interface. |
| Model is still asked for the value | Confirm the binding is on the active state's ToolCallSpec, rather than on the tool definition or an unselected graph version. |
| `channel-id` is absent or differs from the sender | Check whether the caller has a valid phone address and whether the text-session limitation applies; do not infer identity from a supplied value. |
Continue with [Verify an Integration Action](/developer-guide/guides/verify-an-integration-action.md) when the tool performs an external write, and [Build and Prove](/developer-guide/guides/build-and-prove.md) for a reviewed configuration rollout.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.concurrence.com/developer-guide/guides/conversation-context.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
