Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Promptzilla run the full pipeline to optimize my customer-support system prompt"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Site: silverquill.amccutcheon.com
Five prompt-engineering skills and a durable optimization loop. Install the skills into your agent with one command, or run the whole pipeline from the terminal with a fresh process per stage.
Release status: Silverquill 2.0.0 is pending npm publication. There is no
silverquillpackage on npm yet; the last published release ispromptzilla@1.0.0, the old MCP server. Use the source or the local build until 2.0.0 ships.
Silverquill does not call a model API itself and stores no credentials. The worker you choose — OpenCode, Claude Code or Codex — already has its own authentication.
Until 2.0.0 is on npm, clone and build. The commands below run from the repository root.
git clone https://github.com/andymccutcheon/silverquill
cd silverquill && npm install && npm run build
node dist/cli.js install
node dist/cli.js run --request "Write a prompt for a meeting-notes summarizer"Once 2.0.0 ships, npx silverquill install and npx silverquill run do the same two things
without the clone.
install copies the five skills into the agent hosts it detects. run executes the full
Compose → Judge → Revise loop and writes the approved prompt to
./prompts/<slug>.md.
Related MCP server: SoloFlow
Requires Node.js 22.12 or newer.
node dist/cli.js installThe command detects the agent hosts on this machine and copies all five skills into each one it finds:
Host | Destination |
Claude Code |
|
OpenCode |
|
Shared agents |
|
If none are found it installs to Claude Code. Re-run the same command to update; the five
skill folders are replaced. Upgrading from the pre-rename release also removes the five
legacy folders (tasker, metapod, judge-dredd, brian-spillner, prompt-pipeline)
when they are present. Use --target, --dir or --dry-run for control:
npx silverquill install --target all
npx silverquill install --target claude,opencode
npx silverquill install --dir ./.claude/skills
npx silverquill install --dry-runThe installed skills are brief, compose, judge, revise and
loop. Supporting files for the manual pipeline (DRY-RUN.md, the Python
helpers) are installed with loop.
Full mode turns a rough request into a prompt, then scores and rewrites it until Judge returns STOP at 9 or higher:
npx silverquill run --request "Write a prompt for a meeting-notes summarizer that returns five bullets"Optimize-only mode starts from a prompt you already have:
npx silverquill run --prompt ./prompt.mdA trailing argument is shorthand for a Full request:
npx silverquill run "Write a prompt for a release-notes generator"The default worker is opencode. Choose another and pass a model when you want one:
npx silverquill run --prompt ./prompt.md --worker claude --model claude-sonnet-4-5
npx silverquill run --request "..." --worker codex --model gpt-5Useful flags:
Flag | Meaning |
| Constraints carried through every stage |
| Output directory (default |
| Override the exported filename |
| Print each stage's full output |
| Suppress stage progress |
| Per-stage timeout (default 900000) |
| Machine-readable result |
Exit codes: 0 approved, 2 paused for a decision, 3 capped or blocked with a
provisional candidate.
On STOP, the scored prompt is written to ./prompts/<slug>.md (or --out). The file is
the prompt itself — no frontmatter, no commentary, ready to paste.
If the run caps at four scoring rounds, blocks on invalid output, or pauses because the
score stopped improving, the best scored candidate is written to
./prompts/<slug>.provisional.md and clearly reported as not approved. A plateau pause is
resumable:
npx silverquill run --resume <run-id> --decision "Continue; resolve the count conflict first."Every run also keeps a full record under ~/.silverquill/runs/<run-id>/: the original
input, each stage file, retries, scorecards, provenance and run.json. Use --runs-dir
to relocate it.
Each stage runs in a separate process with only that stage's packet. That is real isolation, not an attestation.
Worker | Command | Notes |
|
| Reads the packet from stdin; captures the session ID |
|
| Reads the packet from stdin |
|
| Reads the packet from stdin |
| in-process | Deterministic; used by the test suite |
The worker must be installed and authenticated already. Silverquill never reads or stores provider keys.
An agent that cannot spawn a worker can still use the durable engine. start creates a
run and prints the first dispatch; the agent executes dispatch.instructions with
dispatch.input and submits the exact output.
npx silverquill start --request "Write a prompt for a meeting-notes summarizer" --json
npx silverquill status <run-id>
npx silverquill submit <run-id> --dispatch <dispatch-id> --output ./stage-output.md
npx silverquill pause <run-id> --reason "Need a user decision"
npx silverquill resume <run-id> --decision "Keep the current structure"
npx silverquill fix <run-id> --old "notes" --new "meeting notes"
npx silverquill export <run-id> --out ./promptsstatus --json includes the active dispatch, so the packet can be handed to a fresh
worker without reading run.json. fix accepts repeated --old/--new pairs or
--fixes FILE containing [{ "old": "...", "new": "..." }]. Fixes must be quoted
exactly in a Judge recommendation, and a fresh Judge confirms the diff before approval.
Skill | Job |
| Turn a rough task assignment into an execution-ready instruction |
| Turn a request into a System Prompt and a Task Prompt |
| Score a prompt on a locked 0–10 rubric; STOP at 9+ |
| Rewrite a prompt by applying every numbered recommendation |
| Orchestrate the three pipeline skills manually |
The installed files are the source of truth. The CLI pins each run to the exact skill text it started with, so editing a skill mid-run cannot change the current run.
Compose must return one System Prompt and one Task Prompt with all required headings. It never performs the requested task.
Judge returns section ratings with quoted evidence, one overall rating, a STOP or CONTINUE verdict, and numbered recommendations. STOP is valid only at 9 or higher; CONTINUE needs 3–5 recommendations.
Revise returns the complete rewrite between one BEGIN and one END BODY marker plus a checklist accounting for every recommendation. Judge re-scores the body without seeing the checklist.
A scoring round starts with Judge. Pass 1 counts toward the four-round cap.
An invalid stage gets one retry. A second invalid output blocks the run and preserves the best scored candidate as provisional.
A score that does not improve after two rewrites pauses for an explicit decision. It never invents one.
Exact fixes after STOP are explicit, all-or-nothing, and confirmed by a fresh Judge.
npm test # 66 unit, integration and CLI tests
npm run check # build, type-check, coverage, Python helper tests
npm run test:package # pack, install into a clean directory, run the pipeline
npm run test:live # real model through the real three-skill pipelinenpm test uses authored fixtures and does not spend model tokens. npm run test:live
runs Full mode against OpenCode and reports the score trajectory; it passes when the
pipeline reaches a terminal or decision state with a final or provisional prompt. A
blocked run — output that fails the stage contract twice — is a failure.
The live run proves the protocol, validation and state machine against real skill output. It does not prove that a particular prompt is good; Judge can legitimately cap at 8.
import { Catalog, Pipeline, executeRun, createWorker } from 'silverquill';
const pipeline = new Pipeline(await Catalog.load('./skills'), './runs');
const result = await executeRun({
pipeline,
worker: createWorker('claude', { model: 'claude-sonnet-4-5' }),
mode: 'optimize-only',
input: 'You summarize notes.',
outDir: './prompts',
});Pipeline exposes start, status, submit, pause, resume and applyFixes for
manual orchestration. Catalog discovers and validates skill folders.
The package publishes to npm as silverquill.
Bump version, run npm run check, then npm publish --access public, or trigger the
publish GitHub Actions workflow.
No API keys, no provider accounts, no remote service. Workers use their own auth.
Run directories are created with owner-only permissions; run files are mode 0600.
Stage input is capped at 200,000 characters; worker output at 4 MB; each stage defaults to a 15-minute timeout.
Symlinks, path traversal and artifact tampering are rejected.
Prompt text stays on disk until you remove it. Run directories can contain private material.
Version 1.x was Promptzilla, an MCP server. Version 2 is Silverquill, a CLI and a library.
Remove the promptzilla entry from your MCP client configuration.
Run npx silverquill install.
Use npx silverquill run ... or the installed skills directly.
Old runs live under ~/.promptzilla-mcp/runs; read one with
--runs-dir ~/.promptzilla-mcp/runs. New runs default to ~/.silverquill/runs.
The Cloudflare Worker, HTTP transport and MCP-specific tools, prompts and resources are gone. The durable pipeline engine and all five skills remain.
The implementation plan and acceptance criteria are in PLAN.md. Measured
verification results are in TEST-RESULTS.md.
Prepare Brian Spillner to rewrite a prompt using a numbered scorecard. Host executes the packet.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | ||
| scorecard | Yes | ||
| priorities | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and nothing here contradicts it ('prepare' is consistent with a read-only staging step). The description adds one genuinely useful behavioral fact: the tool produces a packet that the host, not this tool, executes. However it never describes what the packet contains or what the caller receives back.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler and the main action front-loaded. It is tight, though the second sentence is cryptic enough that its brevity costs more clarity than it saves.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotation detail about returns, the description is the only source for what happens after invocation, and it leaves the core mechanism ('Host executes the packet') unexplained. An agent cannot tell whether it gets a rewritten prompt, an instruction set, or a status back, which is a serious gap for a tool whose entire value is a staged rewrite.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across three string parameters, so the description must carry the load. It loosely maps 'prompt' (the text to rewrite) and hints that the scorecard is 'numbered', which is format info the schema lacks, but 'priorities' is never mentioned and no input constraints or expectations are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names an action ('Prepare ... to rewrite a prompt using a numbered scorecard') but 'Brian Spillner' is an unexplained persona and 'Host executes the packet' muddies whether this tool performs the rewrite or just stages it. It does not differentiate itself from siblings like prompt_pipeline or tasker, so an agent cannot confidently pick it over them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool, when not to, or which sibling (prompt_pipeline, tasker, metapod) is the alternative. 'Host executes the packet' hints at a two-stage flow but never tells the agent where this tool fits in it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load exact skill instructions and metadata for host execution.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds little beyond that — 'for host execution' hints at downstream use, but it does not disclose behavior for an unknown/invalid name, error modes, or the shape of the returned instructions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words. It is efficient, though the trailing phrase 'for host execution' is slightly opaque rather than informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only lookup with no output schema, the description covers the core action adequately and the annotations cover safety. It still omits the parameter's expected format and failure behavior, which are the main gaps an agent would hit in practice.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single 'name' parameter is never mentioned in the description. There is no guidance on whether it expects a skill name, slug, or path, or on case sensitivity — the agent must guess from the tool name alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Load exact skill instructions and metadata.' An agent can tell this retrieves a skill's content. However, it does not differentiate itself from the sibling tools list_skills and search_skills, which also operate on skills.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus list_skills or search_skills, no prerequisite (e.g., call search_skills first to obtain a valid name), and no mentioned alternatives or exclusions. Usage must be inferred entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prepare a fresh Judge Dredd evaluation. Returns skill instructions plus caller-supplied prompt data, not a computed score.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | ||
| priorities | No | ||
| fidelity_source | No | ||
| earlier_scorecards | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description nonetheless adds valuable behavioral context that the schema cannot convey: the return payload is skill instructions plus caller-supplied prompt data, not a computed score. It still omits what the caller is expected to do with that payload.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler, and the key negative clarification ('not a computed score') is front-loaded where an agent will read it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters at 0% schema coverage and no output schema, the definition should explain each input and the expected follow-up workflow. It resolves the return-value question but leaves three of four parameters entirely undocumented, which is not enough for an agent to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for four parameters, so the description must carry the explanation and it largely does not. Only the vague phrase 'caller-supplied prompt data' hints at the inputs; priorities, fidelity_source, and earlier_scorecards are never mentioned or explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Prepare') and resource ('Judge Dredd evaluation'), and adds the unusual clarification that it returns skill instructions plus prompt data rather than a score. That distinguishes it from a scoring/computation tool, but it does not differentiate it from any named sibling such as get_skill or prompt_pipeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'Prepare' and the phrase 'not a computed score' weakly imply this is a setup step rather than the evaluation itself, but there is no explicit when-to-use, no prerequisites, and no mention of alternatives among the skill/pipeline siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available prompt-engineering skills.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is fully covered structurally. The description adds nothing beyond that — no mention of result ordering, completeness limits, or pagination behavior for what is presumably a list endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler or redundancy. It is tightly sized for the operation, though it is arguably a touch too terse to carry the sibling-routing burden.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a trivial zero-argument, read-only tool with no output schema, the description is close to sufficient but omits what a skill entry contains and how this differs from search_skills/get_skill, which is exactly the information an agent needs to choose correctly among the three.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters, so the baseline is 4; there is no parameter meaning for the description to add. The statement that it returns all skills is consistent with the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource ('List all available prompt-engineering skills') with a scope qualifier ('all available') that hints at unfiltered enumeration. However, it never distinguishes itself from the close siblings search_skills and get_skill, leaving the agent to infer the difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'all' loosely implies the unfiltered-enumeration case, but there is no explicit when-to-use, no when-not-to-use, and no named alternative despite search_skills and get_skill sitting right next to it. The agent gets essentially no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prepare Metapod to turn a raw request into System and Task Prompts. Host executes the returned packet.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description usefully adds that the host — not this tool — executes the returned packet, which is consistent with readOnlyHint. However, it says nothing about what the packet contains, latency, or how the request is interpreted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, the transformation outcome is front-loaded, and there is no filler. It is efficient, though the opening meta-phrasing is slightly awkward.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, an opaque tool name, an undocumented sole parameter, and no sibling differentiation among eleven related tools, the definition omits too much for an agent to confidently select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single required 'request' parameter, so the description carries the burden. It only restates it as a 'raw request' without saying what form that takes (natural language? structured? size/format expectations), adding almost nothing beyond the schema's maxLength=200000.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the transformation (a request into System and Task Prompts), so the verb+output are identifiable, but 'Prepare Metapod' is self-referential and opaque — it never says what Metapod is or how it differs from prompt-related siblings like tasker, prompt_pipeline, or brian_spillner.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this versus the many prompt/pipeline siblings, no prerequisites, and no exclusions. The agent is left to infer the triggering condition from the phrase 'raw request' alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply explicit Judge-authorized exact replacements to a STOP final. Preserves original final; requires fresh diff-only confirmation before approval.
| Name | Required | Description | Default |
|---|---|---|---|
| fixes | Yes | ||
| run_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as a write (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds genuinely new context: the original final is preserved (consistent with destructiveHint=false) and a fresh diff-only confirmation is required before approval. That workflow constraint is not derivable from any structured field. It still doesn't say what happens when an 'old' string is not found or when the run isn't in STOP state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the core action front-loaded and the safety constraint second. Dense with domain terms but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-idempotent, two-parameter mutation tool with no output schema, this covers the essentials: authorization source, target artifact, preservation guarantee, and confirmation gate. It omits error/rejection semantics and the batch-size limit, leaving meaningful gaps for an agent orchestrating a pipeline run.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the load. It does convey that replacements are exact old-string matches, which explains the old/new pair semantics and implies literal matching rather than regex. But it says nothing about the 1–10 item cap on 'fixes', the run_id format, or failure behavior for unmatched strings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb+resource is specific: 'Apply explicit Judge-authorized exact replacements to a STOP final.' It identifies the operation on a distinct artifact state ('STOP final') within the pipeline family. It stops short of naming a sibling to distinguish it from, and the domain jargon ('Judge-authorized', 'STOP final') assumes insider knowledge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The prerequisite is implied through 'Judge-authorized' and 'STOP final' — an agent can infer this runs only after a Judge verdict on a stopped run. However, there is no explicit when-to-use statement, no when-not-to-use, and no named alternative among siblings like pipeline_submit or pipeline_resume.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pause a running stage for a real user decision or unavailable fresh workers. Preserve the pending stage for resume.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| run_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (not read-only, not destructive, not idempotent), so the bar is lower. The description adds real value by stating the pending stage is preserved for resume, i.e. the pause is reversible. However, it omits what happens to in-flight work or a double-pause, which matters given idempotentHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and its conditions, and the preservation guarantee placed second. Nothing is redundant or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A non-destructive mutation with no output schema and zero parameter documentation needs more than two sentences. The reversibility guarantee is useful, but idempotency behavior, failure modes, and the semantics of reason are left uncovered for an agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description explains neither parameter. run_id is self-evident, but reason (a free-text field with a 200k maxLength) gets no guidance on expected content or granularity, even though the stated pause conditions hint at what belongs there.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ("Pause a running stage") that an agent can place immediately against siblings like pipeline_resume and pipeline_status. Minor ambiguity remains between pausing a stage versus the whole run, since the sibling family is named pipeline_*, and no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete triggering conditions: "for a real user decision or unavailable fresh workers," which tells the agent when pausing is the right move. It also implies the complement (resume) but states no exclusions, such as when not to pause or what to do instead for non-stage failures.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume a paused run using the actual user decision. Never invent an answer or bypass the four-round cap.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| decision | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, closed-world). The description adds the "actual user decision" and "four-round cap" context, but does not explain what resuming does to run state or what the cap means, so it adds only modest context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the primary action front-loaded and no filler; the guardrail follows the action, which is the right order.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-idempotent mutation with no output schema and 0% parameter coverage, the description should explain the decision payload, state transition, and the four-round cap it references. It leaves all of these undefined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for both parameters. The description says the decision must be the "actual user decision," which gives some meaning for `decision`, but explains nothing about the `run_id` UUID or the decision's expected format/content. It does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (resume) and resource (a paused run), which cleanly distinguishes it from the sibling pipeline_pause. It does not name an alternative sibling explicitly, so it falls just short of the top mark.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Resume a paused run" implies the precondition (the run must be paused) and the guardrail about not inventing an answer hints at how the decision should be sourced. However there is no explicit when-to-use/when-not or reference to pipeline_status / pipeline_apply_fixes as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read run status, score history, artifacts and the active dispatch.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful fact that the response bundles status, score history, artifacts, and active dispatch — helpful since there is no output schema — but says nothing about behavior for an unknown run_id or how 'active dispatch' is scoped.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the verb and the returned artifacts come first. It is tight, though terse enough that it leaves gaps rather than being optimally informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only status tool with full annotation coverage and no output schema, disclosing the returned sections largely suffices. However, the sole required parameter is undocumented in both schema and description, so the definition is only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single required run_id parameter, and the description never mentions it. The UUID format/pattern in the schema implies a run identifier, but the description contributes no meaning beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Read) and enumerates the resources returned: run status, score history, artifacts, and the active dispatch. That clearly separates it from pipeline_submit/pause/resume/apply_fixes, though it never explicitly names those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the pipeline_* siblings. The agent must infer from the name alone that this is the polling/inspection tool for an existing run.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit exactly one isolated worker output. Validate and persist it, then advance or retry the expected stage.
| Name | Required | Description | Default |
|---|---|---|---|
| output | Yes | ||
| run_id | Yes | ||
| dispatch_id | Yes | ||
| execution_id | Yes | ||
| fresh_context | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare a non-read-only, non-destructive, non-idempotent write. The description adds real value beyond them by disclosing the side-effect chain: the output is validated, persisted, and then the expected stage is advanced or retried. It does not say what happens on validation failure or what permissions are required, so it is not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler; the core action and the resulting state transition are front-loaded. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a five-required-parameter mutation with no output schema, the description covers the write effect but leaves the three opaque identifiers and fresh_context unexplained, and does not point to the pipeline_status/prompt_pipeline calls that presumably produce run_id and dispatch_id. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across five required parameters, and the schema supplies only types and UUID formats. The description touches only the 'output' parameter ('isolated worker output') and says nothing about run_id, dispatch_id, execution_id, or fresh_context, nor where those identifiers come from. It does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('submit... worker output') plus a scope constraint ('exactly one isolated'). An agent can distinguish it from prompt_pipeline and pipeline_status without opening a schema, though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'submit exactly one isolated worker output' implies the usage context (one worker result per call) and the pipeline context, but there is no explicit when-to-use / when-not-to-use statement or reference to alternatives like pipeline_status or prompt_pipeline. Usage is only inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a durable Full (idea → prompt) or optimize-only (existing prompt) run. Returns the next isolated-worker dispatch; the host executes it.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| input | Yes | ||
| priorities | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world write. The description usefully adds beyond that: the run is 'durable', and the call returns a 'next isolated-worker dispatch' that 'the host executes' — a non-obvious async/dispatch contract. It stops short of saying what happens on re-invocation or how the run is later resumed/inspected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, front-loaded with the action and its two variants, then the return/dispatch contract. Nothing redundant with the name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly explains the return value (a worker dispatch executed by the host), which is the key missing structured information. But for a durable, stateful run tool surrounded by pipeline_status/submit/pause/resume siblings, it omits how the run is tracked afterward and leaves 'priorities' unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 3 params, so the description must carry the load. It does clarify mode (naming both enum values) and gives strong semantic framing for 'input' (an idea for full, an existing prompt for optimize-only), but the third parameter 'priorities' is never mentioned, leaving a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Start') and resource ('run') and enumerates the two modes with their inputs ('Full (idea → prompt)' vs 'optimize-only (existing prompt)'), so the agent knows exactly what happens. It does not, however, distinguish itself from close siblings like pipeline_submit or pipeline_status, so the agent must infer the split.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical glosses for each mode implicitly tell the agent which mode to pick based on whether it has an idea or an existing prompt. There is no explicit when-to-use vs when-not guidance against the other pipeline_* siblings, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keyword-search skill names and descriptions.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that both names and descriptions are matched, which is useful, but says nothing about ranking, matching behavior, or result format. With annotations carrying the safety burden, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler. It is appropriately sized for the tool, though its brevity doubles as under-specification captured in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so return values need not be explained. However, for a tool with an undocumented 'limit' parameter and undisclosed pagination/matching behavior, the definition is only minimally complete, though annotations reduce the behavioral burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It implies the query string targets skill names and descriptions, but gives no semantics for the 'limit' parameter (default 10, max 50) or the query length constraint. Most parameter meaning is left undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'Keyword-search skill names and descriptions.' The 'keyword-search' framing distinguishes it from list_skills and get_skill, but it never names those siblings explicitly, so differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance and no alternatives named. The description does not say when to prefer this over list_skills or get_skill, nor any exclusions or prerequisites. The agent must infer usage from the verb alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prepare Tasker to optimize a rough task assignment. Host executes the returned skill; underlying task is never performed.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds the important fact that the host executes the returned skill and the underlying task is never performed, which goes beyond the safety annotations and clarifies the tool's non-execution behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no filler. However, the first sentence is confusing and not clearly front-loaded, but it is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what is returned. It mentions 'returned skill' but does not describe its form or how the host should use it, nor does it clarify what 'underlying task' means. For a one-parameter tool the coverage is minimal but still leaves gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the only parameter 'task' has no description. The description hints that the input is a 'rough task assignment' but does not specify format, content, or constraints, leaving the 200,000-character string parameter largely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Prepare Tasker to optimize a rough task assignment,' which largely restates the tool name 'tasker' and does not define a specific verb+resource that an agent can distinguish from siblings like prompt_pipeline or get_skill. The added 'optimize a rough task assignment' is vague and does not clarify what the tool actually produces or how it differs from other skill-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no mention of alternatives. The agent is left to infer whether this is appropriate for a given task versus using list_skills or prompt_pipeline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0brian_spillnerget_skilljudge_dreddlist_skillsmetapodpipeline_apply_fixespipeline_pausepipeline_resumepipeline_statuspipeline_submitprompt_pipelinesearch_skillstaskerScored across 13 tools
The pipeline_* tools are clearly differentiated by distinct verbs (status, submit, pause, resume, apply_fixes), and the skill discovery trio (list/search/get) is distinct. However, the four persona tools (tasker, metapod, judge_dredd, brian_spillner) share an identical 'prepare X to return skill instructions' behavior, and get_skill also returns skill instructions, so boundaries must be inferred from descriptions rather than names.
Two coherent families exist: verb_noun snake_case (list_skills, search_skills, get_skill) and noun-prefixed pipeline_* operations. But the four single-word persona names (tasker, metapod, judge_dredd, brian_spillner) break any verb_noun pattern, making the overall set mixed rather than predictable.
13 tools is well within a reasonable range for a prompt-engineering pipeline with skill discovery, skill wrappers, and a full run lifecycle. Each tool appears to earn its place, though the four persona wrappers could arguably be consolidated into a single parameterized tool.
The surface covers discovery (list/search/get), execution packaging (persona tools), and a durable pipeline lifecycle (start, status, submit, pause, resume, apply_fixes). Minor gaps exist—no explicit cancel/delete for runs or a listing of past runs—but core workflows are covered without obvious dead ends.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
Generate contextual prompts and reusable agent skills, evaluate prompts with the 16-dimension Prompt Score, and manage saved work in PromptDrive. Twelve MCP tools also provide authorized access to private Memory for source-grounded answers. Connect over Streamable HTTP using OAuth 2.1 and PKCE. Generation consumes account quota and automatically saves successful results; Memory access follows account permissions and plan limits.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
