tool-creation

Tool Creation for Matimo SDK

This skill teaches you how to properly create, configure, and validate tools for the Matimo SDK—a configuration-driven framework where tools are defined once in YAML and executed everywhere (factory pattern, decorators, LangChain).

Two audiences — know which one you are:

You are an Agent at runtime	You are an SDK developer
Creating tools dynamically via matimo_create_tool	Adding tools to the SDK codebase
Tools go to ./matimo-tools/{tool-name}/definition.yaml (configured by developer)	Tools go to packages/{provider}/tools/{tool-name}/definition.yaml
Validate with matimo_doctor (meta-tool)	Validate with pnpm validate-tools (CLI)
Approval needed: matimo_approve_tool → matimo_reload_tools	No approval flow — merged via git

If you are an agent using meta-tools, follow the "Agent at runtime" column throughout this skill.

Matimo Architecture Overview

Tool Execution Flow

Tool Definition (YAML)
         ↓
    ToolLoader (parse & validate)
         ↓
    ToolRegistry (in-memory store)
         ↓
MatimoInstance.execute(name, params)
         ↓
  Select Executor Based on execution.type
         ↓
CommandExecutor | HttpExecutor | FunctionExecutor
         ↓
  Validate output against output_schema
         ↓
    Return structured result

Key Concepts

• Tools are YAML-first: Define once in YAML, execute anywhere
• Always include requires_approval: true: Required by policy for all agent-created tools
• Default execution type is http: command and function types are blocked by policy by default — only use http unless the developer has explicitly enabled the others
• Parameter templating: Use {paramName} syntax for dynamic values
• Authentication: Provider-agnostic (API key, bearer, basic, OAuth2)
• Output validation: All responses validated against Zod schemas
• Error handling: Structured errors with retry/backoff policies