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

# Test a tool

> Call a tool with input and read its result or error.

`commits_by_author` counts the commits each author made since a git ref.

```yaml .graph/tools/commits_by_author.yaml theme={null}
version: 2
name: commits_by_author
description: How many commits each author made since a git ref.
kind: exec
command: bash
args:
- -ceuo
- pipefail
- |
  git shortlog -sn --no-merges "$1..HEAD" </dev/null \
    | jq -Rs '[split("\n")[] | select(length > 0)
        | capture("^\\s*(?<commits>[0-9]+)\\t(?<author>.+)$")
        | {author, commits: (.commits | tonumber)}]'
- commits_by_author
- '{{input.base}}'
output: json
read_only: true
input_schema:
  type: object
  required:
  - base
  properties:
    base:
      type: string
      description: The ref to start after, such as a release tag
```

## Call the tool

Pass the tool's name, as `graph tool list` prints it, and set its input with `--input`:

```bash theme={null}
graph tool test user__commits_by_author \
  --input base=v0.14.0
```

graph calls the tool and prints its result:

```json theme={null}
[
  {
    "author": "Tyler Davis",
    "commits": 32
  }
]
```

## Read an error

Give it a ref that doesn't exist, and add `--json` to see whether the call failed:

```bash theme={null}
graph tool test user__commits_by_author \
  --input base=v9.9.9 --json
```

`isError` is `true`, and `result` carries the command's exit status and stderr:

```json theme={null}
{
  "isError": true,
  "result": {
    "error": "'bash' exited with exit status: 128",
    "stderr": "fatal: ambiguous argument 'v9.9.9..HEAD': unknown revision or path not in the working tree.…",
    "stdout": "[]"
  },
  "tool": "user__commits_by_author"
}
```

The command still exits with code 0, so check `isError` in scripts.

## Related guides

> **[Create a tool in the workbench](/tools/guides/create-in-workbench)**
>
> Draft, test-run and save a tool with the tool drafter.

> **[Improve what graph knows about a tool](/tools/guides/tool-shapes)**
>
> Show drafters what a tool returns.

> **[Test an MCP server](/integrating/mcp/guides/test-an-mcp-server)**
>
> Check a server connects and lists its tools.


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