Improve what graph knows about a tool

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

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

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

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:

graph shape show user__recent_releases

Error: no cached shape for tool user__recent_releases

Call it once:

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:

graph shape show user__recent_releases

{
  "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:

.graph/tools/recent_releases.yaml

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:

graph tool show user__recent_releases

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

Test a tool

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

Filter and override a server's tools

Declare output shapes for an MCP server’s tools.

Draft a plan in the workbench

Draft a plan from the tools in your catalog.

Create a tool in the workbench

Draft, test-run and save a tool with the tool drafter.

Getting started

Agents

Plans

Tools

Packs

Integrating

Reference

Improve what graph knows about a tool

Record a shape by running the tool

Declare the output schema

Test a tool

Filter and override a server's tools

Draft a plan in the workbench

Create a tool in the workbench

​Record a shape by running the tool

​Declare the output schema

​Related guides

Test a tool

Filter and override a server's tools

Draft a plan in the workbench

Create a tool in the workbench

Record a shape by running the tool

Declare the output schema

Related guides