User-defined tools

Wrap commands, queries, and prompts as first-class tools

Drop a YAML file in ./.graph/tools/ (or ~/.config/graph/tools/ for tools you want everywhere) and it becomes user__<name> — callable by the agent, referenced in plan steps or from the CLI.

exec — wrap any command

name: git_log
description: Recent git commits for a local repository path.
kind: exec
command: git
args:
  - "-C"
  - "{{input.repo}}"
  - "log"
  - "-n"
  - "{{input.count}}"
  - "--pretty=format:{\"hash\":\"%h\",\"subject\":\"%s\"},"
output: text                # or json: stdout parsed as JSON
read_only: true
input_schema:
  type: object
  required: [repo]
  properties:
    repo: { type: string, description: Absolute path to a git repository }
    count: { type: integer }

Field	Required	Notes
command	yes	the executable
args	no	templated from the input ({{input.*}} only — step references don’t exist inside a tool)
env	no	extra environment; values support ${VAR} from the parent environment
cwd	no	working directory for the process
timeout_secs	no	kill-after budget; default 60
output	no	text (default: stdout wrapped as {"text": …}) or json (stdout parsed as JSON)

Unparseable json output, non-zero exit (with stderr captured), and timeouts all return as structured tool errors.

Exec tools are arbitrary code execution, by design — you author them, graph runs them. Treat the tools directory like you treat your shell profile.

prompt — an LLM call as a tool

name: summarize
description: Summarize any text into a gist and three keywords.
kind: prompt
prompt: |
  Summarize into a single-sentence gist and exactly three keywords:

  {{input.text}}
model: chat                  # any configured role: standard (chat, solver, …) or custom
output_schema:               # optional → enforced structured output
  type: object
  required: [gist, keywords]
  properties:
    gist: { type: string }
    keywords: { type: array, items: { type: string } }

With an output_schema, the result is validated JSON; without one, {"text": …}. Useful as a cheap sub-task inside plans — classify, extract, reword — with model controlling cost: any configured role — a standard one like chat (the default, with the usual fallback to default) or a custom one like nano. An unknown name fails the call with the configured names listed.

Shared behavior

• input_schema validates before dispatch — missing fields return actionable errors (in chat, the agent asks and retries).
• output_schema, when declared, feeds the planner’s shape knowledge just like an MCP output schema.
• Names must match [a-zA-Z0-9_-]+; templates referencing anything but {{input.*}} are load-time errors.
• Files are read strictly: a key the tool’s kind does not accept is a load error naming it (unknown field(s) \tmeout_secs` for a `exec` tool`), never ignored.
• version is the file version the document is written in; omitted means 1. graph tools migrate <path> brings a file to the current version.