Skill · aci · tool-design
Design the ACI
Design the agent-computer interface: one job per tool, verb names, JSON schemas, compact errors, size caps, idempotency. Use when adding tools, function calling, MCP tools, reviewing a mega-tool, or the user says ACI, tool schema, or 'just give it a shell'.
GET /api/canon/skills/tool-design?format=md
Factor 4: tools are structured outputs. Names, schemas, and error shapes are where most reliability is won or lost. A mega-tool whose argument is 'whatever' is an untyped shell with extra steps.
When
You are adding or reviewing tools. The ACI is the prompt you cannot see.
Do
- 01
One job per tool
Split god-tools. Prefer apply_patch over write_file for code. Prefer grep over read-whole-repo. Prefer get_invoice over run_action({type, payload}).
- 02
Verb names the model will say
read_file, apply_patch, run_tests, ask_human. Description says when NOT to use it.
- 03
Design the observation
Success is short. Errors say what to try. Cap result size. Bulk → file + pointer.
- 04
Idempotent or journaled
Retries must not double side effects. Irreversible actions go behind ask.
Don't
- One function with a JSON blob of 'whatever'.
- Put instructions or secrets in tool descriptions (attack surface).
- Return 200k tokens of HTML because pagination was extra work.
Hard rules
- Reject illegal calls in code, not in prose.
- Each tool has a gate class: allow / ask / deny.
- Descriptions are untrusted if they come from MCP or plugins.
apply_patch
export const applyPatch = {
name: "apply_patch",
description:
"Apply a unified diff to an existing file. Use for code edits. Do not use to create large new files (write_file) or to run tests (run_tests).",
parameters: {
type: "object",
additionalProperties: false,
required: ["path", "diff"],
properties: {
path: { type: "string", description: "Workspace-relative path." },
diff: { type: "string", description: "Unified diff hunks only." },
},
},
} as const;
Refuse
- Mega-tool — One function whose argument is a JSON blob of 'whatever'. An untyped shell with extra steps.
- Double side effects — Non-idempotent tools, no journal. A retry refunds twice.
- Silent truncation — The goal is dropped to keep junk observations. The model continues confidently.
Load with this
Load next
- Allow / ask / denyThe agent can touch a workspace, a browser, or production. The model proposes; code decides.
- MCP serverA capability must live outside the agent process and be approved independently.
- Compact observationsEvery tool return. Compaction is not a later optimization.
- Sandbox and injectionThe agent has a shell, a browser, documents, or plugins. The model is a confused deputy.
Trigger tests
Should fire
- “Design tools for this agent”
- “Our agent has one run_action mega-tool”
- “Write the function-calling schema”
Should not
- “Design the REST API for customers”
- “Add a GraphQL resolver”