[PR #485] [MERGED] docs: add REA tool design guidance #2021

New issue

Closed

opened 2026-10-16 21:13:26 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:13:26 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/485
Author: @morluto
Created: 9/29/2026
Status: ✅ Merged
Merged: 9/29/2026
Merged by: @morluto

Base: main ← Head: docs/agent-tool-design-guidance

📝 Commits (1)

e443420 docs: clarify MCP tool design guidance

📊 Changes

3 files changed (+105 additions, -108 deletions)

View changed files

📝 AGENTS.md (+33 -108)
📝 CONTRIBUTING.md (+2 -0)
➕ docs/tool-design.md (+70 -0)

📄 Description

Summary

Adds agent guidance for designing task-focused REA CLI/MCP tools and trims volatile implementation detail from AGENTS.md.

Problem and expected behavior

REA's existing guidance described architecture and MCP quality principles, but did not give agents a clear way to decide when a task calls for an inspect/search primitive, a trace, a comparison, or a composed workflow.

Change and scope

Shortens the file-by-file map and command/environment catalog in AGENTS.md.
Adds concise tool-shape and contract rules to AGENTS.md.
Adds docs/tool-design.md with the decision process, contract requirements, and evaluation guidance.
Links the guide from CONTRIBUTING.md.
Includes scenario patterns for tracing UI controls into handlers/state, explaining simulation rules, comparing choices, and reconstructing navigation.

Contract and boundary impact

Semantic owner and earliest changed stage: contributor/agent documentation.
CLI and MCP/tool-catalog contract: none.
Provider, bridge, target-format, or platform compatibility: none.
Evidence, artifact, provenance, or reconstruction contract: no runtime contract changes; the guide asks future tools to preserve these distinctions.
Process execution, authorization, cleanup, or containment impact: none.
Generated metadata (docs/product-catalog.json), package, or installation impact: none.

Evidence and regression coverage

Tests added or updated: none; documentation only.
Base reproduction or other evidence: reviewed current AGENTS.md, docs/mcp-contracts.md, docs/testing.md, and CONTRIBUTING.md.
User-visible CLI/MCP output: not applicable.
Remaining proof gaps: none for the documentation change.

Validation performed

git diff --cached --check — passed before commit.
Automated tests: not run; this change does not alter executable behavior.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: not applicable.
Package or release metadata impact: none.
Security, privacy, process, or containment review: no runtime behavior changed.

Review checklist

The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is not applicable; this is a documentation clarification.
Owning docs are updated.
I checked the final diff for unrelated cleanup and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/485 **Author:** [@morluto](https://github.com/morluto) **Created:** 9/29/2026 **Status:** ✅ Merged **Merged:** 9/29/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `docs/agent-tool-design-guidance` --- ### 📝 Commits (1) - [`e443420`](https://github.com/morluto/rea/commit/e443420084cfb48c6e6cb48745315e0bb0146e72) docs: clarify MCP tool design guidance ### 📊 Changes **3 files changed** (+105 additions, -108 deletions) <details> <summary>View changed files</summary> 📝 `AGENTS.md` (+33 -108) 📝 `CONTRIBUTING.md` (+2 -0) ➕ `docs/tool-design.md` (+70 -0) </details> ### 📄 Description ## Summary Adds agent guidance for designing task-focused REA CLI/MCP tools and trims volatile implementation detail from `AGENTS.md`. ## Problem and expected behavior REA's existing guidance described architecture and MCP quality principles, but did not give agents a clear way to decide when a task calls for an inspect/search primitive, a trace, a comparison, or a composed workflow. ## Change and scope - Shortens the file-by-file map and command/environment catalog in `AGENTS.md`. - Adds concise tool-shape and contract rules to `AGENTS.md`. - Adds `docs/tool-design.md` with the decision process, contract requirements, and evaluation guidance. - Links the guide from `CONTRIBUTING.md`. - Includes scenario patterns for tracing UI controls into handlers/state, explaining simulation rules, comparing choices, and reconstructing navigation. ## Contract and boundary impact - Semantic owner and earliest changed stage: contributor/agent documentation. - CLI and MCP/tool-catalog contract: none. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: no runtime contract changes; the guide asks future tools to preserve these distinctions. - Process execution, authorization, cleanup, or containment impact: none. - Generated metadata (`docs/product-catalog.json`), package, or installation impact: none. ## Evidence and regression coverage - Tests added or updated: none; documentation only. - Base reproduction or other evidence: reviewed current `AGENTS.md`, `docs/mcp-contracts.md`, `docs/testing.md`, and `CONTRIBUTING.md`. - User-visible CLI/MCP output: not applicable. - Remaining proof gaps: none for the documentation change. ## Validation performed - `git diff --cached --check` — passed before commit. - Automated tests: not run; this change does not alter executable behavior. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: not applicable. - Package or release metadata impact: none. - Security, privacy, process, or containment review: no runtime behavior changed. ## Review checklist - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is not applicable; this is a documentation clarification. - [x] Owning docs are updated. - [x] I checked the final diff for unrelated cleanup and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:13:26 +00:00