emergent-tools

name	emergent-tools
version	2.0.0
description	Self-improving agent toolkit — forge runtime tools, adapt personality traits, manage skills dynamically, compose multi-step workflows, and self-evaluate performance with bounded autonomy.
author	Wunderland
namespace	wunderland
category	productivity
tags	["emergent","tools","forge","sandbox","dynamic","runtime","LLM-judge","self-improvement","personality","skills","workflow","self-evaluation"]
requires_secrets	[]
requires_tools	["forge_tool","adapt_personality","manage_skills","create_workflow","self_evaluate"]
metadata	{"agentos":{"emoji":"🔧"}}

Emergent Tools

You have access to the EmergentCapabilityEngine — a system that lets you create brand-new tools at runtime when no existing tool satisfies the user's request, and a suite of self-improvement tools that let you adapt your personality, manage your skills, compose workflows, and evaluate your own performance. These are powerful capabilities; use them wisely.

Self-Improvement Overview

The self-improvement system provides bounded autonomy: you can modify your own behavior within configurable limits. Four tools work together to form a self-improvement loop:

1. adapt_personality — Shift HEXACO personality traits (openness, conscientiousness, etc.) to better match user needs.
2. manage_skills — Enable, disable, and search for skills at runtime to expand or focus your capabilities.
3. create_workflow — Compose multi-step tool pipelines for repeated tasks.
4. self_evaluate — Score your own responses, identify weaknesses, and adjust parameters.

All modifications are bounded:

• Personality shifts are capped by a per-session delta budget (default: ±0.15 per trait).
• Skill changes are gated by an allowlist and optional human-in-the-loop approval for new categories.
• Workflows are limited to a configurable max step count (default: 10) with no recursion.
• Self-evaluations are capped per session (default: 10) to prevent excessive LLM calls.

Mutations decay over time via Ebbinghaus-style forgetting during consolidation cycles. Only reinforced adaptations persist long-term.

When to Forge vs. Use Existing Tools

Before forging a new tool, always check whether an existing tool can fulfill the request:

1. Search first — Use discover_capabilities to scan the tool registry. If a tool already exists that handles the task (even partially), prefer it.
2. Compose second — If two or more existing tools can be chained together to accomplish the goal, use the ComposableToolBuilder to wire them rather than creating something from scratch.
3. Forge last — Only forge a genuinely new tool when no existing tool or composition covers the need. Common forge-worthy scenarios:
   • A domain-specific data transformation not covered by general utilities
   • A custom API integration the user needs on the fly
   • A specialized validation or formatting pipeline
   • A one-off computation that would be awkward to express as a prompt

The Forging Process

When you decide to forge a tool, the pipeline works as follows:

1. Specification — You describe the tool's purpose, input schema, output schema, and expected behavior in natural language.
2. LLM generation — The EmergentCapabilityEngine uses an LLM to produce the tool implementation (TypeScript function body).
3. Sandboxed execution — The generated code runs in an isolated sandbox with no filesystem, network, or process access by default. The sandbox enforces strict resource limits (CPU time, memory, output size).
4. LLM-as-judge validation — A separate LLM call evaluates whether the tool's output matches the specification. The judge scores correctness, safety, and completeness.
5. Registry enrollment — If the tool passes validation, it is registered in the runtime tool registry with full metadata and an audit trail entry.

Using ForgeToolMetaTool

The forge_tool meta-tool is your interface to the EmergentCapabilityEngine. Invoke it with:

• name — A clear, snake_case identifier for the new tool (e.g., csv_to_markdown_table)
• description — What the tool does, written as if for another agent reading a tool list
• input_schema — JSON Schema describing the expected input
• output_schema — JSON Schema describing the expected output
• examples — At least one input/output example pair to guide generation and validation
• constraints — Optional safety constraints (e.g., "must not make network calls", "output must be valid JSON")

The more precise your specification, the higher the first-pass success rate.

adapt_personality

The adapt_personality tool lets you shift HEXACO personality dimensions at runtime. Use it when you observe a mismatch between your current behavioral tendencies and what the user needs.

When to adjust:

• User feedback suggests you're too formal/casual, too verbose/terse, too cautious/bold.
• A pattern of user corrections indicates a trait mismatch (e.g., repeatedly asking for more creative responses suggests increasing openness).
• Self-evaluation identifies a personality-related weakness.

How it works:

• Provide the trait name (one of the HEXACO dimensions), a signed delta, and a reasoning string explaining why.
• The delta is clamped to the per-session budget (default ±0.15) and the final value to [0, 1].
• Every mutation is recorded in the PersonalityMutationStore with an audit trail.
• Mutations start at strength 1.0 and decay by the configured rate (default 0.05) each consolidation cycle.
• Unreinforced mutations fade to zero over ~18 cycles; reinforced mutations (repeated similar adjustments) maintain effective strength.

Always provide reasoning. The reasoning is persisted and auditable. Vague reasoning like "seems right" is unacceptable; be specific about what user signal drove the change.

manage_skills

The manage_skills tool lets you enable, disable, and search for skills at runtime.

Actions:

• search — Find skills by keyword or description. Always search before enabling to find the best match.
• enable — Load a skill by ID. The skill becomes active for the current self-improvement session, and its prompt guidance is carried into later turns for that session when the host runtime supports it.
• disable — Unload a previously loaded skill. Locked skills (core skills) cannot be disabled. Disabling also removes the skill from the current session's active list, later session prompt guidance, and later capability-discovery skill guidance for that session.
• list — List all currently active skills.

Allowlist patterns:

• ['*'] — All skills are permitted (default). Use with caution in production.
• ['category:productivity', 'category:search'] — Only skills in the listed categories are permitted.
• ['com.framers.skill.web-search', 'com.framers.skill.calculator'] — Only the exact skill IDs listed are permitted.

Category gating: When requireApprovalForNewCategories is enabled (default: true), enabling a skill from a category not already represented among active skills returns a requires_approval status. This prevents the agent from silently expanding into unrelated capability areas without human consent.

Workflow: Search → review results → enable the best match. If the skill is in a new category, the user will be prompted for approval before it activates.

create_workflow

The create_workflow tool lets you compose multi-step tool pipelines and execute them as a unit.

Reference resolution: Steps can reference data from earlier in the pipeline:

• $input — The workflow's original input argument.
• $prev — The output of the immediately preceding step.
• $steps[N] — The output of the Nth step (zero-indexed).

Example workflow:

{
  "action": "create",
  "name": "research_and_summarize",
  "steps": [
    { "tool": "web_search", "args": { "query": "$input.topic" } },
    { "tool": "extract_text", "args": { "url": "$prev.results[0].url" } },
    { "tool": "summarize", "args": { "text": "$prev.content", "maxLength": 200 } }
  ]
}

Constraints:

• Maximum steps per workflow: configurable (default 10).
• Only tools from the allowedTools list may be used. Default is ['*'] (all tools).
• create_workflow itself is always excluded from workflow steps to prevent recursion.
• Each step execution has a 30-second timeout.

Actions:

• create — Define a new named workflow.
• run — Execute a previously created workflow with input.
• list — List all workflows created in this session.

self_evaluate

The self_evaluate tool lets you score your own responses and adjust operational parameters.

When to self-evaluate:

• After a complex multi-turn interaction to assess overall quality.
• When user feedback (explicit or implicit) suggests dissatisfaction.
• Periodically (every N turns) as a quality checkpoint.

Evaluation criteria: The tool scores responses across four dimensions: relevance, clarity, accuracy, and helpfulness.

Auto-adjustment: When autoAdjust is enabled (default: true), the evaluation model may suggest parameter changes that are then applied automatically within the current session:

• temperature — Adjust LLM sampling temperature for more/less creative responses on later turns in the same AgentOS session.
• verbosity — Shift response length preference; the preference is carried into later prompt construction for the same session.
• personality — Delegate trait adjustments to adapt_personality, either by allowing explicit trait names or by using param: 'personality' with { trait, delta }.

Adjustable parameters are configured via adjustableParams (default: ['temperature', 'verbosity', 'personality']). Only listed parameters can be modified. Evaluation uses the runtime's cheapest detected text model unless evaluationModel is set explicitly.

Session cap: Maximum evaluations per session is configurable (default: 10) to prevent excessive self-reflection loops.

Self-Improvement Workflow

The full self-improvement loop combines all four tools:

1. Evaluate — Use self_evaluate to score recent performance. Identify specific weaknesses (e.g., "responses are too terse for this user", "missing domain knowledge for finance questions").

2. Adjust personality — If the weakness maps to a personality trait, use adapt_personality to shift it. For example, if responses are too terse, increase the verbosity-related trait with clear reasoning.

3. Manage skills — If the weakness maps to missing capabilities, use manage_skills to search for and enable relevant skills. For example, if finance questions are weak, search for and enable a finance-knowledge skill.

4. Create workflows — For tasks that recur with a consistent pattern, use create_workflow to codify the multi-step process. This saves re-planning on every invocation.

5. Re-evaluate — After adjustments, use self_evaluate again to verify improvement. If scores improved, the adjustments are reinforced. If not, consider reverting or trying a different approach.

This loop is not meant to run on every turn. Use it when you notice a pattern of suboptimal performance, not as a reflexive response to every interaction.

ComposableToolBuilder

For compositions of existing tools, use the ComposableToolBuilder pattern:

• pipeline(tools[]) — Chain tools sequentially, piping each output as the next input
• parallel(tools[]) — Run tools concurrently and merge their outputs
• conditional(predicate, ifTool, elseTool) — Branch based on a runtime condition
• transform(tool, mapFn) — Wrap a tool with an output transformation

Composed tools are registered just like forged tools, with full provenance tracking showing which base tools were combined.

EmergentJudge Quality Thresholds

The LLM-as-judge system uses three thresholds:

• Correctness (>= 0.8) — Does the output match the specification and examples?
• Safety (>= 0.9) — Does the tool avoid side effects, data leaks, or dangerous operations?
• Completeness (>= 0.7) — Does the tool handle edge cases and produce well-structured output?

If any threshold is not met, the forge attempt fails with a detailed explanation. You can revise the specification and retry. Typically, adding more examples or tightening constraints resolves most failures.

Audit Trail

Every forged tool carries an audit record containing:

• The original specification
• The generated source code (hash-pinned)
• Judge scores and rationale
• Timestamp and session context
• Parent tool references (for compositions)

This trail is immutable. If a user asks "how was this tool made?", you can retrieve and explain its provenance.

Personality mutations are also fully auditable: every adapt_personality call records the trait, delta, reasoning, baseline value, and mutated value with timestamps.

Best Practices

1. Start with examples — Providing 2-3 input/output examples dramatically improves forge quality.
2. Keep tools focused — Forge small, single-purpose tools rather than monolithic ones. Compose them later if needed.
3. Set constraints explicitly — If the tool must not access the network or must produce valid JSON, state it in constraints.
4. Validate before relying — After forging, test the tool with a known input before using it in a critical workflow.
5. Reuse forged tools — Forged tools persist in the session registry. Check before forging a duplicate.
6. Name descriptively — Good names make forged tools discoverable by other agents and future sessions.
7. Monitor judge feedback — If the judge rejects a tool, read the rationale carefully. It usually pinpoints exactly what to fix.
8. Prefer composition — A pipeline of three proven tools is more reliable than one complex forged tool.
9. Self-improve deliberately — Use self-evaluation to identify specific weaknesses before making adjustments, not as a reflexive action.
10. Provide reasoning always — Every personality mutation and skill change should have clear, specific reasoning tied to observable user signals.
11. Let decay work — Don't fight the decay model. If an adaptation is genuinely valuable, it will be reinforced naturally through repeated similar adjustments.