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

# Improve what graph knows about a tool

> Record what a tool returns by running it, then declare its output schema in the tool file.

Drafters write templates like `{{releases.0.tagName}}` from what a tool returns. `recent_releases` doesn't say yet.

```yaml .graph/tools/recent_releases.yaml theme={null}
version: 2
name: recent_releases
description: The latest releases of a GitHub repository, newest first.
kind: exec
command: gh
args:
- release
- list
- --repo
- '{{input.repo}}'
- --json
- tagName,publishedAt
- --limit
- '3'
output: json
read_only: true
input_schema:
  type: object
  required:
  - repo
  properties:
    repo:
      type: string
      description: The repository as owner/name
```

## Record a shape by running the tool

graph records the shape of each successful result. Before the first call, there's nothing for `recent_releases`:

```bash theme={null}
graph shape show user__recent_releases
```

```text theme={null}
Error: no cached shape for tool user__recent_releases
```

Call it once:

```bash theme={null}
graph tool test user__recent_releases \
  --input repo=tylerdavis/graph
```

The shape is now cached, with a schema inferred from the result and an example:

```bash theme={null}
graph shape show user__recent_releases
```

```json theme={null}
{
  "example": [
    {
      "publishedAt": "2026-09-24T04:34:59Z",
      "tagName": "v0.15.0"
    },
    …
  ],
  "schema": {
    "items": {
      "properties": {
        "publishedAt": {
          "type": "string"
        },
        "tagName": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "type": "array"
  },
  "seen_count": 1,
  "tool": "user__recent_releases"
}
```

## Declare the output schema

A recorded shape only exists after a run, and it can't say what a field means. Add `output_schema` to the tool file:

```yaml .graph/tools/recent_releases.yaml theme={null}
output_schema:
  type: array
  items:
    type: object
    properties:
      tagName:
        type: string
        description: The release's tag
      publishedAt:
        type: string
        description: When it was published, ISO 8601
```

`graph tool show` now lists it, and drafters use it in place of the recorded shape:

```bash theme={null}
graph tool show user__recent_releases
```

```text theme={null}
user__recent_releases

The latest releases of a GitHub repository, newest first.

input schema:
…

output schema:
{
  "items": {
    "properties": {
      "publishedAt": {
        "description": "When it was published, ISO 8601",
        "type": "string"
      },
      "tagName": {
        "description": "The release's tag",
        "type": "string"
      }
    },
    "type": "object"
  },
  "type": "array"
}
source: ./.graph/tools/recent_releases.yaml
```

## Related guides

> **[Test a tool](/tools/guides/test-a-tool)**
>
> Call a tool with input and read its result or error.

> **[Filter and override a server's tools](/integrating/mcp/guides/filter-and-override-tools)**
>
> Declare output shapes for an MCP server's tools.

> **[Draft a plan in the workbench](/plans/guides/draft-in-workbench)**
>
> Draft a plan from the tools in your catalog.

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


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