# Overview

The ten tools in the Paradoc AI packages, with their inputs and outputs

Canonical URL: https://docs.paradoc.dev/ai-tools/

Every Paradoc AI [adapter](/ai-tools/adapters) exposes these ten tools. They come from [`@paradoc/ai-tools`](/ai-tools/api), so names, inputs, and outputs are the same in every adapter. Input and output fields are snake\_case. Artifact JSON and fill data keep their own field names.

| Tool                                               | Category   | Description                                                              |
| -------------------------------------------------- | ---------- | ------------------------------------------------------------------------ |
| [`get_registry`](/ai-tools/get-registry)           | Registry   | Discover the artifacts in a registry                                     |
| [`get_artifact`](/ai-tools/get-artifact)           | Registry   | Retrieve one artifact and its instructions from a registry               |
| [`inspect_artifact`](/ai-tools/inspect-artifact)   | Artifacts  | Return a bounded description of an artifact                              |
| [`validate_artifact`](/ai-tools/validate-artifact) | Artifacts  | Validate an artifact definition                                          |
| [`validate_input`](/ai-tools/validate-input)       | Filling    | Validate and normalize one value before it goes into a draft             |
| [`fill`](/ai-tools/fill)                           | Filling    | Start a form or checklist draft from seed data                           |
| [`get_fill_state`](/ai-tools/get-fill-state)       | Filling    | Report draft progress and the next target to fill                        |
| [`update_fill`](/ai-tools/update-fill)             | Filling    | Merge, clear, or reset values in a draft                                 |
| [`render`](/ai-tools/render)                       | Rendering  | Render a form, document, or checklist through one of its layers          |
| [`extract`](/ai-tools/extract)                     | Extraction | Read a filled PDF form back into form data, with a report for each field |

## Sources

All tools except `get_registry` and `get_artifact` work on an artifact that you identify with a source. The `source` field selects one of three modes:

| Mode                 | Fields                           | Resolution                                                                                                                                                                 |
| -------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source: "artifact"` | `artifact`, `base_url?`          | Artifact JSON passed inline. File-backed layers resolve against `base_url`.                                                                                                |
| `source: "url"`      | `url`                            | Fetches the artifact JSON. File-backed layers resolve against the URL's directory.                                                                                         |
| `source: "registry"` | `registry_url?`, `artifact_name` | Fetches `registry.json`, checks the artifact is listed, then fetches it. Without `registry_url`, uses `defaultRegistryUrl` from the [config](/ai-tools/api#configuration). |

```typescript
{ source: "artifact", artifact: { kind: "form", name: "my-form", /* ... */ } }
{ source: "url", url: "https://example.com/forms/my-form.json" }
{ source: "registry", registry_url: "https://public.paradoc.dev", artifact_name: "pet-addendum" }
```

## Errors

Tools return failures in the result instead of throwing. A failed call carries an `error` object, and tools that validate values also return an `errors` array of the same shape:

| Field       | Type                   | Description                                                                                          |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------- |
| `code`      | `string`               | Machine-readable code, such as `validation_error`, `unsupported_artifact`, or `missing_registry_url` |
| `message`   | `string`               | Human-readable message                                                                               |
| `path`      | `(string \| number)[]` | Optional path to the value that failed                                                               |
| `retryable` | `boolean`              | Optional hint that the call may succeed if retried                                                   |

## How the tools work together

[Build an intake agent](/ai/intake-agent) shows the tools in a conversation: find the form, check each answer, keep the draft, ask the next question, and render the result. [Read a filled PDF](/ai/read-a-filled-pdf) starts the draft from a PDF.

Pass `data` and `evaluation_context` from each `fill` or `update_fill` result into the next call, so the draft and its date context stay the same across turns.