tool.yml reference

Each tool folder has one tool.yml. The fields that apply depend on kind.

Fields

Field	Required	Kinds	What it does
spec	yes	all	glxymesh/tool@v1
name	yes	all	Must match the folder name. 1–64 characters of a-z, 0-9, -, not starting or ending with -.
kind	yes	all	http or function
description	yes	all	What the tool does and when to use it, 10–2,000 characters. The model reads this to decide whether to call it.
title	no	all	A display name for clients, up to 80 characters
read_only	no	all	true tells clients the tool changes nothing (readOnlyHint)
inputs	yes	all	The arguments. Can be {}.
output	no	all	How the model reads results
network	if it calls out	all	Hosts the tool may reach
secrets	if it uses keys	all	Keys and the hosts each may travel to
limits	no	all	Timeout and memory, overriding gx.yml defaults
tests	no	all	Run by gxmesh test and before every revision goes live
request, response	request	http	The request template and what to keep from the reply

For a complete example explained section by section, see Understand gx.yml and templates.

inputs

inputs:
  owner:  {type: string, description: "GitHub user or org, e.g. golang"}
  limit:  {type: integer, default: 20, min: 1, max: 100}
  state:  {type: string, enum: [open, closed], default: open}
  labels: {type: array, items: {type: string}, required: false}
  since:  {type: string, pattern: "^\\d{4}-\\d{2}-\\d{2}$", required: false}

Key	Meaning
type	string, integer, number, boolean, array or object
description	Shown to the model, up to 500 characters. Give an example value.
required	Default true, unless the input has a default
default	Used when the argument is missing
min, max	Bounds for numbers
min_length, max_length	Bounds for the length of strings
pattern	A regular expression a string must match
enum	The only allowed values, up to 100
items	The shape of each item in an array

Input names are a-z, 0-9 and _, starting with a letter, like target_id. When the API’s own field is camelCase, map it in the request: path: /targets/{target_id}, body: {targetId: "{target_id}"}. The platform turns inputs into the JSON Schema that clients receive, and checks every call against it before the tool runs. Up to 50 inputs.

output

output:
  format: toon   # toon · json · text
  as: issues     # the table's name

toon renders a list of rows as a compact TOON table, which costs the model far fewer tokens than JSON. json returns the result as JSON, and text as plain text. The default comes from gx.yml’s defaults.output.

network

network:
  allow: [api.github.com]

Up to 20 entries, with no scheme or port: a host name, covering its subdomains (api.github.com); a pattern where * stands for one label ("*.example.com", "ec2.*.amazonaws.com"); an IPv4 or IPv6 address; or a range (203.0.113.0/24). A person approves each new entry before it goes live; one inside an entry already live needs no new approval. A host written as {NAME} is an address kept in the project’s secrets. See Keys and network access.

network:
  connect: ["db.example.com:5432", "{PG_HOST}:5432"]

connect lists host:port pairs a function tool may open a TCP connection to, for databases and other services that aren’t HTTPS, up to 10. The host is a name (that one server), a pattern ("*.rds.amazonaws.com:5432"), an IP address ("[2001:db8::7]:5432" for IPv6), a range ("203.0.113.0/24:6379") or a vault host. A person approves each new one. See Connect to a database.

network:
  allow: [85.209.161.240]
  trust:
    85.209.161.240: "3F:9A:1C:D2:7E:40:B8:65:0D:E1:5A:93:C4:2F:78:B6:11:AE:0C:5D:F3:92:67:4B:E8:D0:1A:7C:39:B5:62:F4"

trust names the one HTTPS certificate accepted from a server whose certificate no public authority vouches for, such as a fresh Proxmox’s, by its SHA-256 fingerprint. Each host is one in allow, written out or a vault host, never a pattern or a range; up to 10. Only that exact certificate is accepted, whatever name it’s for, and a person approves each one. Not for server tools. See A server with its own certificate.

secrets

secrets:
  GITHUB_TOKEN:
    hosts: [api.github.com]
    header: "Authorization: Bearer {value}"
  WEATHER_KEY:
    hosts: [api.weatherapi.com]
    query: key

Key	Meaning
hosts	The only hosts the key may be sent to
header	A header added to requests to those hosts. {value} is replaced by the key.
query	The name of a query parameter to add instead, such as key
mode	pass-in for a key the code reads itself, such as a database password, with ctx.SecretValue / ctx.secretValue / ctx.secret_value. A person approves it before it goes live. Not for http tools.

Key names are capitals, digits and _, such as GITHUB_TOKEN; up to 20 per tool. Use header or query, not both. With neither, the key is used only where the code puts a placeholder. An http tool needs one of them.

limits

limits: {timeout: 30s, memory: 512MB}

timeout is 1 second to 15 minutes, and memory 128 MB to 10 GB. Each falls back to gx.yml’s defaults. See Memory and your bill.

tests

tests:
  - name: two issues
    input: {owner: golang, repo: go, limit: 2}
    expect: {rows: 2}
  - name: bad repo
    input: {owner: golang, repo: does-not-exist}
    expect: {error: true}
  - input: {owner: golang, repo: go, limit: 1}
    expect: {contains: "number"}

A test with no expect passes when the call doesn’t end in an error. Up to 50 tests per tool.

expect key	Passes when
rows	The result is a list of exactly this many rows
contains	The answer, as the model reads it, contains this text
error	true: the call ended with an error

request and response (http tools)

request:
  method: GET                     # GET · POST · PUT · PATCH · DELETE
  url: https://api.github.com/repos/{owner}/{repo}/issues
  query: {state: open, per_page: "{limit}"}
  headers: {Accept: application/vnd.github+json}
  body: {title: "{title}"}        # for POST, PUT, PATCH; sent as JSON
response:
  pick: "[].{number: number, title: title}"   # JMESPath

url starts with https://. {name} is replaced by the input of that name in the path, the query, headers and the body; inputs can’t change the host. response.pick is a JMESPath expression over the JSON the API returns.