[GH-ISSUE #489] [Docs] Make reusable analysis primitives the default tool-design unit #263

New issue

Closed

opened 2026-10-15 18:23:09 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:23:09 +00:00

Owner

Originally created by @morluto on GitHub (Oct 1, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/489

Gap

The current tool-design guidance is strong on provider boundaries, evidence, and avoiding mega-tools, but it does not clearly distinguish a reusable analysis primitive from a domain-specific workflow. This can encourage proposals named around one application concept or business outcome instead of capabilities that compose across unrelated artifacts and questions.

Proposed guidance

Update docs/tool-design.md with a short decision rule: prefer a bounded primitive when it exposes one reusable fact or relationship (for example, resolve a call target, enumerate typed references, inspect one resource graph, or compare explicit evidence). Add a composed workflow only when it serves a recurring analyst outcome across target domains and cannot be expressed clearly by composing the available primitives. Keep app/domain-specific language in analyst prompts or documentation, not in general-purpose tool contracts.

Add a brief pointer in AGENTS.md so implementation work follows the same rule. Preserve the existing distinction between provider facts, normalized domain contracts, and composed application workflows.

Acceptance criteria

The guidance distinguishes capability primitives from composed workflows with one concise test and a couple of general examples.
It says not to promote a one-target or one-domain outcome into a reusable public tool without evidence of broader reuse.
It does not prescribe tool names, call sequences, arbitrary limits, or provider-specific public APIs.
AGENTS.md stays concise and points to the detailed checklist in docs/tool-design.md.

Originally created by @morluto on GitHub (Oct 1, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/489 ## Gap The current tool-design guidance is strong on provider boundaries, evidence, and avoiding mega-tools, but it does not clearly distinguish a reusable analysis primitive from a domain-specific workflow. This can encourage proposals named around one application concept or business outcome instead of capabilities that compose across unrelated artifacts and questions. ## Proposed guidance Update `docs/tool-design.md` with a short decision rule: prefer a bounded primitive when it exposes one reusable fact or relationship (for example, resolve a call target, enumerate typed references, inspect one resource graph, or compare explicit evidence). Add a composed workflow only when it serves a recurring analyst outcome across target domains and cannot be expressed clearly by composing the available primitives. Keep app/domain-specific language in analyst prompts or documentation, not in general-purpose tool contracts. Add a brief pointer in `AGENTS.md` so implementation work follows the same rule. Preserve the existing distinction between provider facts, normalized domain contracts, and composed application workflows. ## Acceptance criteria - The guidance distinguishes capability primitives from composed workflows with one concise test and a couple of general examples. - It says not to promote a one-target or one-domain outcome into a reusable public tool without evidence of broader reuse. - It does not prescribe tool names, call sequences, arbitrary limits, or provider-specific public APIs. - `AGENTS.md` stays concise and points to the detailed checklist in `docs/tool-design.md`.

bsakaguchi

2026-10-15 18:23:09 +00:00