# Tool Prompt Optimization

Optimize the description prompts an AI agent reads to learn its built-in tools (the...

- Repository: https://github.com/can1357/oh-my-pi (37428 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add can1357/oh-my-pi --skill tool-prompt-optimization -g -a claude-code -y`
Codex: `npx skills add can1357/oh-my-pi --skill tool-prompt-optimization -g -a codex -y`
Cursor: `npx skills add can1357/oh-my-pi --skill tool-prompt-optimization -g -a cursor -y`
Gemini CLI: `npx skills add can1357/oh-my-pi --skill tool-prompt-optimization -g -a gemini-cli -y`

## Description

Optimize the description prompts an AI agent reads to learn its built-in tools (the `.md` files under prompts/tools/). Two halves: (1) measure how much of a prompt is already inferable from the tool's JSON parameter schema + name, to prune redundancy with evidence; (2) house authoring rules for what belongs in a tool prompt vs what stays in code. Use when auditing, trimming, writing, or reviewing tool prompts, deciding what schema field descriptions already cover, or testing schema-vs-prompt overlap before deleting prompt lines.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Tool Prompt Optimization

Prompt/schema overlap: content reconstructible from `(name, JSON schema, blank outline)` is a *prune candidate*, never an automatic delete. Probe this overlap for evidence, not vibes: predict the prompt body from those inputs. Reliably recovered lines: candidates; no-model recovery: load-bearing, keep.

## Run probe

`scripts/probe.ts`: `@oh-my-pi/pi-ai` `completeSimple`; production-matching model/auth/provider behavior.

```bash
bun .omp/skills/tool-prompt-optimization/scripts/probe.ts \
  --schema <file|json> --template <file|text> --name <tool_name>
```

- Required: `--schema`, `--template`, file path or inline value.
- No `--model`: panel `fireworks/kimi-k2.7-code`, `anthropic/claude-opus-4-8`, `openai/gpt-5.5` × `--samples` (default 3); requires `FIREWORKS_API_KEY` / `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`.
- `--model p/id,p/id`: override panel. Tune: `--samples N`, `--max-tokens`, `--json`.
- Programmatic: `import { probe } from "./scripts/probe.ts"` → `{ prompt, results: [{ model, samples: [{ text, stopReason, usage, error }] }] }`.

### Builtin shortcut, preferred for this repo

`scripts/probe-builtin.ts` instantiates the live tool; gets exact `toolWireSchema`, `tool.description`, and derived outline:

```bash
bun .omp/skills/tool-prompt-optimization/scripts/probe-builtin.ts --tool <name> [--no-summary] [--show]
```

- `--show`: resolved schema, derived outline, real prompt; exits without API calls. Inspect before spending tokens.
- `--no-summary`: direct summary-line-blank ablation.
- `--samples` / `--model` / `--max-tokens` / `--json`: panel passthrough. Output ends with real prompt for in-place diff.
- Factory-map bypasses settings allowlist: gated `irc`, `github`, … resolve. Construction availability gate (e.g. missing `gh` CLI) → manual inputs.

## Inputs

**Schema:** wire schema the model sees, never hand-sketch. Arktype:

The rest: https://github.com/can1357/oh-my-pi/blob/HEAD/.omp/skills/tool-prompt-optimization/SKILL.md