# Discover and run Darcy REST tools

Source: https://govform.com/resources/documentation/article/33-15-api-darcy-tools
Topic: Govform API & MCP

Use the Builder REST API to discover the Darcy tools available to a library API key and invoke a tool using its advertised schema. Tool availability depends on the configured release and the key's permissions.

## Host and authentication

Use `https://app.govform.com` (or your private Builder host), with /builder/libraries/{libraryId}/api as the prefix. Send Authorization: GovformsApiKey <key-id>:<key-secret> or GovformsApiHmac. POST requests use JSON.

## Endpoints and permissions

Paths below follow the Builder prefix.

| Method and path | Permission | Behaviour |
| --- | --- | --- |
| `GET /darcy/tools/catalog` | apiDarcyToolRead or apiDarcyToolWrite | Discover tools permitted for this key. |
| `POST /darcy/tools/{toolName}` | apiDarcyToolRead or apiDarcyToolWrite, depending on the tool | Run a discovered tool. Mutating tools require apiDarcyToolWrite. |
| `POST /darcy/ask` | apiDarcyAsk | Ask a non-mutating question where supported. |
| `POST /darcy/agent` | apiDarcyAgent | Request a Darcy agent operation where supported. |

These routes use 1 API unit per successful call. Form-write or tool-write permission is additionally required for the agent to be allowed to mutate forms. A question request is always non-mutating.

## Discover tools before invoking them

GET /darcy/tools/catalog accepts mode=all (default), readonly or mutating. The returned tools array includes each tool's name, title, description, inputSchema and annotations where available. The catalogue is filtered by the key: use only names and inputs advertised by the connection.

Some tools require a service. Include formId in the input for those tools, using its Service ID or library-prefixed ID. Read the current service and relevant guidance before authoring a change.

POST /darcy/tools/{toolName} accepts either the tool input object directly or {"input": {...}}. For example, the wrapper for a tool requiring a form is:

```json
{"input": {"formId": "example-application"}}
```

Add every other property required by that tool's inputSchema. Optional X-On-Behalf-Of records an actor for changes. A successful mutating tool result can save a new Builder version; it does not automatically deploy it. The response is the tool's result object, so inspect success and its returned data rather than assuming one uniform payload for all tools.

## Optional question and agent operations

POST /darcy/ask and POST /darcy/agent forward their JSON payload to the configured Darcy capability. The wrapper sets the library, API-key identity and permitted mutation context; callers cannot grant themselves write access. Support and the detailed request/result contract depend on the configured capability. These endpoints can return 501 when that operation is unsupported or 503 when Darcy is unavailable. Discover direct guidance and authoring tools through the catalogue instead when question or agent operations are unavailable.

## Errors and limits

Unknown or unauthorised tool names return 404. Missing required service input and a tool result with success: false return 400. Invalid credentials, source-IP restrictions or insufficient permission return 403. Rate and quota limits return 429. Follow error.message and Retry-After when provided.

For an MCP client, see [Govform MCP capabilities](<https://govform.com/resources/documentation/article/33-14-mcp-capabilities>). An ordinary REST integration does not need an MCP client.

See [authentication headers](<https://govform.com/resources/documentation/article/33-govforms-api#authentication-headers>) for raw-key and HMAC formats.

## Find screens and settings in Builder

Use the discovered `findBuilderScreen` tool through `POST /darcy/tools/findBuilderScreen` to find where a screen or setting is in Builder and how to reach it, for example `{"input": {"query": "data retention"}}`. When the result’s `matchQuality` is `weak`, request one area’s directory with `{"input": {"contents": true, "area": "Service"}}` and then the chosen `screenId`. It needs no `formId` (supply one to complete service links), uses the existing tool-read permission and reads no library or service data. Results come from the Builder release handling the request. See [Govform MCP capabilities](<https://govform.com/resources/documentation/article/33-14-mcp-capabilities>).

## Test saved service journeys

Use the discovered `testJourney` tool through `POST /darcy/tools/testJourney` to describe inputs and run disposable scenarios on the latest saved service. It uses the existing tool-read or tool-write permission and requires `formId`. See [journey test examples, assertions and limits](<https://govform.com/resources/documentation/article/33-16-api-journey-tests>). Unsaved Darcy drafts, existing respondent journeys and real external delivery are outside this API check.
