APPENDIX C: PATTERNS CATALOG

TOOLING PATTERNS Typed handler pattern: tools of the same kind share one base handler that applies the same safety checks, so one fix improves them all. Use this when: you have several tools that do similar things, such as many file tools. On-demand discovery pattern: the harness loads only the tool descriptions that a task needs instead of listing every tool each turn. Use this when: you have many tools and listing them all would fill the context window. Read-only versus action split pattern: tools that only look are kept separate from tools that change things, and the changing tools get extra safeguards. Use this when: you want most of the agent's work to run without human approval while still protecting important data. Draft-then-send pattern: one tool prepares a message for review and a different tool actually sends it. Use this when: sending the message cannot be undone. Idempotent tool pattern: tools are designed so that repeating a call leaves things in the same state, often by using an idempotency key or a set operation instead of an increment. Use this when: a timeout might lead the harness to retry a call that already succeeded. Helpful error pattern: a tool returns an error message that says what went wrong and how to fix it. Use this when: you want the agent to correct itself without asking a human.