# Built-In Tools Capability

Built-in tools are pre-built agent tools that ship with the platform. They share a wire shape (`$resourceType: "tool"`, `type: "internal"`) and a fixed input/output schema per tool. Unlike process or Integration Service tools, built-in tools are self-contained at the agent level — no solution-level files, no `uip solution resources refresh`.

For process tools (RPA / agent / API / agentic), see [../process/process.md](../process/process.md). For Integration Service tools, see [../integration-service/integration-service.md](../integration-service/integration-service.md).

## When to Use

- Agent needs file content analysis at runtime → pair a `job-attachment` input field with `analyze-attachments`
- Agent needs a platform capability that ships pre-built and does not require deployment

## Critical Rules

1. **Built-in tools are not implicit.** Add them as `resources/{Name}/resource.json` with `type: "internal"` to make them callable. Without the resource file, the tool is unavailable.
2. **`properties.toolType` is the discriminator** — fixed per built-in, kebab-lowercase. Copy from the per-tool walkthrough; do not invent.
3. **No solution-level files.** Built-in tools need no `uip solution resources refresh`. Validate the agent and bundle.
4. **Input/output schemas are fixed.** Do not edit them. Each tool's walkthrough lists the canonical schema.
5. **Inline agents need the flow node too.** When the built-in tool is on an *inline* agent (embedded in a flow), authoring the `resource.json` is **not enough** — also wire a `uipath.agent.resource.tool.builtin.<toolType>` flow node to the autonomous node's `tool` handle. Fetch the node manifest with `uip maestro flow registry get` and hand the node + edge authoring to the `uipath-maestro-flow` skill (Critical Rule 16). Without the flow node the tool is never reachable at runtime. See [../inline-in-flow/inline-in-flow.md](../inline-in-flow/inline-in-flow.md).

## Resource Shape

```jsonc
{
  "$resourceType": "tool",
  "id": "<UUID>",
  "referenceKey": null,
  "name": "<DisplayName>",
  "type": "internal",
  "description": "<TOOL_DESCRIPTION>",
  "isEnabled": true,
  "inputSchema":  { /* fixed per tool */ },
  "outputSchema": { /* fixed per tool */ },
  "settings": {},
  "guardrail": { "policies": [] },
  "argumentProperties": {},
  "properties": {
    "toolType": "<kebab-lowercase-id>"
  }
}
```

| Field | Notes |
|---|---|
| `type` | Always `"internal"` for built-in tools |
| `properties.toolType` | Fixed discriminator (e.g. `"analyze-attachments"`) |
| `inputSchema` / `outputSchema` | Fixed per tool — copy from walkthrough |
| `referenceKey` | Always `null` (no Orchestrator binding) |
| `guardrail.policies` | Always `[]` — required for backward compatibility |
| `id` | Fresh UUID per resource — see [../../critical-rules/critical-rules.md](../../critical-rules/critical-rules.md) Anti-pattern 9 |

## Lifecycle

1. **Author** the agent-level `resources/{ToolName}/resource.json` with the canonical shape from the per-tool walkthrough.
2. **Refresh** with `uip agent refresh "<AGENT_NAME>" --output json` — regenerates `entry-points.json` and `bindings_v2.json`.
3. **Validate** with `uip agent validate "<AGENT_NAME>" --output json` (read-only check).
4. **Bundle and upload** the solution. No solution-resource refresh needed.

## Tool Registry

| Tool | `toolType` | Walkthrough |
|---|---|---|
| Analyze Files | `analyze-attachments` | [analyze-attachments.md](analyze-attachments.md) |
| Deep RAG | `deep-rag` | [deeprag/impl-json.md](deeprag/impl-json.md) |
| Batch Transform | `batch-transform` | [batch-transform/impl-json.md](batch-transform/impl-json.md) |

## Gotchas

- See [../../critical-rules/critical-rules.md](../../critical-rules/critical-rules.md) Critical Rules 17–20 and Anti-patterns 20–21 for the canonical rule list.
- Pairing with file inputs: a `job-attachment` field renders metadata only in `{{input.<field>}}`. The agent reads contents only by calling a file-handling built-in tool. See [../../agent-definition.md](../../agent-definition.md) § File Attachments.
- Runtime test path: built-in tools cannot be exercised end-to-end through the `uip` CLI. Test from Studio Web or via Orchestrator job invocation.

## References

- [analyze-attachments.md](analyze-attachments.md) — Analyze Files walkthrough
- [../../agent-definition.md](../../agent-definition.md) § File Attachments — `job-attachment` schema
- [../../critical-rules/critical-rules.md](../../critical-rules/critical-rules.md) — canonical rules