> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/functions/tool-testing.md).

# Tool Testing

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": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%%
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:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:2px
    style S fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:2px
    style E fill:#F0DDD9,stroke:#AA412A,color:#100F0F,stroke-width:2px
    style D fill:#DDE3DB,stroke:#2c3827,color:#100F0F,stroke-width:2px
    style W fill:#DDE3DB,stroke:#2c3827,color:#100F0F,stroke-width:2px
    style V fill:#E8E2EB,stroke:#C5BACE,color:#100F0F,stroke-width:2px
```

## 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**: writer-backed world tools are simulated when `dry_run=true`. Surface handlers currently execute their normal test path, so do not assume that the flag prevents every write.
* **Surface delivery**: the platform blocks outbound delivery for surfaces created with the tool-test source.

## 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://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/tools/resolve" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Execute a Tool

Execute a single tool in isolation with custom input parameters.

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

{% hint style="info" %}
**World tools only.** This endpoint executes `world_tool` tools exclusively. 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://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/skills/{skill\_id}/test" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Test an Integration Endpoint

Integration endpoints are addressed by integration and endpoint ID, not name.

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

## Invoke a Platform Function

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

## Test a Platform Function

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/functions/{function\_name}/test" method="post" %}
<https://api.platform.amigo.ai/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://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/data\_queries/{query\_id}/invoke" method="post" %}
<https://api.platform.amigo.ai/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 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.amigo.ai/developer-guide/platform-api/functions/tool-testing.md?ask=<question>&goal=<endgoal>
```

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