Skip to content

Chrome DevTools for coding agents

docs: Add 'Progressive Complexity' and 'Reference over Value' design principles. (#939)

Michael Hablich8d765c0aef7b
diff --git a/docs/design-principles.md b/docs/design-principles.md
index a2066a5d..3cf9baef 100644
--- a/docs/design-principles.md
+++ b/docs/design-principles.md
@@ -8,3 +8,5 @@ Apply them with nuance.
- **Small, Deterministic Blocks**: Give agents composable tools (Click, Screenshot), not magic buttons.
- **Self-Healing Errors**: Return actionable errors that include context and potential fixes.
- **Human-Agent Collaboration**: Output must be readable by machines (structured) AND humans (summaries).
+- **Progressive Complexity**: Tools should be simple by default (high-level actions) but offer advanced optional arguments for power users.
+- **Reference over Value**: for heavy assets (screenshots, traces, videos), return a file path or resource URI, never the raw data stream. Some MCP clients support a built-in handling of heavy assets e.g. directly displaying images. This _could_ be an exception.