Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
natorion merged 3 commits into from
Feb 13, 2026
Merged

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

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
82bee84
docs: Add 'Progressive Complexity' and 'Reference over Value' design …
natorion Feb 12, 2026
a24f76d
Update design-principles.md
natorion Feb 13, 2026
20c0961
docs: Fix formatting
natorion Feb 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/design-principles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.