Hablich Agent Interface Engineering Framework

// When should I apply the Hablich Agent Interface Engineering Framework?

Use this skill whenever you are building, auditing, or improving an MCP server, CLI tool, or any interface that agents will consume. Trigger it when you notice agents failing tasks, burning too many tokens, getting stuck on errors, not calling the right tools, or when you are making trust/permission decisions in an agentic system.

// What inputs do I need before applying the Hablich framework?

• Agent interface descriptionrequired
  What MCP server, CLI tool, or agent-facing API you are designing or auditing — its purpose, current tools, and target agent harness (e.g. Claude Code, Gemini CLI, Codex).
• Target user journeysrequired
  The specific task classes or workflows agents will perform through this interface. List each distinct journey separately because fuel efficiency metrics must not be compared across journey types.
• Current tool inventoryrequired
  List of tools currently exposed, with their names and descriptions (or intended descriptions). Can be a draft or existing schema.
• Deployment tierrequired
  Which tier the agent operates in: Tier 1 (local dev, human in loop), Tier 2 (CI/controlled environment), or Tier 3 (full internet access / browsing agent fleet).
• Observed failure modes
  Known or suspected ways the interface currently fails — context window blowout, agents getting stuck, wrong tool selection, security concerns, etc.

// What are the core principles behind the Hablich Agent Interface Engineering Framework?

// How do you apply the Hablich framework step by step?

1. 1

   Identify deployment tier and establish trust boundaries before any other design decision

   Classify the agent's operating environment: Tier 1 (local dev, human in loop, default Chrome profile / local data, time-bound consent), Tier 2 (CI / controlled, use data separation — containers, separate profiles, remote debugging port), Tier 3 (full internet access — domain allow lists, prompt injection mitigations, maximum isolation). A tool can be shared across tiers; the security model must not be. Apply the Lethal Trifactor lens (Simon Willison) to Tier 1 specifically: confirm a human must consent at each sensitive action, and treat convenience requests that remove that consent as security risks, not UX wins.

2. 2

   Map each target user journey and diagnose whether agents are currently flying blind

   List each distinct task class the agent must complete. For each, ask: what data does the agent currently receive, and is it raw/voluminous or semantically summarised? If the agent is receiving multi-megabyte raw files or deeply nested JSON, flag this as a dump zone risk. Identify which journeys are lightweight (e.g. web scraping) vs. intricate (e.g. debugging responsive layout) — fuel efficiency targets will differ and must not be compared across these classes.

3. 3

   Replace raw data outputs with semantic summaries for data-heavy tool responses

   For any tool that currently returns large raw payloads (traces, logs, trees, JSON blobs), engineer an alternative return format: structured markdown and semantic summaries that surface only the actionable signal. Do not delete the raw output capability — it may be needed for post-processing pipelines — but make the semantic summary the default agent-facing response. The goal is pointing the agent at the right sentence, not handing it the entire book.

4. 4

   Categorise tools and apply tool categorisation to control default context exposure

   Review your full tool inventory. Identify niche tools that only apply to specific sub-populations of users or use cases. Hide these behind command line parameters or opt-in flags — do not add them to the default context. Consider offering a Slim Mode (minimal tool set — e.g. select, navigate, evaluate) for cost-sensitive or context-constrained deployments, but explicitly document the capability trade-offs: slim mode reduces token cost but may force extra turns or block certain tasks entirely.

5. 5

   Audit every tool description for intent clarity using the 'schema as UI' standard

   For each tool, evaluate the description against two criteria: (1) Purpose — does it clearly explain the tool's core function? (2) Usage guidelines — does it provide clear activation criteria, i.e. when should an agent call this tool? Add concrete trigger signals: domain terms, task types, metric names that an agent can pattern-match to. Example pattern: 'Use to find front-end performance issues and core web vitals: LCP, INP, CLS' — this lets the agent infer the tool is relevant when asked to improve page load. Be aware that longer descriptions grow context window size and can bias smaller models toward wrong tool selection; aim for minimum viable description per tool.

6. 6

   Build error recovery playbooks — turn every error state into a self-healing opportunity

   For each tool, enumerate its failure modes. Then: (a) Useful error messages — rewrite vague errors to include actionable recovery information so the agent can self-heal without human intervention. (b) Proactive detours — where model training data might cause the agent to reach for the wrong tool, add explicit redirection in the tool description or schema pointing to the correct tool. (c) Diagnostic playbooks / troubleshooting skills — for recurring setup or configuration failures, build a dedicated skill that walks the agent (and human) through resolution. Every unhandled error costs tokens on retry; every self-healed error saves them.

7. 7

   Add skills for intricate multi-step workflows, but budget their context cost consciously

   Skills (pre-built agentic workflows) are powerful for complex, repeatable journeys. Add them when a user journey has too many steps to be reliably assembled by the agent from individual tools alone. However, skills are not free lunch: piling in too many skills inflates context window size and causes agents to invoke skills inappropriately — the same discoverability problem re-emerges at the skill level. Apply the same minimum viable description discipline to skill descriptions as to individual tools.

8. 8

   Instrument and measure tokens per successful outcome per user journey

   Implement measurement even if imperfect — data-informed decisions beat gut-driven decisions. Track: token cost, tool calls, duration, and task completion (binary: did the agent complete the full user journey?). Visualise per-journey fuel efficiency (e.g. bar chart where bar length = effectiveness). Prioritise engineering effort on the journeys with the worst tokens per successful outcome. Do not aggregate across journey types — a debugging session will always use more tokens than a scraping session, and that is appropriate, not a problem.

// What does the Hablich framework look like in practice?

// What mistakes should I avoid when designing agent interfaces?

• Throwing raw, voluminous data (multi-megabyte logs, full trace files, complete AST dumps) at agents — this pushes them into the dump zone and blows through the context window.
• Building one monolithic tool and assuming the agent will figure out sub-tasks — this was the 'debug_webpage' mistake; agents need decomposed, targeted tools with clear activation criteria.
• Decomposing into many tools but leaving descriptions with quality smells — the schema is the UI; 97% of MCP tool descriptions have quality smells that cause wrong tool selection.
• Treating skills and rich descriptions as free lunch — every addition to context costs tokens and can cause agents to invoke tools or skills they shouldn't. The trade-off shifts, it never disappears.
• Comparing tokens per successful outcome globally across different user journey types — a debugging journey will always cost more than a scraping journey; aggregate comparison masks real signal.
• Removing human consent friction for convenience (e.g. auto-remembering permissions / autoconnect by default) — in agentic systems, some friction is by design. Convenience that eliminates consent checkpoints creates backdoors exploitable via prompt injection.
• Applying the same security model to a local Tier 1 agent and a Tier 3 internet-browsing agent fleet — these tiers may share tools but must never share security assumptions.
• Writing error messages that are vague or tool-internal — every unhelpful error forces the agent to burn tokens on retry or require human intervention; good error messages enable self-healing.
• Skipping measurement because it is hard to instrument perfectly — even an imperfect measurement of tokens per successful outcome is better than gut-driven decisions.

// What are the key terms in the Hablich Agent Interface Engineering Framework?

Flying Blind

The state of a coding agent that can generate code but cannot validate what it has actually done — it has no sensory interface back to the environment it is affecting. The motivating problem this framework solves.

Dump Zone

The degraded reasoning state an agent enters when its context window is overwhelmed with too much data (e.g. a 50,000-line JSON trace file). Named in reference to Matt's talk on context window management.

Tokens Per Successful Outcome

The primary fuel efficiency metric for an agent interface. Measures token cost (plus tool calls and duration) normalised only against successful task completions — not all attempts. 'Fuel efficiency is worthless if you can't reach your destination.'

Fuel Efficiency of the Interface

The aggregate quality of an agent-facing interface as measured by tokens per successful outcome. High fuel efficiency means the agent completes user journeys using the minimum token expenditure.

Effectiveness

Whether the agent completes the entire user journey and fulfils the functional intent. Binary measure: yes or no. Must be measured alongside efficiency — an optimised but ineffective interface is worthless.

Semantic Summary

A structured, human-readable (markdown) distillation of a large raw data payload that surfaces only the actionable signal relevant to the agent's task. The alternative to throwing the entire book at the agent.

Schema Is the UI for the Agent

The principle that MCP tool descriptions (names, parameter schemas, docstrings) function as the user interface the agent navigates. Poor descriptions = bad UI = wrong tool selection and task failure.

Tool Categorisation

The practice of hiding niche or rarely-needed tools behind opt-in command line parameters rather than exposing them in the default context, to reduce context window bloat and wrong tool selection.

Slim Mode

An extreme application of tool categorisation that exposes only the minimum viable tool set (e.g. 3 tools: select page, navigate page, evaluate script) for maximum token efficiency. Explicit trade-off: reduced capability and potential for extra agent turns.

Proactive Detours

Explicit redirections built into tool descriptions or schemas that counteract an agent's training-data biases — steering the agent toward the correct tool before it reaches for the wrong one.

Diagnostic Playbooks

Pre-built troubleshooting skills that activate when an agent (or human) encounters a known recurring failure mode, enabling self-healing without human intervention.

Self-Healing

The ability of an agent to recover from errors without requiring human intervention, enabled by useful error messages, proactive detours, and diagnostic playbooks.

Minimum Viable Description

The shortest tool description that still provides sufficient purpose definition and activation criteria for the agent to select and use the tool correctly. The target end-state of iterative description optimisation — never fully finished because models and harnesses keep changing.

Lethal Trifactor

Simon Willison's framework (referenced, not fully reproduced) for reasoning about the three converging risk factors in agentic browser automation that make prompt injection dangerous. Drives the by-design friction principle in Tier 1 trust design.

Tier 1 / Tier 2 / Tier 3 (Trust Tiers)

A three-tier deployment classification for browser-using agents. Tier 1: local dev environment, human in loop, time-bound consent required. Tier 2: CI/controlled environment, data separation (containers, isolated profiles) required. Tier 3: full internet access (YOLO mode) — domain allow lists, prompt injection mitigations, and full Tier 2 controls required.

Autoconnect

A convenience feature that lets a human share their screen/session with an agent without repeated consent prompts. Flagged as a trust boundary risk — convenience that removes consent friction is by-design rejected in Tier 1 deployments.

Agents Are a Different User Class

The foundational insight that agents are a separate user segment from humans, sharing the same goals and intents but having fundamentally different cognitive bottlenecks — token cost and reasoning load rather than visual complexity.

// FREQUENTLY ASKED QUESTIONS