Skip to content
Matimodocs

YAML Tool Specification

Complete guide to writing Matimo tools in YAML format.

Quick Reference

Section titled “Quick Reference”

See the detailed specification for complete documentation.

Quick tool template:

name: my_tool
description: Brief description
version: '1.0.0'


parameters:
  query:
    type: string
    description: What this parameter does
    required: true


execution:
  type: http
  method: GET
  url: 'https://api.example.com/search'
  query_params:
    q: '{query}'


output_schema:
  type: object
  properties:
    result:
      type: string

Key Sections

Section titled “Key Sections”
Section Purpose
name Unique tool identifier (snake_case, matching its directory)
description One-line description
version Semantic version (e.g., 1.0.0)
parameters Tool input parameters
execution How the tool runs (HTTP, command or function)
output_schema What the tool returns; max_response_size caps it
authentication OAuth2/API key config (optional)
requires_approval Ask a human before every call (optional; DELETE and command tools ask by default)
risk low / medium / high / critical (optional; required for function tools)
status draft / approved / deprecated (optional)
error_handling Retry settings (optional; accepted but not yet applied)

Full Specification

Section titled “Full Specification”

The complete YAML schema documentation is in TOOL_SPECIFICATION.md.

Topics covered:

  • Metadata (name, description, version)
  • Parameter types and constraints
  • Execution modes (HTTP, command, function)
  • Governance fields (approval, risk, status)
  • Authentication configuration
  • Output schema validation and response-size caps
  • Error handling settings
  • Examples for each type

Next Steps

Section titled “Next Steps”