From ad17fe7aa71f5cbffcdff3e27b08bc4538e73c7d Mon Sep 17 00:00:00 2001
From: morluto <76467478+morluto@users.noreply.github.com>
Date: Fri, 17 Jul 2026 02:22:34 +0000
Subject: [PATCH] docs: prioritize agent usability in tool design

---
 AGENTS.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 452481a0e..2b4a1a612 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -102,7 +102,9 @@ Use ESM TypeScript, two-space indentation, and Prettier defaults. Keep compiler
 
 Name tests `*.test.ts`. Use Vitest and production seams (`tests/fixtures/`) rather than module mocks. Domain tests assert pure behavior; adapter tests use fake launcher/socket seams; MCP tests connect with the client SDK version pinned in `package.json`. Preserve the canonical tool inventory defined by `TOOL_CONTRACTS` and verified through `CATALOG_IDENTITY` and generated product metadata. Cover malformed input, cancellation, timeouts, process exit, concurrency, limits, and clean shutdown. Real Hopper, Ghidra, browser, JavaScript replay, managed conformance, and any real managed-tool claims cannot be replaced by mocks; use the corresponding `verify:*` command.
 
-MCP tool catalogs must remain complete and self-describing. Prefer capability- and session-scoped tool advertisement over schema truncation. Do not impose arbitrary serialized-byte ceilings on tool schemas or `tools/list`; assess model-context cost only against a named client's actual model-facing projection and tokenizer.
+MCP tools are agent-computer interfaces. Optimize them first for successful agent use: distinct purposes, clear names and parameters, relevant result context, actionable errors, and realistic multi-step workflows. Validate tool-design changes with representative agent tasks and transcripts when possible; schema validity and transport success alone do not prove that a tool is easy for an agent to use.
+
+MCP tool catalogs must remain complete and self-describing. Prefer capability- and session-scoped tool advertisement over schema truncation. Never use serialized byte counts as a proxy for model-context cost, token use, tool usability, or agent performance. Measure bytes only when evaluating a named transport, storage, or protocol constraint. Any model-context or token-efficiency claim must identify the client and its actual model-facing projection and tokenizer, since clients may omit, transform, dereference, or otherwise reproject MCP schemas. Do not weaken names, descriptions, schemas, examples, errors, or result context to improve a byte-based metric.
 
 ## Commit & Pull Request Guidelines