create-tool

name	create-tool
type	python
description	Generate a new tool. Python tools go to staging for review. Instruction tools (no code) are created and registered immediately.
schema_hint	{"name":"string (tool name, e.g. bluesky-instructions)","description":"string (one-line description)","requirements":"string (what it does, what APIs/libs/env vars/params/output)","tool_type":"string (optional): 'python' (default, staged) or 'instruction' (no code, immediate)"}

create-tool

Generate a new Cognitive Workbench tool. Supports two modes:

• python (default): LLM generates tool.py + Skill.md, written to src/tools-staging/{name}/ for review.
• instruction: No code generation. The requirements text becomes the Skill.md body. Written directly to src/tools/{name}/ and hot-registered immediately.

Input

• name: Tool name (used as directory and action type, e.g. bluesky-instructions)
• description: One-line description for the tool catalog
• requirements: For python tools: full specification. For instruction tools: the instructional content that becomes the tool output.
• tool_type: "python" (default) or "instruction"

Output

Success: summary with file paths. For python tools, includes promotion command.

Failure: reason (syntax error, LLM failure, name conflict).

Behavior

Python tools:

• Loads reference tools as examples for the LLM
• Generates tool.py and runs py_compile to catch syntax errors
• Writes to src/tools-staging/{name}/ for review
• To activate: review, mv to src/tools/, restart

Instruction tools:

• Writes Skill.md directly to src/tools/{name}/
• Hot-registers into running system (available immediately for next goal)
• No restart needed

Limits: Only one create-tool call allowed per planner session.

Common Workflows

Create an instruction tool from research results:

{"type":"create-tool","name":"bluesky-instructions","description":"Instructions for retrieving Bluesky engagement metrics via public API","requirements":"Use fetch-text to call https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile?actor={HANDLE} for profile metrics and app.bsky.feed.getAuthorFeed for post engagement. No auth required.","tool_type":"instruction","out":"$result"}

Generate a new Python tool:

{"type":"create-tool","name":"post-bluesky","description":"Post text to Bluesky social network","requirements":"Use atproto library. Read BLUESKY_HANDLE and BLUESKY_PASSWORD from env. Accept 'text' parameter with post content (max 300 chars). Return success/failure with post URI if successful.","out":"$result"}