> ## Documentation Index
> Fetch the complete documentation index at: https://graph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool file

> One user tool, in `./.graph/tools/` or `~/.config/graph/tools/`, called as `user__<name>`. A file in a tools directory's `builtin/` subdirectory replaces the built-in tool it names instead.

| File type | Location |
| - | - |
| YAML | `./.graph/tools/<name>.yaml` (project) `~/.config/graph/tools/<name>.yaml` (global) `<tools dir>/builtin/<name>.yaml` (replaces a built-in tool) |

Unknown keys are a load error. For completion in your editor, start the file with `# yaml-language-server: $schema=https://raw.githubusercontent.com/tylerdavis/graph/main/docs/schemas/tool.schema.json`.

## Common fields

**version** `integer`

The file version the document is written in. Omitted means 1; `graph tool migrate` brings a file to the current version.

**name** `string` *required*

Letters, digits, `_` and `-`. The tool is called as `user__<name>`.

**description** `string` *required*

What the tool does and returns. Agents and the plan drafter read it when choosing tools.

**kind** `enum\<string\>` *required*

What the tool runs. Each kind takes its own fields, listed below.

Available options: `exec`, `prompt`, `reshape`, `decision`

**input\_schema** `object`

JSON Schema for the input, validated before the tool runs. Templates reference it as `{{input.<field>}}`.

**output\_schema** `object`

JSON Schema for the output. A `prompt` tool enforces it as structured output; for every kind it tells drafters what the tool returns.

**read\_only** `boolean`

Marks the tool as free of side effects. `reshape` and `decision` tools are read-only by default.

## Kinds

Each `kind` adds its own fields.

* [`exec`](/tools/reference/tool-file/exec): Runs a command.
* [`prompt`](/tools/reference/tool-file/prompt): One model call.
* [`reshape`](/tools/reference/tool-file/reshape): Builds a value in a new JSON shape from the input, with no process and no model call.
* [`decision`](/tools/reference/tool-file/decision): Asks a decision model typed questions about the same state, each answered independently.

```yaml Example theme={null}
version: 2
name: open_prs
description: Open pull requests in the current repository, newest first.
kind: exec
command: gh
args:
- pr
- list
- --state
- open
- --json
- number,title,author
- --limit
- '{{input.limit}}'
read_only: true
input_schema:
  type: object
  required:
  - limit
  properties:
    limit:
      type: integer
      description: Most pull requests to return
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.