From 82bee846e1a6b6997f7452b275b3b18377052bb2 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Thu, 12 Feb 2026 07:41:20 -0500 Subject: [PATCH 1/3] docs: Add 'Progressive Complexity' and 'Reference over Value' design principles. --- docs/design-principles.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/design-principles.md b/docs/design-principles.md index a2066a5dc..e3a658ed5 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. From a24f76d990c46692a20fa0c94918c6fd5b016599 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Fri, 13 Feb 2026 16:16:00 +0100 Subject: [PATCH 2/3] Update design-principles.md Added the considaration of direct processing of heavy assets. --- docs/design-principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design-principles.md b/docs/design-principles.md index e3a658ed5..fc84084f7 100644 --- a/docs/design-principles.md +++ b/docs/design-principles.md @@ -9,4 +9,4 @@ Apply them with nuance. - **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. +- **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. From 20c0961682876bcb15e97ad199697c9b2640b435 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Fri, 13 Feb 2026 10:52:37 -0500 Subject: [PATCH 3/3] docs: Fix formatting --- docs/design-principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design-principles.md b/docs/design-principles.md index fc84084f7..3cf9baef1 100644 --- a/docs/design-principles.md +++ b/docs/design-principles.md @@ -9,4 +9,4 @@ Apply them with nuance. - **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. +- **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.