Meta-Tools Reference
Complete reference for all built-in Matimo meta-tools β the tools that manage other tools.
Overview
Meta-tools are built-in tools that live in packages/core/tools/ and provide tool lifecycle management capabilities. They allow agents (LangChain, MCP, SDK) to create, validate, approve, reload, and discover tools at runtime.
| Meta-Tool | Purpose | Requires Approval |
|---|---|---|
matimo_validate_tool |
Validate YAML against schema + policy rules | No |
matimo_create_tool |
Write a new tool definition to disk | Yes |
matimo_approve_tool |
Promote a draft tool to approved status | Yes |
matimo_reload_tools |
Hot-reload all tools into the live registry | Yes |
matimo_list_user_tools |
List tools in a directory with metadata | No |
matimo_get_tool_status |
Get status, risk level, and approval state of a tool | Yes |
matimo_create_skill |
Create a SKILL.md file with validated frontmatter | Yes |
matimo_list_skills |
List skills in a directory with metadata | No |
matimo_get_skill |
Read a skillβs full content by name | No |
matimo_validate_skill |
Validate a skill against the Agent Skills spec | No |
Note on
matimo_doctor: Examples, prompts, and older docs may refer tomatimo_doctor. This is an informal human-readable alias formatimo_validate_toolβ it is not a separate tool. The actual registered tool name you must use inmatimo.execute()ismatimo_validate_tool.
π‘ New to meta-tools? See When to Use Which Meta-Tool for decision guides and typical agent workflows before diving into individual tool references.
Common tags: All meta-tools are tagged with matimo and meta.
When to Use Which Meta-Tool
Decision Guide: Tool Lifecycle
I want to...
ββ Check if my YAML is safe before doing anything β matimo_validate_tool
ββ Write a new tool to disk β matimo_create_tool
ββ Promote a draft to production-ready β matimo_approve_tool
ββ Make newly created/approved tools available β matimo_reload_tools
ββ See what tools an agent has created β matimo_list_user_tools
ββ Check a specific tool's approval state β matimo_get_tool_status
Decision Guide: Skills Lifecycle
I want to...
ββ Discover what skills are available β matimo_list_skills
ββ Read the full content of a skill β matimo_get_skill
ββ Create a new SKILL.md at runtime β matimo_create_skill
ββ Check if a skill follows the Agent Skills spec β matimo_validate_skill
Use Cases by Meta-Tool
| Meta-Tool | When to Use | What Happens If You Skip It |
|---|---|---|
matimo_validate_tool |
Before matimo_create_tool β catch errors early without writing to disk |
Tool creation may fail mid-write with a less clear error |
matimo_create_tool |
Agent proposes a new capability (weather lookup, data fetch) | Tool never exists; agent canβt use the new capability |
matimo_approve_tool |
After creation β promote draft to usable state | Tool stays in draft status; matimo_reload_tools wonβt load it |
matimo_reload_tools |
After create+approve β make new tools available without restart | Agent canβt call the new tool until the process is restarted |
matimo_list_user_tools |
Agent wants to audit what it has created this session | Agent re-creates duplicates, wastes tool slots |
matimo_get_tool_status |
Before using a tool the agent created β verify itβs approved | Agent calls a draft tool and hits an approval gate error |
matimo_list_skills |
At session start or when agent needs domain knowledge | Agent misses available expertise, gives generic responses |
matimo_get_skill |
When agent needs specific domain knowledge for a task | Agent works without guidelines, prone to API misuse |
matimo_create_skill |
Team wants to package reusable agent expertise | Knowledge scattered in system prompts, not reusable |
matimo_validate_skill |
After creating a skill β verify spec compliance | Skill may fail to load or have invalid frontmatter silently |
Typical Agent Workflows
Workflow A β Agent creates and uses a new tool (full lifecycle)
1. matimo_validate_tool β Check YAML is safe (no approval needed)
2. matimo_create_tool β Write draft to disk (needs human β
)
3. matimo_approve_tool β Promote to approved (needs human β
)
4. matimo_reload_tools β Load into live registry (needs human β
)
5. matimo.execute(name) β Use the tool
Workflow B β Agent discovers and applies skills
1. matimo_list_skills β See available skills (free β no approval)
2. matimo_get_skill β Load the relevant one (free β no approval)
3. Agent applies guidelines from skill content in its response
Workflow C β Agent audits what it built
1. matimo_list_user_tools β List all tools created this session
2. matimo_get_tool_status β Check approval state for each tool
3. matimo_reload_tools β Ensure approved tools are live
matimo_validate_tool
Alias: Also informally called
matimo_doctorin examples and prompts. The registered tool name is alwaysmatimo_validate_tool.
Validate a tool definition YAML string against the Matimo schema and policy rules. Returns schema errors, policy violations, and risk classification.
Does not require approval β safe for agents to call freely.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
yaml_content |
string | Yes | The YAML content of the tool definition to validate |
Response
{
valid: boolean; // true if tool passes all checks
schemaErrors: string[]; // Zod schema validation errors
policyViolations: Array<{
rule: string; // e.g., 'no-command-execution'
severity: string; // 'critical' | 'high' | 'medium' | 'low'
message: string; // Human-readable explanation
}>;
riskLevel: string; // 'low' | 'medium' | 'high' | 'critical'
}
Example
const result = await matimo.execute('matimo_validate_tool', {
yaml_content: `
name: my_api_tool
version: '1.0.0'
description: Fetch data from an API
parameters:
query:
type: string
required: true
execution:
type: http
method: GET
url: 'https://api.example.com/search?q={query}'
`,
});
// {
// valid: true,
// schemaErrors: [],
// policyViolations: [], // medium: force-approval, force-draft-status (non-blocking)
// riskLevel: 'low'
// }
What It Checks
- YAML syntax β can the content be parsed?
- Schema validation β does it match the
ToolDefinitionZod schema? (name, version, description, execution, parameters) - Content rules β runs all 9 content validator rules (see POLICY_AND_LIFECYCLE.md)
- Risk classification β assigns risk level based on execution type and HTTP method
Error Cases
| Scenario | valid |
Response |
|---|---|---|
| Invalid YAML syntax | false |
schemaErrors: ["YAML parse error: ..."] |
| Missing required fields | false |
schemaErrors: ["Schema validation failed: ..."] |
| Command tool (blocked by policy) | false |
policyViolations: [{ rule: "no-command-execution", severity: "critical" }] |
| SSRF attempt | false |
policyViolations: [{ rule: "no-ssrf", severity: "critical" }] |
| Valid HTTP GET tool | true |
riskLevel: "low" |
matimo_create_tool
Create a new tool definition on disk. Validates the YAML, forces draft status and requires_approval: true, and writes the tool to the target directory.
Requires approval β human must confirm before tool is written to disk.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string | Yes | β | Name for the new tool (snake_case) |
yaml_content |
string | Yes | β | The YAML content of the tool definition |
target_dir |
string | No | ./matimo-tools |
Directory to create the tool in |
proposed_by |
string | No | β | Identifier of who proposed this tool |
justification |
string | No | β | Reason for creating this tool |
Response
// Success
{
success: true,
path: './agent-tools/weather/definition.yaml',
riskLevel: 'low',
status: 'draft',
message: 'Tool created as draft. Use matimo_approve_tool to promote.'
}
// Failure
{
success: false,
message: 'Tool failed policy validation',
errors: ['[critical] no-command-execution: Command-type tools are not allowed']
}
Example
const result = await matimo.execute('matimo_create_tool', {
name: 'city_lookup',
target_dir: './agent-tools',
proposed_by: 'agent-1',
justification: 'User requested city information lookup',
yaml_content: `
name: city_lookup
version: '1.0.0'
description: Look up user information including city and address details
parameters:
id:
type: string
required: true
description: User ID to look up (1-10)
execution:
type: http
method: GET
url: 'https://jsonplaceholder.typicode.com/users/{id}'
`,
});
Safety Enforcement
The following fields are always forced regardless of what the YAML contains:
| Field | Forced Value | Why |
|---|---|---|
name |
params.name |
Prevents name mismatch |
requires_approval |
true |
Agent-created tools must be approved |
status |
'draft' |
Agent-created tools start as draft |
Auto-Approval for Low-Risk GET Tools
matimo_create_tool classifies risk at creation time. HTTP GET tools targeting approved domains are classified as low risk and receive approvalState: 'auto-approved' immediately β they still start as status: 'draft' and must go through matimo_approve_tool, but the human approval step produces an immediate approval rather than a pending review. All other tools start as approvalState: 'pending'.
| Execution Type | Method | riskLevel |
approvalState after create |
|---|---|---|---|
http |
GET | low |
auto-approved |
http |
POST/PUT/DELETE | medium |
pending |
http with auth headers |
any | high |
pending |
command / function |
β | blocked by policy | β |
Name Validation
The tool name is sanitized to prevent security issues:
| Check | Blocked Pattern | Example |
|---|---|---|
| Path traversal | ../, ..\\ |
../../etc/passwd |
| Backslash | \ |
tools\backdoor |
| Control characters | \x00-\x1f |
Null bytes, newlines |
| Reserved namespace | matimo_* |
matimo_backdoor |
| Empty/whitespace | "", " " |
Blank names |
Internal Flow
- Sanitize name (reject invalid patterns)
- Parse YAML (reject syntax errors)
- Force
name,requires_approval: true,status: 'draft' - Validate against
ToolDefinitionZod schema - Run content validator (9 rules)
- Reject if any
criticalorhighseverity violations - Classify risk level
- Create directory
{target_dir}/{name}/ - Write
definition.yaml(with optional proposer/justification comments)
Output on Disk
agent-tools/
city_lookup/
definition.yaml β Created by matimo_create_tool
The written YAML will include the forced safety fields:
# Proposed by: agent-1
# Justification: User requested city information lookup
name: city_lookup
version: '1.0.0'
description: Look up user information including city and address details
requires_approval: true
status: draft
parameters:
id:
type: string
required: true
description: User ID to look up (1-10)
execution:
type: http
method: GET
url: 'https://jsonplaceholder.typicode.com/users/{id}'
matimo_approve_tool
Approve a draft tool for production use. Re-validates the tool, signs with HMAC, and updates the approval manifest.
Requires approval β human must confirm before tool is promoted.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string | Yes | β | Name of the tool to approve |
tool_dir |
string | No | ./matimo-tools |
Directory containing the tool |
Response
// Success
{
success: true,
name: 'city_lookup',
hash: 'sha256:a1b2c3d4e5f6...',
approvedAt: '2026-03-14T09:30:00.000Z',
message: 'Tool approved. Effective after reload or immediately if auto-reload is active.'
}
// Failure
{
success: false,
message: 'Tool has policy violations that must be resolved before approval'
}
Example
const result = await matimo.execute('matimo_approve_tool', {
name: 'city_lookup',
tool_dir: './agent-tools',
});
Internal Flow
- Read
{tool_dir}/{name}/definition.yaml - Parse and validate against Zod schema
- Re-run content validator (prevents approve-after-modify attacks)
- Reject if any
criticalorhighviolations remain - Compute SHA-256 hash of the YAML content
- Create HMAC signature using
MATIMO_APPROVAL_SECRET(or random UUID) - Store approval in
.matimo-approvals.json - Update YAML:
status: draftβstatus: approved - Write updated YAML to disk
Approval Manifest File
Created at {tool_dir}/.matimo-approvals.json:
{
"city_lookup": {
"hash": "sha256:a1b2c3d4e5f6...",
"signature": "hmac-sha256:...",
"approvedAt": "2026-03-14T09:30:00.000Z",
"approvedBy": "system"
}
}
Tamper Detection
If the YAML is modified after approval:
- On next
matimo_approve_toolorreloadTools(), the hash is recomputed - New hash β stored hash β approval is invalid
- Tool must be re-approved
matimo_reload_tools
Hot-reload all tools from configured toolPaths. Clears the registry, re-reads YAML definitions from disk, re-validates untrusted tools against the active policy, and returns a summary.
Requires approval β human must confirm before registry is rebuilt.
Parameters
No parameters required. The tool uses the toolPaths and untrustedPaths configured during MatimoInstance.init().
Response
{
success: true,
loaded: 13, // Total tools now in registry
removed: 0, // Tools that were in registry but no longer on disk
revalidated: 1, // Untrusted tools that were re-checked against policy
rejected: [], // Tool names that failed policy and were not loaded
message: 'Reload complete. 13 tools loaded, 0 removed, 0 rejected.'
}
Example
// Via meta-tool (works from SDK, LangChain, and MCP)
const result = await matimo.execute('matimo_reload_tools', {});
// Or programmatically (SDK only)
const reloadResult = await matimo.reloadTools();
Why This Meta-Tool Exists
Without matimo_reload_tools, the createβapproveβreloadβuse lifecycle could only be completed from SDK code (matimo.reloadTools()). MCP clients and LangChain agents had no way to trigger a reload.
With this meta-tool:
| Interface | Reload Method |
|---|---|
| SDK | matimo.reloadTools() or matimo.execute('matimo_reload_tools', {}) |
| LangChain | Agent calls matimo_reload_tools as a tool |
| MCP | Client calls tools/call with name: "matimo_reload_tools" |
Internal Flow (Interception Pattern)
This tool uses a special interception pattern. Unlike other meta-tools that execute via the FunctionExecutor, matimo_reload_tools is intercepted directly in MatimoInstance.execute():
matimo.execute('matimo_reload_tools', {})
β
ββ Policy check (canExecute)
ββ Approval check (requires_approval: true)
β
βΌ Intercepted BEFORE executor routing
β
this.reloadTools() β Called directly on the instance
β
βΌ Returns ReloadResult formatted as tool response
Why interception? The FunctionExecutor doesnβt have a reference to the MatimoInstance, so it canβt call this.reloadTools(). The interception happens after all policy and approval checks, so security is fully enforced.
After Reload (LangChain)
After calling matimo_reload_tools, LangChain agents must rebind their tools:
// Reload registry
await matimo.execute('matimo_reload_tools', {});
// Rebind LangChain tools (registry changed)
const updatedTools = matimo.listTools() as ToolDefinition[];
const langchainTools = await convertToolsToLangChain(updatedTools, matimo);
llmWithTools = llm.bindTools(langchainTools);
After Reload (MCP)
MCP reload automatically sends a notifications/tools/list_changed notification to connected clients, prompting them to re-fetch the tool list.
matimo_get_tool_status
Get the current status, risk level, and approval state of a specific tool by name. Works for both draft and approved tools.
Requires approval β reads from the approval manifest (sensitive metadata).
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string | Yes | β | Name of the tool to check |
tool_dir |
string | No | ./matimo-tools |
Directory containing the tool |
Response
// Tool found
{
found: true,
name: 'weather_fetch',
status: 'approved', // 'draft' | 'approved'
riskLevel: 'low', // 'low' | 'medium' | 'high' | 'critical'
approvalState: 'approved', // 'pending' | 'auto-approved' | 'approved'
approvedAt: '2026-03-14T09:30:00.000Z',
approvedBy: 'system',
message: 'Tool "weather_fetch" is approved and ready for use.'
}
// Tool not found
{
found: false,
name: 'nonexistent',
message: 'Tool "nonexistent" not found at ./matimo-tools/nonexistent/definition.yaml'
}
Example
const result = await matimo.execute('matimo_get_tool_status', {
name: 'weather_fetch',
tool_dir: './agent-tools',
});
if (result.found) {
console.log(`Status: ${result.status}, Risk: ${result.riskLevel}`);
}
matimo_list_user_tools
List all user-created tools in a directory with risk classification, approval status, and metadata.
Does not require approval β safe for agents to call freely.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
tool_dir |
string | No | ./matimo-tools |
Directory to scan for tools |
include_drafts |
boolean | No | true |
Whether to include draft tools |
Response
{
tools: [
{
name: 'city_lookup',
description: 'Look up city information',
version: '1.0.0',
status: 'approved',
riskLevel: 'low',
tags: []
},
{
name: 'weather',
description: 'Get current weather',
version: '1.0.0',
status: 'draft',
riskLevel: 'low',
tags: ['weather']
}
],
total: 2
}
Example
// List all tools (including drafts)
const result = await matimo.execute('matimo_list_user_tools', {
tool_dir: './agent-tools',
});
// List only approved tools
const approvedOnly = await matimo.execute('matimo_list_user_tools', {
tool_dir: './agent-tools',
include_drafts: false,
});
Internal Flow
- Check if
tool_direxists (return empty if not) - Scan directory entries
- For each subdirectory, look for
definition.yaml - Parse YAML + validate against schema
- Classify risk level
- Filter by
include_draftsflag - Return tool summaries
Error Handling
- If a toolβs YAML is invalid, itβs skipped with a warning log (doesnβt fail the entire listing)
- If
tool_dirdoesnβt exist, returns{ tools: [], total: 0 }
matimo_create_skill
Create a new skill definition (SKILL.md) on disk. Validates YAML frontmatter and writes the file to the target directory.
Requires approval β human must confirm before skill is written.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string | Yes | β | Name for the new skill (alphanumeric, hyphens, underscores) |
content |
string | Yes | β | Markdown content with YAML frontmatter |
target_dir |
string | No | ./matimo-tools/skills |
Directory to create the skill in |
Response
// Success
{
success: true,
path: './matimo-tools/skills/my-skill/SKILL.md',
message: 'Skill created successfully.'
}
// Failure
{
success: false,
message: 'YAML frontmatter must include a "description" field'
}
Example
const result = await matimo.execute('matimo_create_skill', {
name: 'data-analysis',
content: `---
name: data-analysis
description: Analyze datasets using statistical methods
---
# Data Analysis Skill
This skill enables statistical analysis of tabular datasets.
## Capabilities
- Descriptive statistics (mean, median, mode, std deviation)
- Correlation analysis
- Trend detection
`,
});
Frontmatter Requirements
The content must start with YAML frontmatter (---) containing at least:
| Field | Required | Description |
|---|---|---|
name |
Yes | Skill name (must be in frontmatter) |
description |
Yes | What the skill does |
Name Validation
Same as matimo_create_tool:
- No path traversal (
../) - No backslashes
- No control characters
- No empty/whitespace-only names
Output on Disk
matimo-tools/
skills/
data-analysis/
SKILL.md β Created by matimo_create_skill
matimo_list_skills
List all skills (SKILL.md files) in a directory. Returns each skillβs name, description, and file path from its YAML frontmatter.
Does not require approval β read-only operation.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
skills_dir |
string | No | ./matimo-tools/skills |
Directory to scan for skills |
Response
{
skills: [
{
name: 'code-review',
description: 'Code review checklist and best practices',
path: './matimo-tools/skills/code-review/SKILL.md'
},
{
name: 'security-checklist',
description: 'Security vulnerability detection checklist',
path: './matimo-tools/skills/security-checklist/SKILL.md'
}
],
total: 2
}
Example
const result = await matimo.execute('matimo_list_skills', {
skills_dir: './my-skills',
});
// result.skills β array of { name, description, path }
// result.total β number of skills found
Behavior
- Check if
skills_direxists (return empty if not) - Scan directory entries
- For each subdirectory, look for
SKILL.md - Parse YAML frontmatter for
nameanddescription - Skip skills with missing frontmatter fields (warning logged)
- Return skill summaries
matimo_get_skill
Read the full content of a skill (SKILL.md) by name. Returns the skillβs frontmatter metadata and complete markdown content so the agent can use it as instructions or context.
Does not require approval β read-only operation.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string | Yes | β | Name of the skill (matches the skillβs directory name) |
skills_dir |
string | No | ./matimo-tools/skills |
Directory containing skills |
Response
// Success
{
success: true,
name: 'code-review',
description: 'Code review checklist and best practices',
content: '---\nname: code-review\ndescription: ...\n---\n\n# Code Review Checklist\n...',
path: './matimo-tools/skills/code-review/SKILL.md',
message: 'Skill retrieved successfully.'
}
// Failure
{
success: false,
message: 'Skill "nonexistent" not found at ./matimo-tools/skills/nonexistent/SKILL.md'
}
Example
const result = await matimo.execute('matimo_get_skill', {
name: 'code-review',
skills_dir: './my-skills',
});
if (result.success) {
// The agent can now read result.content and apply the skill's guidelines
console.log(result.content);
}
Name Validation
Spec-compliant name rules:
- Lowercase letters, numbers, and hyphens only
- 1β64 characters
- No leading/trailing hyphens
- No consecutive hyphens
- Must match the skillβs directory name
matimo_validate_skill
Validate an existing skill against the Agent Skills specification. Checks SKILL.md existence, frontmatter validity, name rules, and directory structure.
Does not require approval β read-only validation.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string | Yes | β | Name of the skill to validate |
skills_dir |
string | No | ./matimo-tools/skills |
Directory containing skills |
Response
// Valid skill
{
valid: true,
name: 'code-review',
issues: [],
structure: {
has_skill_md: true,
resources: { scripts: [], references: [], assets: [], other: [] }
},
message: 'Skill "code-review" is valid.'
}
// Invalid skill
{
valid: false,
name: 'Bad_Name',
issues: [
{ level: 'error', message: 'Name contains invalid characters...' },
{ level: 'error', message: 'Skill name "Bad_Name" does not match directory name...' }
],
structure: { has_skill_md: true, resources: { ... } },
message: 'Skill "Bad_Name" has 2 issue(s).'
}
Example
const result = await matimo.execute('matimo_validate_skill', {
name: 'code-review',
skills_dir: './my-skills',
});
if (result.valid) {
console.log('Skill is spec-compliant!');
} else {
console.log('Issues:', result.issues);
}
Usage Across Interfaces
All meta-tools work consistently across SDK, LangChain, and MCP:
SDK
const result = await matimo.execute('matimo_validate_tool', { yaml_content: '...' });
LangChain
The LLM decides which meta-tool to call based on the conversation:
User: "Create a weather lookup tool"
Agent β matimo_validate_tool (check YAML)
Agent β matimo_create_tool (write to disk)
Agent β matimo_approve_tool (promote status)
Agent β matimo_reload_tools (load into registry)
Agent β weather_lookup (use the new tool)
MCP
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "matimo_validate_tool",
"arguments": {
"yaml_content": "name: my_tool\n..."
}
}
}
For tools with requires_approval: true, MCP clients must include _matimo_approved: true:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "matimo_create_tool",
"arguments": {
"name": "my_tool",
"yaml_content": "...",
"_matimo_approved": true
}
}
}
File Locations
All meta-tools are located in packages/core/tools/:
packages/core/tools/
matimo_validate_tool/
definition.yaml
matimo_validate_tool.ts
matimo_create_tool/
definition.yaml
matimo_create_tool.ts
matimo_approve_tool/
definition.yaml
matimo_approve_tool.ts
matimo_reload_tools/
definition.yaml
matimo_reload_tools.ts
matimo_list_user_tools/
definition.yaml
matimo_list_user_tools.ts
matimo_create_skill/
definition.yaml
matimo_create_skill.ts
matimo_list_skills/
definition.yaml
matimo_list_skills.ts
matimo_get_skill/
definition.yaml
matimo_get_skill.ts
matimo_validate_skill/
definition.yaml
matimo_validate_skill.ts
shared/
skill-validation.ts
See Also
- Policy & Lifecycle Guide β Complete policy engine and lifecycle documentation
- Tool Specification β YAML tool definition format reference
- Adding Tools β How to add new tool providers
- Approval System β Approval handler configuration