> 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/platform-api/functions/tool-testing.md).

# Tool Testing

Test context graph tools without starting a phone call. Resolve available tools, execute world tools, and understand test-mode persistence.

The tool testing endpoints let you resolve all context graph tools (world tools, skills, integrations) for a service and execute world tools in isolation, without making a phone call. Skills and integrations are tested through their own dedicated test/invoke endpoints. This is useful during development for verifying tool behavior, debugging input/output schemas, and validating write operations before wiring tools into a live conversation flow.

{% hint style="warning" %}
**Admin/owner only.** Tool testing requires the `tools:test` scope, which is restricted to admin and owner roles.
{% endhint %}

```mermaid
%%{init: {"flowchart":{"useMaxWidth":true,"nodeSpacing":20,"rankSpacing":30},"theme":"base","themeVariables":{"fontFamily":"Inter, sans-serif","fontSize":"16px","background":"#FAF8F6","primaryColor":"#F1EAE7","primaryTextColor":"#1A1817","primaryBorderColor":"#D7D2D0","secondaryColor":"#FDFCFB","tertiaryColor":"#F6F2F0","lineColor":"#575452","textColor":"#3D3937","clusterBkg":"#FDFCFB","clusterBorder":"#E8E2DF","edgeLabelBackground":"#FAF8F6","actorBkg":"#F1EAE7","actorTextColor":"#1A1817","actorBorder":"#D7D2D0","actorLineColor":"#575452","signalColor":"#575452","signalTextColor":"#3D3937","labelBoxBkgColor":"#F1EAE7","labelBoxBorderColor":"#D7D2D0","labelTextColor":"#3D3937","loopTextColor":"#3D3937","noteBkgColor":"#F6F2F0","noteBorderColor":"#D7D2D0","noteTextColor":"#3D3937","activationBkgColor":"#F1EAE7","activationBorderColor":"#D7D2D0","altSectionBkgColor":"#FAF8F6","altSectionColor":"#3D3937"},"fontFamily":"Inter, sans-serif"}}%%
flowchart LR
    R[Resolve tools<br/>for service] --> S[Select tool &<br/>provide inputs]
    S --> E[Execute tool<br/>source=tool_test]
    E -->|dry_run=true| D[Simulate writes<br/>where supported]
    E -->|dry_run=false| W[Execute with<br/>test source]
    D --> V[Inspect result<br/>+ sub-tool logs]
    W --> V

    style R fill:#FDFCFB,stroke:#D7D2D0,color:#3D3937,stroke-width:1px
    style S fill:#FDFCFB,stroke:#D7D2D0,color:#3D3937,stroke-width:1px
    style E fill:#FDFCFB,stroke:#D7D2D0,color:#3D3937,stroke-width:1px
    style D fill:#FDFCFB,stroke:#D7D2D0,color:#3D3937,stroke-width:1px
    style W fill:#FDFCFB,stroke:#D7D2D0,color:#3D3937,stroke-width:1px
    style V fill:#FDFCFB,stroke:#D7D2D0,color:#3D3937,stroke-width:1px
```

## Test-Mode Behavior

Tool testing changes the execution context, but it is not a universal sandbox. A non-dry-run test can persist data, and not every handler applies `dry_run` in the same way. Use test records and non-production credentials for any operation that could affect an external system.

* **Source tagging**: supported writes are tagged `source="tool_test"`. Platform pipelines can use that provenance to exclude test data from production processing.
* **Persistent tests**: with `dry_run=false`, write tools can create test-tagged records.
* **Dry runs**: world write tools are simulated when `dry_run=true` and never reach the workspace.
* **Session binding**: world tools are registered the way a live session registers them. The request `entity_id` is the session's bound patient and starts in its write scope. `input_params` passes through the same allowlist as a live call, so a patient ID placed there is dropped. There is no caller to verify, so `world_confirm_patient_identity` answers that no record matched.
* **Surface tools**: surface tools do not run from this endpoint, as in other test and simulation sessions.

## Resolve Available Tools

Retrieve the full list of tools available for a given service, including their input schemas, types, tiers, and write classification.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/tools/resolve" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Execute a Tool

Execute a single tool in isolation with custom input parameters.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/tools/execute" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

{% hint style="info" %}
**World tools only.** This endpoint executes `world_tool` tools exclusively, named by their catalog ids (`world_*`) as the resolve operation returns them; a bare handler name returns an unknown-tool error. The skill, integration, platform function (`fn_*`), and workspace data query (`wsq_*`) tool families use the dedicated operations below. Passing a non-`world_tool` type returns a validation error pointing at the appropriate operation.
{% endhint %}

## Test a Skill

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/skills/{skill\_id}/test" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Test an Integration Endpoint

Integration endpoints are addressed by integration and endpoint ID, not name. The response reports the call's `outcome` and `wrote`, and `over_text_budget` says whether the call took as long as a text turn waits on one; see [Test an Endpoint](/developer-guide/platform-api/integrations.md#test-an-endpoint). The Console's Tool Tester shows the same `outcome` as **Succeeded**, **Failed**, or **May have been written**, and asks before it sends a write again after an unknown outcome.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/integrations/{integration\_id}/endpoints/{endpoint\_id}/test" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Invoke a Platform Function

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/functions/{function\_name}/invoke" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Test a Platform Function

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/functions/{function\_name}/test" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Invoke a Workspace Data Query

Workspace data queries are addressed by query ID, not name. See [Workspace Data Queries](/developer-guide/platform-api/functions/workspace-data-queries.md) for deployment and runtime guidance.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/data\_queries/{query\_id}/invoke" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

{% hint style="info" %}
**Rate limited.** Tool execute is subject to write rate limits. Use resolve to inspect tools before executing.
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/functions/tool-testing.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.