Tool Use

Tool use adalah jembatan antara "model yang menghasilkan teks" dan "agent yang mengerjakan sesuatu". Halaman ini membedah mekanismenya — cukup dalam untuk kamu bisa menulis tool sendiri dan mengatur permission dengan sadar.

Mekanisme dasar: function calling

Model tidak pernah "menjalankan" apa pun. Yang terjadi:

1. Harness (program CLI-nya — Claude Code, opencode, dst.) mengirim ke model: percakapan + daftar tool beserta skema parameternya (JSON Schema).
2. Model membalas bukan dengan prosa, tapi dengan tool call terstruktur: {"name": "bash", "input": {"command": "npm test"}}.
3. Harness yang mengeksekusi perintah itu di mesinmu, lalu mengirim hasilnya kembali ke model sebagai pesan berikutnya.

   MODEL (di cloud)                      HARNESS (di mesinmu)
   ─────────────────                     ────────────────────
   "aku mau jalankan      ──────────▶    cek permission
    npm test"                            eksekusi: npm test
                          ◀──────────    kirim stdout/stderr
   "test gagal di X,
    aku baca file X"      ──────────▶    baca file, kirim isinya

Konsekuensi penting: keamanan dan permission adalah urusan harness, bukan model. Model boleh "meminta" apa saja; harness yang memutuskan mengeksekusi atau tidak. Saat memilih tool di Landscape, kualitas harness (permission, sandboxing, ketepatan edit) sama pentingnya dengan kualitas model.

Toolkit standar coding agent

Semua coding agent serius punya tool inti yang hampir identik:

Tool	Fungsi	Catatan operator
read	Baca file (dengan nomor baris)	Murah, aman, tidak perlu dibatasi
edit	Ganti string lama → baru di file	Edit gagal kalau string sudah berubah — mekanisme anti-stale (oh-my-pi bahkan pakai hash-anchored edits)
write	Tulis/timpa file utuh	Lebih berisiko dari edit — bisa menimpa isi yang tidak dibaca
bash/shell	Jalankan perintah	Tool paling berkuasa sekaligus paling berbahaya
grep/glob/search	Cari kode	Fondasi agentic search (Context Engineering)
web_search/fetch	Akses internet	Pintu masuk prompt injection (Guardrails)
subagent/task	Delegasi ke agent lain	Dibahas di Memory, Skills & Subagents

Di atas toolkit inti, tool tambahan datang dari MCP servers (database, Slack, browser, dsb.) atau dari CLI apapun yang bisa dipanggil via bash.

Permission model

Inilah dial otonomi (level A2–A4) dalam bentuk konkret. Pola umum di semua tool:

• Read-only selalu boleh — baca file dan search tidak merusak apa pun.
• Write/edit minta izin — sampai kamu mengizinkan per-sesi atau per-pola.
• Shell minta izin per-perintah — dengan allowlist: npm test boleh selamanya, rm selalu tanya.
• Mode YOLO/full-auto ada di semua tool — jangan dipakai di mesin utama tanpa sandbox.

Claude Code

Permission diatur via /permissions atau file .claude/settings.json (bisa di-commit untuk berlaku se-tim):

.claude/settings.json

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Edit"
    ],
    "deny": [
      "Read(./.env)",
      "Bash(rm -rf:*)"
    ]
  }
}

Mode tersedia: default (tanya), accept edits (edit otomatis, shell tetap tanya), plan mode (read-only, menyusun rencana dulu), dan --dangerously-skip-permissions (hanya untuk sandbox/container).

opencode

Permission diatur di opencode.json dengan pola per-tool:

opencode.json

{
  "permission": {
    "edit": "allow",
    "bash": {
      "npm test": "allow",
      "npm run lint": "allow",
      "*": "ask"
    }
  }
}

Nilai yang tersedia: allow, ask, deny. Ada juga mode plan (read-only) dan build.

oh-my-pi

oh-my-pi mengikuti pola pi: konfigurasi di ~/.config/omp/ dengan permission per-tool, plus plan mode. Cek omp --help untuk flag terbaru — proyek ini bergerak cepat; verifikasi terhadap repo resminya.

:::warning Aturan emas allowlist Izinkan per-pola spesifik (npm test:*), jangan per-kategori (Bash semuanya). Perintah yang pantas masuk allowlist permanen hanyalah yang idempotent dan tidak destruktif: test, lint, build, git status/diff. Perintah dengan efek keluar (git push, deploy, migrasi DB) harus selalu lewat gate — manusia atau review pipeline. :::

Menulis tool yang baik (untuk yang membangun sendiri)

Kalau kamu memperluas agent dengan tool custom (via MCP atau SDK), tiga aturan dari pengalaman industri:

1. Deskripsi tool adalah prompt. Model memilih tool berdasarkan deskripsinya. Deskripsi ambigu = tool salah pakai.
2. Kembalikan error yang informatif. "Gagal" tidak bisa diperbaiki model; "gagal: kolom user_id tidak ada, kolom tersedia: [...]" bisa.
3. Buat parameter sesempit mungkin. Tool run_sql(query) mengundang bencana; get_order_status(order_id) tidak.

Kenapa ini penting untuk playbook

Setup agent di playbook sebagian besar adalah pekerjaan mengkonfigurasi permission: allowlist yang cukup longgar supaya agent tidak macet setiap 30 detik, cukup ketat supaya kesalahan terburuknya murah. Dan saat kamu pindah ke kontrol via Telegram, permission ini menjadi satu-satunya rem — kamu tidak lagi menekan y/n di terminal.

Lanjut

→ Context Engineering: kenapa agent dengan tool lengkap pun tetap gagal kalau konteksnya salah kelola.