Agent Native Architecture

<why_now>

Why Now

Software agents work reliably now. Claude Code demonstrated that an LLM with access to bash and file tools, operating in a loop until an objective is achieved, can accomplish complex multi-step tasks autonomously.

The surprising discovery: a really good coding agent is actually a really good general-purpose agent. The same architecture that lets Claude Code refactor a codebase can let an agent organize your files, manage your reading list, or automate your workflows.

The Claude Code SDK makes this accessible. You can build applications where features aren't code you write—they're outcomes you describe, achieved by an agent with tools, operating in a loop until the outcome is reached.

This opens up a new field: software that works the way Claude Code works, applied to categories far beyond coding. </why_now>

<core_principles>

Core Principles

1. Parity

Whatever the user can do through the UI, the agent should be able to achieve through tools.

This is the foundational principle. Without it, nothing else matters.

Imagine you build a notes app with a beautiful interface for creating, organizing, and tagging notes. A user asks the agent: "Create a note summarizing my meeting and tag it as urgent."

If you built UI for creating notes but no agent capability to do the same, the agent is stuck. It might apologize or ask clarifying questions, but it can't help—even though the action is trivial for a human using the interface.

The fix: Ensure the agent has tools (or combinations of tools) that can accomplish anything the UI can do.

This isn't about creating a 1:1 mapping of UI buttons to tools. It's about ensuring the agent can achieve the same outcomes. Sometimes that's a single tool (create_note). Sometimes it's composing primitives (write_file to a notes directory with proper formatting).

The discipline: When adding any UI capability, ask: can the agent achieve this outcome? If not, add the necessary tools or primitives.

A capability map helps:

The test: Pick any action a user can take in your UI. Describe it to the agent. Can it accomplish the outcome?

---

2. Granularity

Prefer atomic primitives. Features are outcomes achieved by an agent operating in a loop.

A tool is a primitive capability: read a file, write a file, run a bash command, store a record, send a notification.

A feature is not a function you write. It's an outcome you describe in a prompt, achieved by an agent that has tools and operates in a loop until the outcome is reached.

Less granular (limits the agent):

Tool: classify_and_organize_files(files)
→ You wrote the decision logic
→ Agent executes your code
→ To change behavior, you refactor

More granular (empowers the agent):

Tools: read_file, write_file, move_file, list_directory, bash
Prompt: "Organize the user's downloads folder. Analyze each file,
        determine appropriate locations based on content and recency,
        and move them there."
Agent: Operates in a loop—reads files, makes judgments, moves things,
       checks results—until the folder is organized.
→ Agent makes the decisions
→ To change behavior, you edit the prompt

The key shift: The agent is pursuing an outcome with judgment, not executing a choreographed sequence. It might encounter unexpected file types, adjust its approach, or ask clarifying questions. The loop continues until the outcome is achieved.

The more atomic your tools, the more flexibly the agent can use them. If you bundle decision logic into tools, you've moved judgment back into code.

The test: To change how a feature behaves, do you edit prose or refactor code?

---

3. Composability

With atomic tools and parity, you can create new features just by writing new prompts.

This is the payoff of the first two principles. When your tools are atomic and the agent can do anything users can do, new features are just new prompts.

Want a "weekly review" feature that summarizes activity and suggests priorities? That's a prompt:

"Review files modified this week. Summarize key changes. Based on
incomplete items and approaching deadlines, suggest three priorities
for next week."

The agent uses list_files, read_file, and its judgment to accomplish this. You didn't write weekly-review code. You described an outcome, and the agent operates in a loop until it's achieved.

This works for developers and users. You can ship new features by adding prompts. Users can customize behavior by modifying prompts or creating their own. "When I say 'file this,' always move it to my Action folder and tag it urgent" becomes a user-level prompt that extends the application.

The constraint: This only works if tools are atomic enough to be composed in ways you didn't anticipate, and if the agent has parity with users. If tools encode too much logic, or the agent can't access key capabilities, composition breaks down.

The test: Can you add a new feature by writing a new prompt section, without adding new code?

---

4. Emergent Capability

The agent can accomplish things you didn't explicitly design for.

When tools are atomic, parity is maintained, and prompts are composable, users will ask the agent for things you never anticipated. And often, the agent can figure it out.

"Cross-reference my meeting notes with my task list and tell me what I've committed to but haven't scheduled."

You didn't build a "commitment tracker" feature. But if the agent can read notes, read tasks, and reason about them—operating in a loop until it has an answer—it can accomplish this.

This reveals latent demand. Instead of guessing what features users want, you observe what they're asking the agent to do. When patterns emerge, you can optimize them with domain-specific tools or dedicated prompts. But you didn't have to anticipate them—you discovered them.

The flywheel: 1. Build with atomic tools and parity 2. Users ask for things you didn't anticipate 3. Agent composes tools to accomplish them (or fails, revealing a gap) 4. You observe patterns in what's being requested 5. Add domain tools or prompts to make common patterns efficient 6. Repeat

This changes how you build products. You're not trying to imagine every feature upfront. You're creating a capable foundation and learning from what emerges.

The test: Give the agent an open-ended request relevant to your domain. Can it figure out a reasonable approach, operating in a loop until it succeeds? If it just says "I don't have a feature for that," your architecture is too constrained.

---

5. Improvement Over Time

Agent-native applications get better through accumulated context and prompt refinement.

Unlike traditional software, agent-native applications can improve without shipping code:

Accumulated context: The agent can maintain state across sessions—what exists, what the user has done, what worked, what didn't. A context.md file the agent reads and updates is layer one. More sophisticated approaches involve structured memory and learned preferences.

Prompt refinement at multiple levels:

• Developer level: You ship updated prompts that change agent behavior for all users
• User level: Users customize prompts for their workflow
• Agent level: The agent modifies its own prompts based on feedback (advanced)

Self-modification (advanced): Agents that can edit their own prompts or even their own code. For production use cases, consider adding safety rails—approval gates, automatic checkpoints for rollback, health checks. This is where things are heading.

The improvement mechanisms are still being discovered. Context and prompt refinement are proven. Self-modification is emerging. What's clear: the architecture supports getting better in ways traditional software doesn't.

The test: Does the application work better after a month of use than on day one, even without code changes? </core_principles>

<intake>

What aspect of agent-native architecture do you need help with?

1. Design architecture - Plan a new agent-native system from scratch 2. Files & workspace - Use files as the universal interface, shared workspace patterns 3. Tool design - Build primitive tools, dynamic capability discovery, CRUD completeness 4. Domain tools - Know when to add domain tools vs stay with primitives 5. Execution patterns - Completion signals, partial completion, context limits 6. System prompts - Define agent behavior in prompts, judgment criteria 7. Context injection - Inject runtime app state into agent prompts 8. Action parity - Ensure agents can do everything users can do 9. Self-modification - Enable agents to safely evolve themselves 10. Product design - Progressive disclosure, latent demand, approval patterns 11. Mobile patterns - iOS storage, background execution, checkpoint/resume 12. Testing - Test agent-native apps for capability and parity 13. Refactoring - Make existing code more agent-native

Wait for response before proceeding. </intake>

<routing>

After reading the reference, apply those patterns to the user's specific context. </routing>

<architecture_checklist>

Architecture Review Checklist

When designing an agent-native system, verify these before implementation:

Core Principles

• [ ] Parity: Every UI action has a corresponding agent capability
• [ ] Granularity: Tools are primitives; features are prompt-defined outcomes
• [ ] Composability: New features can be added via prompts alone
• [ ] Emergent Capability: Agent can handle open-ended requests in your domain

Tool Design

• [ ] Dynamic vs Static: For external APIs where agent should have full access, use Dynamic Capability Discovery
• [ ] CRUD Completeness: Every entity has create, read, update, AND delete
• [ ] Primitives not Workflows: Tools enable capability, don't encode business logic
• [ ] API as Validator: Use z.string() inputs when the API validates, not z.enum()

Files & Workspace

• [ ] Shared Workspace: Agent and user work in same data space
• [ ] context.md Pattern: Agent reads/updates context file for accumulated knowledge
• [ ] File Organization: Entity-scoped directories with consistent naming

Agent Execution

• [ ] Completion Signals: Agent has explicit complete_task tool (not heuristic detection)
• [ ] Partial Completion: Multi-step tasks track progress for resume
• [ ] Context Limits: Designed for bounded context from the start

Context Injection

• [ ] Available Resources: System prompt includes what exists (files, data, types)
• [ ] Available Capabilities: System prompt documents tools with user vocabulary
• [ ] Dynamic Context: Context refreshes for long sessions (or provide refresh_context tool)

UI Integration

• [ ] Agent → UI: Agent changes reflect in UI (shared service, file watching, or event bus)
• [ ] No Silent Actions: Agent writes trigger UI updates immediately
• [ ] Capability Discovery: Users can learn what agent can do

Mobile (if applicable)

• [ ] Checkpoint/Resume: Handle iOS app suspension gracefully
• [ ] iCloud Storage: iCloud-first with local fallback for multi-device sync
• [ ] Cost Awareness: Model tier selection (Haiku/Sonnet/Opus)

When designing architecture, explicitly address each checkbox in your plan. </architecture_checklist>

<quick_start>

Quick Start: Build an Agent-Native Feature

Step 1: Define atomic tools

const tools = [
  tool("read_file", "Read any file", { path: z.string() }, ...),
  tool("write_file", "Write any file", { path: z.string(), content: z.string() }, ...),
  tool("list_files", "List directory", { path: z.string() }, ...),
  tool("complete_task", "Signal task completion", { summary: z.string() }, ...),
];

Step 2: Write behavior in the system prompt

## Your Responsibilities
When asked to organize content, you should:
1. Read existing files to understand the structure
2. Analyze what organization makes sense
3. Create/move files using your tools
4. Use your judgment about layout and formatting
5. Call complete_task when you're done

You decide the structure. Make it good.

Step 3: Let the agent work in a loop

const result = await agent.run({
  prompt: userMessage,
  tools: tools,
  systemPrompt: systemPrompt,
  // Agent loops until it calls complete_task
});

</quick_start>

<reference_index>

Reference Files

All references in references/:

Core Patterns:

• architecture-patterns.md - Event-driven, unified orchestrator, agent-to-UI
• files-universal-interface.md - Why files, organization patterns, context.md
• mcp-tool-design.md - Tool design, dynamic capability discovery, CRUD
• from-primitives-to-domain-tools.md - When to add domain tools, graduating to code
• agent-execution-patterns.md - Completion signals, partial completion, context limits
• system-prompt-design.md - Features as prompts, judgment criteria

Agent-Native Disciplines:

• dynamic-context-injection.md - Runtime context, what to inject
• action-parity-discipline.md - Capability mapping, parity workflow
• shared-workspace-architecture.md - Shared data space, UI integration
• product-implications.md - Progressive disclosure, latent demand, approval
• agent-native-testing.md - Testing outcomes, parity tests

Platform-Specific:

• mobile-patterns.md - iOS storage, checkpoint/resume, cost awareness
• self-modification.md - Git-based evolution, guardrails
• refactoring-to-prompt-native.md - Migrating existing code

</reference_index>

<anti_patterns>

Anti-Patterns

Common Approaches That Aren't Fully Agent-Native

These aren't necessarily wrong—they may be appropriate for your use case. But they're worth recognizing as different from the architecture this document describes.

Agent as router — The agent figures out what the user wants, then calls the right function. The agent's intelligence is used to route, not to act. This can work, but you're using a fraction of what agents can do.

Build the app, then add agent — You build features the traditional way (as code), then expose them to an agent. The agent can only do what your features already do. You won't get emergent capability.

Request/response thinking — Agent gets input, does one thing, returns output. This misses the loop: agent gets an outcome to achieve, operates until it's done, handles unexpected situations along the way.

Defensive tool design — You over-constrain tool inputs because you're used to defensive programming. Strict enums, validation at every layer. This is safe, but it prevents the agent from doing things you didn't anticipate.

Happy path in code, agent just executes — Traditional software handles edge cases in code—you write the logic for what happens when X goes wrong. Agent-native lets the agent handle edge cases with judgment. If your code handles all the edge cases, the agent is just a caller.

---

Specific Anti-Patterns

THE CARDINAL SIN: Agent executes your code instead of figuring things out

// WRONG - You wrote the workflow, agent just executes it
tool("process_feedback", async ({ message }) => {
  const category = categorize(message);      // Your code decides
  const priority = calculatePriority(message); // Your code decides
  await store(message, category, priority);   // Your code orchestrates
  if (priority > 3) await notify();           // Your code decides
});

// RIGHT - Agent figures out how to process feedback
tools: store_item, send_message  // Primitives
prompt: "Rate importance 1-5 based on actionability, store feedback, notify if >= 4"

Workflow-shaped tools — analyze_and_organize bundles judgment into the tool. Break it into primitives and let the agent compose them.

Context starvation — Agent doesn't know what resources exist in the app.

User: "Write something about Catherine the Great in my feed"
Agent: "What feed? I don't understand what system you're referring to."

Fix: Inject available resources, capabilities, and vocabulary into system prompt.

Orphan UI actions — User can do something through the UI that the agent can't achieve. Fix: maintain parity.

Silent actions — Agent changes state but UI doesn't update. Fix: Use shared data stores with reactive binding, or file system observation.

Heuristic completion detection — Detecting agent completion through heuristics (consecutive iterations without tool calls, checking for expected output files). This is fragile. Fix: Require agents to explicitly signal completion through a complete_task tool.

Static tool mapping for dynamic APIs — Building 50 tools for 50 API endpoints when a discover + access pattern would give more flexibility.

// WRONG - Every API type needs a hardcoded tool
tool("read_steps", ...)
tool("read_heart_rate", ...)
tool("read_sleep", ...)
// When glucose tracking is added... code change required

// RIGHT - Dynamic capability discovery
tool("list_available_types", ...)  // Discover what's available
tool("read_health_data", { dataType: z.string() }, ...)  // Access any type

Incomplete CRUD — Agent can create but not update or delete.

// User: "Delete that journal entry"
// Agent: "I don't have a tool for that"
tool("create_journal_entry", ...)  // Missing: update, delete

Fix: Every entity needs full CRUD.

Sandbox isolation — Agent works in separate data space from user.

Documents/
├── user_files/        ← User's space
└── agent_output/      ← Agent's space (isolated)

Fix: Use shared workspace where both operate on same files.

Gates without reason — Domain tool is the only way to do something, and you didn't intend to restrict access. The default is open. Keep primitives available unless there's a specific reason to gate.

Artificial capability limits — Restricting what the agent can do out of vague safety concerns rather than specific risks. Be thoughtful about restricting capabilities. The agent should generally be able to do what users can do. </anti_patterns>

<success_criteria>

Success Criteria

You've built an agent-native application when:

Architecture

• [ ] The agent can achieve anything users can achieve through the UI (parity)
• [ ] Tools are atomic primitives; domain tools are shortcuts, not gates (granularity)
• [ ] New features can be added by writing new prompts (composability)
• [ ] The agent can accomplish tasks you didn't explicitly design for (emergent capability)
• [ ] Changing behavior means editing prompts, not refactoring code

Implementation

• [ ] System prompt includes dynamic context about app state
• [ ] Every UI action has a corresponding agent tool (action parity)
• [ ] Agent tools are documented in system prompt with user vocabulary
• [ ] Agent and user work in the same data space (shared workspace)
• [ ] Agent actions are immediately reflected in the UI
• [ ] Every entity has full CRUD (Create, Read, Update, Delete)
• [ ] Agents explicitly signal completion (no heuristic detection)
• [ ] context.md or equivalent for accumulated knowledge

Product

• [ ] Simple requests work immediately with no learning curve
• [ ] Power users can push the system in unexpected directions
• [ ] You're learning what users want by observing what they ask the agent to do
• [ ] Approval requirements match stakes and reversibility

Mobile (if applicable)

• [ ] Checkpoint/resume handles app interruption
• [ ] iCloud-first storage with local fallback
• [ ] Background execution uses available time wisely
• [ ] Model tier matched to task complexity

---

The Ultimate Test

Describe an outcome to the agent that's within your application's domain but that you didn't build a specific feature for.

Can it figure out how to accomplish it, operating in a loop until it succeeds?

If yes, you've built something agent-native.

If it says "I don't have a feature for that"—your architecture is still too constrained. </success_criteria>

<overview> A structured discipline for ensuring agents can do everything users can do. Every UI action should have an equivalent agent tool. This isn't a one-time check—it's an ongoing practice integrated into your development workflow.

Core principle: When adding a UI feature, add the corresponding tool in the same PR. </overview>

<why_parity>

Why Action Parity Matters

The failure case:

User: "Write something about Catherine the Great in my reading feed"
Agent: "What system are you referring to? I'm not sure what reading feed means."

The user could publish to their feed through the UI. But the agent had no publish_to_feed tool. The fix was simple—add the tool. But the insight is profound:

Every action a user can take through the UI must have an equivalent tool the agent can call.

Without this parity:

• Users ask agents to do things they can't do
• Agents ask clarifying questions about features they should understand
• The agent feels limited compared to direct app usage
• Users lose trust in the agent's capabilities

</why_parity>

<capability_mapping>

The Capability Map

Maintain a structured map of UI actions to agent tools:

Update this table whenever adding features.

Template for Your App

# Capability Map - [Your App Name]

| UI Action | UI Location | Agent Tool | System Prompt | Status |
|-----------|-------------|------------|---------------|--------|
| | | | | ⚠️ Missing |
| | | | | ✅ Done |
| | | | | 🚫 N/A |

Status meanings:

• ✅ Done: Tool exists and is documented in system prompt
• ⚠️ Missing: UI action exists but no agent equivalent
• 🚫 N/A: User-only action (e.g., biometric auth, camera capture)

</capability_mapping>

<parity_workflow>

The Action Parity Workflow

When Adding a New Feature

Before merging any PR that adds UI functionality:

1. What action is this?
   → "User can publish an insight to their reading feed"

2. Does an agent tool exist for this?
   → Check tool definitions
   → If NO: Create the tool

3. Is it documented in the system prompt?
   → Check system prompt capabilities section
   → If NO: Add documentation

4. Is the context available?
   → Does agent know what "feed" means?
   → Does agent see available books?
   → If NO: Add to context injection

5. Update the capability map
   → Add row to tracking document

PR Checklist

Add to your PR template:

## Agent-Native Checklist

- [ ] Every new UI action has a corresponding agent tool
- [ ] System prompt updated to mention new capability
- [ ] Agent has access to same data UI uses
- [ ] Capability map updated
- [ ] Tested with natural language request

</parity_workflow>

<parity_audit>

The Parity Audit

Periodically audit your app for action parity gaps:

Step 1: List All UI Actions

Walk through every screen and list what users can do:

Library Screen:
- View list of books
- Search books
- Filter by category
- Add new book
- Delete book
- Open book detail

Book Detail Screen:
- View book info
- Start research
- View highlights
- Add highlight
- Share book
- Remove from library

Feed Screen:
- View insights
- Create new insight
- Edit insight
- Delete insight
- Share insight

Settings:
- Edit profile
- Change theme
- Export data
- Delete account

Step 2: Check Tool Coverage

For each action, verify:

✅ View list of books      → read_library
✅ Search books            → read_library (with query param)
⚠️ Filter by category     → MISSING (add filter param to read_library)
⚠️ Add new book           → MISSING (need add_book tool)
✅ Delete book             → delete_book
✅ Open book detail        → read_library (single book)

✅ Start research          → start_research
✅ View highlights         → read_library (includes highlights)
⚠️ Add highlight          → MISSING (need add_highlight tool)
⚠️ Share book             → MISSING (or N/A if sharing is UI-only)

✅ View insights           → read_library (includes feed)
✅ Create new insight      → publish_to_feed
⚠️ Edit insight           → MISSING (need update_feed_item tool)
⚠️ Delete insight         → MISSING (need delete_feed_item tool)

Step 3: Prioritize Gaps

Not all gaps are equal:

High priority (users will ask for this):

• Add new book
• Create/edit/delete content
• Core workflow actions

Medium priority (occasional requests):

• Filter/search variations
• Export functionality
• Sharing features

Low priority (rarely requested via agent):

• Theme changes
• Account deletion
• Settings that are UI-preference

</parity_audit>

<tool_design_for_parity>

Designing Tools for Parity

Match Tool Granularity to UI Granularity

If the UI has separate buttons for "Edit" and "Delete", consider separate tools:

// Matches UI granularity
tool("update_feed_item", { id, content, headline }, ...);
tool("delete_feed_item", { id }, ...);

// vs. combined (harder for agent to discover)
tool("modify_feed_item", { id, action: "update" | "delete", ... }, ...);

Use User Vocabulary in Tool Names

// Good: Matches what users say
tool("publish_to_feed", ...);  // "publish to my feed"
tool("add_book", ...);         // "add this book"
tool("start_research", ...);   // "research this"

// Bad: Technical jargon
tool("create_analysis_record", ...);
tool("insert_library_item", ...);
tool("initiate_web_scrape_workflow", ...);

Return What the UI Shows

If the UI shows a confirmation with details, the tool should too:

// UI shows: "Added 'Moby Dick' to your library"
// Tool should return the same:
tool("add_book", async ({ title, author }) => {
  const book = await library.add({ title, author });
  return {
    text: `Added "${book.title}" by ${book.author} to your library (id: ${book.id})`
  };
});

</tool_design_for_parity>

<context_parity>

Context Parity

Whatever the user sees, the agent should be able to access.

The Problem

// UI shows recent analyses in a list
ForEach(analysisRecords) { record in
    AnalysisRow(record: record)
}

// But system prompt only mentions books, not analyses
let systemPrompt = """
## Available Books
\(books.map { $0.title })
// Missing: recent analyses!
"""

The user sees their reading journal. The agent doesn't. This creates a disconnect.

The Fix

// System prompt includes what UI shows
let systemPrompt = """
## Available Books
\(books.map { "- \($0.title)" }.joined(separator: "\n"))

## Recent Reading Journal
\(analysisRecords.prefix(10).map { "- \($0.summary)" }.joined(separator: "\n"))
"""

Context Parity Checklist

For each screen in your app:

• [ ] What data does this screen display?
• [ ] Is that data available to the agent?
• [ ] Can the agent access the same level of detail?

</context_parity>

<continuous_parity>

Maintaining Parity Over Time

Git Hooks / CI Checks

#!/bin/bash
# pre-commit hook: check for new UI actions without tools

# Find new SwiftUI Button/onTapGesture additions
NEW_ACTIONS=$(git diff --cached --name-only | xargs grep -l "Button\|onTapGesture")

if [ -n "$NEW_ACTIONS" ]; then
    echo "⚠️  New UI actions detected. Did you add corresponding agent tools?"
    echo "Files: $NEW_ACTIONS"
    echo ""
    echo "Checklist:"
    echo "  [ ] Agent tool exists for new action"
    echo "  [ ] System prompt documents new capability"
    echo "  [ ] Capability map updated"
fi

Automated Parity Testing

// parity.test.ts
describe('Action Parity', () => {
  const capabilityMap = loadCapabilityMap();

  for (const [action, toolName] of Object.entries(capabilityMap)) {
    if (toolName === 'N/A') continue;

    test(`${action} has agent tool: ${toolName}`, () => {
      expect(agentTools.map(t => t.name)).toContain(toolName);
    });

    test(`${toolName} is documented in system prompt`, () => {
      expect(systemPrompt).toContain(toolName);
    });
  }
});

Regular Audits

Schedule periodic reviews:

## Monthly Parity Audit

1. Review all PRs merged this month
2. Check each for new UI actions
3. Verify tool coverage
4. Update capability map
5. Test with natural language requests

</continuous_parity>

<examples>

Real Example: The Feed Gap

Before: Every Reader had a feed where insights appeared, but no agent tool to publish there.

User: "Write something about Catherine the Great in my reading feed"
Agent: "I'm not sure what system you're referring to. Could you clarify?"

Diagnosis:

• ✅ UI action: User can publish insights from the analysis view
• ❌ Agent tool: No publish_to_feed tool
• ❌ System prompt: No mention of "feed" or how to publish
• ❌ Context: Agent didn't know what "feed" meant

Fix:

// 1. Add the tool
tool("publish_to_feed",
    "Publish an insight to the user's reading feed",
    {
        bookId: z.string().describe("Book ID"),
        content: z.string().describe("The insight content"),
        headline: z.string().describe("A punchy headline")
    },
    async ({ bookId, content, headline }) => {
        await feedService.publish({ bookId, content, headline });
        return { text: `Published "${headline}" to your reading feed` };
    }
);

// 2. Update system prompt
"""
## Your Capabilities

- **Publish to Feed**: Create insights that appear in the Feed tab using `publish_to_feed`.
  Include a book_id, content, and a punchy headline.
"""

// 3. Add to context injection
"""
When the user mentions "the feed" or "reading feed", they mean the Feed tab
where insights appear. Use `publish_to_feed` to create content there.
"""

After:

User: "Write something about Catherine the Great in my reading feed"
Agent: [Uses publish_to_feed to create insight]
       "Done! I've published 'The Enlightened Empress' to your reading feed."

</examples>

<checklist>

Action Parity Checklist

For every PR with UI changes:

• [ ] Listed all new UI actions
• [ ] Verified agent tool exists for each action
• [ ] Updated system prompt with new capabilities
• [ ] Added to capability map
• [ ] Tested with natural language request

For periodic audits:

• [ ] Walked through every screen
• [ ] Listed all possible user actions
• [ ] Checked tool coverage for each
• [ ] Prioritized gaps by likelihood of user request
• [ ] Created issues for high-priority gaps

</checklist>

<overview> Agent execution patterns for building robust agent loops. This covers how agents signal completion, track partial progress for resume, select appropriate model tiers, and handle context limits. </overview>

<completion_signals>

Completion Signals

Agents need an explicit way to say "I'm done."

Anti-Pattern: Heuristic Detection

Detecting completion through heuristics is fragile:

• Consecutive iterations without tool calls
• Checking for expected output files
• Tracking "no progress" states
• Time-based timeouts

These break in edge cases and create unpredictable behavior.

Pattern: Explicit Completion Tool

Provide a complete_task tool that:

• Takes a summary of what was accomplished
• Returns a signal that stops the loop
• Works identically across all agent types

tool("complete_task", {
  summary: z.string().describe("Summary of what was accomplished"),
  status: z.enum(["success", "partial", "blocked"]).optional(),
}, async ({ summary, status = "success" }) => {
  return {
    text: summary,
    shouldContinue: false,  // Key: signals loop should stop
  };
});

The ToolResult Pattern

Structure tool results to separate success from continuation:

struct ToolResult {
    let success: Bool           // Did tool succeed?
    let output: String          // What happened?
    let shouldContinue: Bool    // Should agent loop continue?
}

// Three common cases:
extension ToolResult {
    static func success(_ output: String) -> ToolResult {
        // Tool succeeded, keep going
        ToolResult(success: true, output: output, shouldContinue: true)
    }

    static func error(_ message: String) -> ToolResult {
        // Tool failed but recoverable, agent can try something else
        ToolResult(success: false, output: message, shouldContinue: true)
    }

    static func complete(_ summary: String) -> ToolResult {
        // Task done, stop the loop
        ToolResult(success: true, output: summary, shouldContinue: false)
    }
}

Key Insight

This is different from success/failure:

• A tool can succeed AND signal stop (task complete)
• A tool can fail AND signal continue (recoverable error, try something else)

// Examples:
read_file("/missing.txt")
// → { success: false, output: "File not found", shouldContinue: true }
// Agent can try a different file or ask for clarification

complete_task("Organized all downloads into folders")
// → { success: true, output: "...", shouldContinue: false }
// Agent is done

write_file("/output.md", content)
// → { success: true, output: "Wrote file", shouldContinue: true }
// Agent keeps working toward the goal

System Prompt Guidance

Tell the agent when to complete:

## Completing Tasks

When you've accomplished the user's request:
1. Verify your work (read back files you created, check results)
2. Call `complete_task` with a summary of what you did
3. Don't keep working after the goal is achieved

If you're blocked and can't proceed:
- Call `complete_task` with status "blocked" and explain why
- Don't loop forever trying the same thing

</completion_signals>

<partial_completion>

Partial Completion

For multi-step tasks, track progress at the task level for resume capability.

Task State Tracking

enum TaskStatus {
    case pending      // Not yet started
    case inProgress   // Currently working on
    case completed    // Finished successfully
    case failed       // Couldn't complete (with reason)
    case skipped      // Intentionally not done
}

struct AgentTask {
    let id: String
    let description: String
    var status: TaskStatus
    var notes: String?  // Why it failed, what was done
}

struct AgentSession {
    var tasks: [AgentTask]

    var isComplete: Bool {
        tasks.allSatisfy { $0.status == .completed || $0.status == .skipped }
    }

    var progress: (completed: Int, total: Int) {
        let done = tasks.filter { $0.status == .completed }.count
        return (done, tasks.count)
    }
}

UI Progress Display

Show users what's happening:

Progress: 3/5 tasks complete (60%)
✅ [1] Find source materials
✅ [2] Download full text
✅ [3] Extract key passages
❌ [4] Generate summary - Error: context limit exceeded
⏳ [5] Create outline - Pending

Partial Completion Scenarios

Agent hits max iterations before finishing:

• Some tasks completed, some pending
• Checkpoint saved with current state
• Resume continues from where it left off, not from beginning

Agent fails on one task:

• Task marked .failed with error in notes
• Other tasks may continue (agent decides)
• Orchestrator doesn't automatically abort entire session

Network error mid-task:

• Current iteration throws
• Session marked .failed
• Checkpoint preserves messages up to that point
• Resume possible from checkpoint

Checkpoint Structure

struct AgentCheckpoint: Codable {
    let sessionId: String
    let agentType: String
    let messages: [Message]          // Full conversation history
    let iterationCount: Int
    let tasks: [AgentTask]           // Task state
    let customState: [String: Any]   // Agent-specific state
    let timestamp: Date

    var isValid: Bool {
        // Checkpoints expire (default 1 hour)
        Date().timeIntervalSince(timestamp) < 3600
    }
}

Resume Flow

1. On app launch, scan for valid checkpoints 2. Show user: "You have an incomplete session. Resume?" 3. On resume:

• Restore messages to conversation
• Restore task states
• Continue agent loop from where it left off

4. On dismiss:

• Delete checkpoint
• Start fresh if user tries again

</partial_completion>

<model_tier_selection>

Model Tier Selection

Different agents need different intelligence levels. Use the cheapest model that achieves the outcome.

Tier Guidelines

Implementation

enum ModelTier {
    case fast      // claude-3-haiku: Quick, cheap, simple tasks
    case balanced  // claude-sonnet: Good balance for most tasks
    case powerful  // claude-opus: Complex reasoning, synthesis

    var modelId: String {
        switch self {
        case .fast: return "claude-3-haiku-20240307"
        case .balanced: return "claude-sonnet-4-20250514"
        case .powerful: return "claude-opus-4-20250514"
        }
    }
}

struct AgentConfig {
    let name: String
    let modelTier: ModelTier
    let tools: [AgentTool]
    let systemPrompt: String
    let maxIterations: Int
}

// Examples
let researchConfig = AgentConfig(
    name: "research",
    modelTier: .balanced,
    tools: researchTools,
    systemPrompt: researchPrompt,
    maxIterations: 20
)

let quickLookupConfig = AgentConfig(
    name: "lookup",
    modelTier: .fast,
    tools: [readLibrary],
    systemPrompt: "Answer quick questions about the user's library.",
    maxIterations: 3
)

Cost Optimization Strategies

1. Start with balanced, upgrade if quality insufficient 2. Use fast tier for tool-heavy loops where each turn is simple 3. Reserve powerful tier for synthesis tasks (comparing multiple sources) 4. Consider token limits per turn to control costs 5. Cache expensive operations to avoid repeated calls </model_tier_selection>

<context_limits>

Context Limits

Agent sessions can extend indefinitely, but context windows don't. Design for bounded context from the start.

The Problem

Turn 1: User asks question → 500 tokens
Turn 2: Agent reads file → 10,000 tokens
Turn 3: Agent reads another file → 10,000 tokens
Turn 4: Agent researches → 20,000 tokens
...
Turn 10: Context window exceeded

Design Principles

1. Tools should support iterative refinement

Instead of all-or-nothing, design for summary → detail → full:

// Good: Supports iterative refinement
tool("read_file", {
  path: z.string(),
  preview: z.boolean().default(true),  // Return first 1000 chars by default
  full: z.boolean().default(false),    // Opt-in to full content
}, ...);

tool("search_files", {
  query: z.string(),
  summaryOnly: z.boolean().default(true),  // Return matches, not full files
}, ...);

2. Provide consolidation tools

Give agents a way to consolidate learnings mid-session:

tool("summarize_and_continue", {
  keyPoints: z.array(z.string()),
  nextSteps: z.array(z.string()),
}, async ({ keyPoints, nextSteps }) => {
  // Store summary, potentially truncate earlier messages
  await saveSessionSummary({ keyPoints, nextSteps });
  return { text: "Summary saved. Continuing with focus on: " + nextSteps.join(", ") };
});

3. Design for truncation

Assume the orchestrator may truncate early messages. Important context should be:

• In the system prompt (always present)
• In files (can be re-read)
• Summarized in context.md

Implementation Strategies

class AgentOrchestrator {
    let maxContextTokens = 100_000
    let targetContextTokens = 80_000  // Leave headroom

    func shouldTruncate() -> Bool {
        estimateTokens(messages) > targetContextTokens
    }

    func truncateIfNeeded() {
        if shouldTruncate() {
            // Keep system prompt + recent messages
            // Summarize or drop older messages
            messages = [systemMessage] + summarizeOldMessages() + recentMessages
        }
    }
}

System Prompt Guidance

## Managing Context

For long tasks, periodically consolidate what you've learned:
1. If you've gathered a lot of information, summarize key points
2. Save important findings to files (they persist beyond context)
3. Use `summarize_and_continue` if the conversation is getting long

Don't try to hold everything in memory. Write it down.

</context_limits>

<orchestrator_pattern>

Unified Agent Orchestrator

One execution engine, many agent types. All agents use the same orchestrator with different configurations.

class AgentOrchestrator {
    static let shared = AgentOrchestrator()

    func run(config: AgentConfig, userMessage: String) async -> AgentResult {
        var messages: [Message] = [
            .system(config.systemPrompt),
            .user(userMessage)
        ]

        var iteration = 0

        while iteration < config.maxIterations {
            // Get agent response
            let response = await claude.message(
                model: config.modelTier.modelId,
                messages: messages,
                tools: config.tools
            )

            messages.append(.assistant(response))

            // Process tool calls
            for toolCall in response.toolCalls {
                let result = await executeToolCall(toolCall, config: config)
                messages.append(.toolResult(result))

                // Check for completion signal
                if !result.shouldContinue {
                    return AgentResult(
                        status: .completed,
                        output: result.output,
                        iterations: iteration + 1
                    )
                }
            }

            // No tool calls = agent is responding, might be done
            if response.toolCalls.isEmpty {
                // Could be done, or waiting for user
                break
            }

            iteration += 1
        }

        return AgentResult(
            status: iteration >= config.maxIterations ? .maxIterations : .responded,
            output: messages.last?.content ?? "",
            iterations: iteration
        )
    }
}

Benefits

• Consistent lifecycle management across all agent types
• Automatic checkpoint/resume (critical for mobile)
• Shared tool protocol
• Easy to add new agent types
• Centralized error handling and logging

</orchestrator_pattern>

<checklist>

Agent Execution Checklist

Completion Signals

• [ ] complete_task tool provided (explicit completion)
• [ ] No heuristic completion detection
• [ ] Tool results include shouldContinue flag
• [ ] System prompt guides when to complete

Partial Completion

• [ ] Tasks tracked with status (pending, in_progress, completed, failed)
• [ ] Checkpoints saved for resume
• [ ] Progress visible to user
• [ ] Resume continues from where left off

Model Tiers

• [ ] Tier selected based on task complexity
• [ ] Cost optimization considered
• [ ] Fast tier for simple operations
• [ ] Powerful tier reserved for synthesis

Context Limits

• [ ] Tools support iterative refinement (preview vs full)
• [ ] Consolidation mechanism available
• [ ] Important context persisted to files
• [ ] Truncation strategy defined

</checklist>

<overview> Testing agent-native apps requires different approaches than traditional unit testing. You're testing whether the agent achieves outcomes, not whether it calls specific functions. This guide provides concrete testing patterns for verifying your app is truly agent-native. </overview>

<testing_philosophy>

Testing Philosophy

Test Outcomes, Not Procedures

Traditional (procedure-focused):

// Testing that a specific function was called with specific args
expect(mockProcessFeedback).toHaveBeenCalledWith({
  message: "Great app!",
  category: "praise",
  priority: 2
});

Agent-native (outcome-focused):

// Testing that the outcome was achieved
const result = await agent.process("Great app!");
const storedFeedback = await db.feedback.getLatest();

expect(storedFeedback.content).toContain("Great app");
expect(storedFeedback.importance).toBeGreaterThanOrEqual(1);
expect(storedFeedback.importance).toBeLessThanOrEqual(5);
// We don't care exactly how it categorized—just that it's reasonable

Accept Variability

Agents may solve problems differently each time. Your tests should:

• Verify the end state, not the path
• Accept reasonable ranges, not exact values
• Check for presence of required elements, not exact format

</testing_philosophy>

<can_agent_do_it_test>

The "Can Agent Do It?" Test

For each UI feature, write a test prompt and verify the agent can accomplish it.

Template

describe('Agent Capability Tests', () => {
  test('Agent can add a book to library', async () => {
    const result = await agent.chat("Add 'Moby Dick' by Herman Melville to my library");

    // Verify outcome
    const library = await libraryService.getBooks();
    const mobyDick = library.find(b => b.title.includes("Moby Dick"));

    expect(mobyDick).toBeDefined();
    expect(mobyDick.author).toContain("Melville");
  });

  test('Agent can publish to feed', async () => {
    // Setup: ensure a book exists
    await libraryService.addBook({ id: "book_123", title: "1984" });

    const result = await agent.chat("Write something about surveillance themes in my feed");

    // Verify outcome
    const feed = await feedService.getItems();
    const newItem = feed.find(item => item.bookId === "book_123");

    expect(newItem).toBeDefined();
    expect(newItem.content.toLowerCase()).toMatch(/surveillance|watching|control/);
  });

  test('Agent can search and save research', async () => {
    await libraryService.addBook({ id: "book_456", title: "Moby Dick" });

    const result = await agent.chat("Research whale symbolism in Moby Dick");

    // Verify files were created
    const files = await fileService.listFiles("Research/book_456/");
    expect(files.length).toBeGreaterThan(0);

    // Verify content is relevant
    const content = await fileService.readFile(files[0]);
    expect(content.toLowerCase()).toMatch(/whale|symbolism|melville/);
  });
});

The "Write to Location" Test

A key litmus test: can the agent create content in specific app locations?

describe('Location Awareness Tests', () => {
  const locations = [
    { userPhrase: "my reading feed", expectedTool: "publish_to_feed" },
    { userPhrase: "my library", expectedTool: "add_book" },
    { userPhrase: "my research folder", expectedTool: "write_file" },
    { userPhrase: "my profile", expectedTool: "write_file" },
  ];

  for (const { userPhrase, expectedTool } of locations) {
    test(`Agent knows how to write to "${userPhrase}"`, async () => {
      const prompt = `Write a test note to ${userPhrase}`;
      const result = await agent.chat(prompt);

      // Check that agent used the right tool (or achieved the outcome)
      expect(result.toolCalls).toContainEqual(
        expect.objectContaining({ name: expectedTool })
      );

      // Or verify outcome directly
      // expect(await locationHasNewContent(userPhrase)).toBe(true);
    });
  }
});

</can_agent_do_it_test>

<surprise_test>

The "Surprise Test"

A well-designed agent-native app lets the agent figure out creative approaches. Test this by giving open-ended requests.

The Test

describe('Agent Creativity Tests', () => {
  test('Agent can handle open-ended requests', async () => {
    // Setup: user has some books
    await libraryService.addBook({ id: "1", title: "1984", author: "Orwell" });
    await libraryService.addBook({ id: "2", title: "Brave New World", author: "Huxley" });
    await libraryService.addBook({ id: "3", title: "Fahrenheit 451", author: "Bradbury" });

    // Open-ended request
    const result = await agent.chat("Help me organize my reading for next month");

    // The agent should do SOMETHING useful
    // We don't specify exactly what—that's the point
    expect(result.toolCalls.length).toBeGreaterThan(0);

    // It should have engaged with the library
    const libraryTools = ["read_library", "write_file", "publish_to_feed"];
    const usedLibraryTool = result.toolCalls.some(
      call => libraryTools.includes(call.name)
    );
    expect(usedLibraryTool).toBe(true);
  });

  test('Agent finds creative solutions', async () => {
    // Don't specify HOW to accomplish the task
    const result = await agent.chat(
      "I want to understand the dystopian themes across my sci-fi books"
    );

    // Agent might:
    // - Read all books and create a comparison document
    // - Research dystopian literature and relate it to user's books
    // - Create a mind map in a markdown file
    // - Publish a series of insights to the feed

    // We just verify it did something substantive
    expect(result.response.length).toBeGreaterThan(100);
    expect(result.toolCalls.length).toBeGreaterThan(0);
  });
});

What Failure Looks Like

// FAILURE: Agent can only say it can't do that
const result = await agent.chat("Help me prepare for a book club discussion");

// Bad outcome:
expect(result.response).not.toContain("I can't");
expect(result.response).not.toContain("I don't have a tool");
expect(result.response).not.toContain("Could you clarify");

// If the agent asks for clarification on something it should understand,
// you have a context injection or capability gap

</surprise_test>

<parity_testing>

Automated Parity Testing

Ensure every UI action has an agent equivalent.

Capability Map Testing

// capability-map.ts
export const capabilityMap = {
  // UI Action: Agent Tool
  "View library": "read_library",
  "Add book": "add_book",
  "Delete book": "delete_book",
  "Publish insight": "publish_to_feed",
  "Start research": "start_research",
  "View highlights": "read_library",  // same tool, different query
  "Edit profile": "write_file",
  "Search web": "web_search",
  "Export data": "N/A",  // UI-only action
};

// parity.test.ts
import { capabilityMap } from './capability-map';
import { getAgentTools } from './agent-config';
import { getSystemPrompt } from './system-prompt';

describe('Action Parity', () => {
  const agentTools = getAgentTools();
  const systemPrompt = getSystemPrompt();

  for (const [uiAction, toolName] of Object.entries(capabilityMap)) {
    if (toolName === 'N/A') continue;

    test(`"${uiAction}" has agent tool: ${toolName}`, () => {
      const toolNames = agentTools.map(t => t.name);
      expect(toolNames).toContain(toolName);
    });

    test(`${toolName} is documented in system prompt`, () => {
      expect(systemPrompt).toContain(toolName);
    });
  }
});

Context Parity Testing

describe('Context Parity', () => {
  test('Agent sees all data that UI shows', async () => {
    // Setup: create some data
    await libraryService.addBook({ id: "1", title: "Test Book" });
    await feedService.addItem({ id: "f1", content: "Test insight" });

    // Get system prompt (which includes context)
    const systemPrompt = await buildSystemPrompt();

    // Verify data is included
    expect(systemPrompt).toContain("Test Book");
    expect(systemPrompt).toContain("Test insight");
  });

  test('Recent activity is visible to agent', async () => {
    // Perform some actions
    await activityService.log({ action: "highlighted", bookId: "1" });
    await activityService.log({ action: "researched", bookId: "2" });

    const systemPrompt = await buildSystemPrompt();

    // Verify activity is included
    expect(systemPrompt).toMatch(/highlighted|researched/);
  });
});

</parity_testing>

<integration_testing>

Integration Testing

Test the full flow from user request to outcome.

End-to-End Flow Tests

describe('End-to-End Flows', () => {
  test('Research flow: request → web search → file creation', async () => {
    // Setup
    const bookId = "book_123";
    await libraryService.addBook({ id: bookId, title: "Moby Dick" });

    // User request
    await agent.chat("Research the historical context of whaling in Moby Dick");

    // Verify: web search was performed
    const searchCalls = mockWebSearch.mock.calls;
    expect(searchCalls.length).toBeGreaterThan(0);
    expect(searchCalls.some(call =>
      call[0].query.toLowerCase().includes("whaling")
    )).toBe(true);

    // Verify: files were created
    const researchFiles = await fileService.listFiles(`Research/${bookId}/`);
    expect(researchFiles.length).toBeGreaterThan(0);

    // Verify: content is relevant
    const content = await fileService.readFile(researchFiles[0]);
    expect(content.toLowerCase()).toMatch(/whale|whaling|nantucket|melville/);
  });

  test('Publish flow: request → tool call → feed update → UI reflects', async () => {
    // Setup
    await libraryService.addBook({ id: "book_1", title: "1984" });

    // Initial state
    const feedBefore = await feedService.getItems();

    // User request
    await agent.chat("Write something about Big Brother for my reading feed");

    // Verify feed updated
    const feedAfter = await feedService.getItems();
    expect(feedAfter.length).toBe(feedBefore.length + 1);

    // Verify content
    const newItem = feedAfter.find(item =>
      !feedBefore.some(old => old.id === item.id)
    );
    expect(newItem).toBeDefined();
    expect(newItem.content.toLowerCase()).toMatch(/big brother|surveillance|watching/);
  });
});

Failure Recovery Tests

describe('Failure Recovery', () => {
  test('Agent handles missing book gracefully', async () => {
    const result = await agent.chat("Tell me about 'Nonexistent Book'");

    // Agent should not crash
    expect(result.error).toBeUndefined();

    // Agent should acknowledge the issue
    expect(result.response.toLowerCase()).toMatch(
      /not found|don't see|can't find|library/
    );
  });

  test('Agent recovers from API failure', async () => {
    // Mock API failure
    mockWebSearch.mockRejectedValueOnce(new Error("Network error"));

    const result = await agent.chat("Research this topic");

    // Agent should handle gracefully
    expect(result.error).toBeUndefined();
    expect(result.response).not.toContain("unhandled exception");

    // Agent should communicate the issue
    expect(result.response.toLowerCase()).toMatch(
      /couldn't search|unable to|try again/
    );
  });
});

</integration_testing>

<snapshot_testing>

Snapshot Testing for System Prompts

Track changes to system prompts and context injection over time.

describe('System Prompt Stability', () => {
  test('System prompt structure matches snapshot', async () => {
    const systemPrompt = await buildSystemPrompt();

    // Extract structure (removing dynamic data)
    const structure = systemPrompt
      .replace(/id: \w+/g, 'id: [ID]')
      .replace(/"[^"]+"/g, '"[TITLE]"')
      .replace(/\d{4}-\d{2}-\d{2}/g, '[DATE]');

    expect(structure).toMatchSnapshot();
  });

  test('All capability sections are present', async () => {
    const systemPrompt = await buildSystemPrompt();

    const requiredSections = [
      "Your Capabilities",
      "Available Books",
      "Recent Activity",
    ];

    for (const section of requiredSections) {
      expect(systemPrompt).toContain(section);
    }
  });
});

</snapshot_testing>

<manual_testing>

Manual Testing Checklist

Some things are best tested manually during development:

Natural Language Variation Test

Try multiple phrasings for the same request:

"Add this to my feed"
"Write something in my reading feed"
"Publish an insight about this"
"Put this in the feed"
"I want this in my feed"

All should work if context injection is correct.

Edge Case Prompts

"What can you do?"
→ Agent should describe capabilities

"Help me with my books"
→ Agent should engage with library, not ask what "books" means

"Write something"
→ Agent should ask WHERE (feed, file, etc.) if not clear

"Delete everything"
→ Agent should confirm before destructive actions

Confusion Test

Ask about things that should exist but might not be properly connected:

"What's in my research folder?"
→ Should list files, not ask "what research folder?"

"Show me my recent reading"
→ Should show activity, not ask "what do you mean?"

"Continue where I left off"
→ Should reference recent activity if available

</manual_testing>

<ci_integration>

CI/CD Integration

Add agent-native tests to your CI pipeline:

# .github/workflows/test.yml
name: Agent-Native Tests

on: [push, pull_request]

jobs:
  agent-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup
        run: npm install

      - name: Run Parity Tests
        run: npm run test:parity

      - name: Run Capability Tests
        run: npm run test:capabilities
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Check System Prompt Completeness
        run: npm run test:system-prompt

      - name: Verify Capability Map
        run: |
          # Ensure capability map is up to date
          npm run generate:capability-map
          git diff --exit-code capability-map.ts

Cost-Aware Testing

Agent tests cost API tokens. Strategies to manage:

// Use smaller models for basic tests
const testConfig = {
  model: process.env.CI ? "claude-3-haiku" : "claude-3-opus",
  maxTokens: 500,  // Limit output length
};

// Cache responses for deterministic tests
const cachedAgent = new CachedAgent({
  cacheDir: ".test-cache",
  ttl: 24 * 60 * 60 * 1000,  // 24 hours
});

// Run expensive tests only on main branch
if (process.env.GITHUB_REF === 'refs/heads/main') {
  describe('Full Integration Tests', () => { ... });
}

</ci_integration>

<test_utilities>

Test Utilities

Agent Test Harness

class AgentTestHarness {
  private agent: Agent;
  private mockServices: MockServices;

  async setup() {
    this.mockServices = createMockServices();
    this.agent = await createAgent({
      services: this.mockServices,
      model: "claude-3-haiku",  // Cheaper for tests
    });
  }

  async chat(message: string): Promise<AgentResponse> {
    return this.agent.chat(message);
  }

  async expectToolCall(toolName: string) {
    const lastResponse = this.agent.getLastResponse();
    expect(lastResponse.toolCalls.map(t => t.name)).toContain(toolName);
  }

  async expectOutcome(check: () => Promise<boolean>) {
    const result = await check();
    expect(result).toBe(true);
  }

  getState() {
    return {
      library: this.mockServices.library.getBooks(),
      feed: this.mockServices.feed.getItems(),
      files: this.mockServices.files.listAll(),
    };
  }
}

// Usage
test('full flow', async () => {
  const harness = new AgentTestHarness();
  await harness.setup();

  await harness.chat("Add 'Moby Dick' to my library");
  await harness.expectToolCall("add_book");
  await harness.expectOutcome(async () => {
    const state = harness.getState();
    return state.library.some(b => b.title.includes("Moby"));
  });
});

</test_utilities>

<checklist>

Testing Checklist

Automated Tests:

• [ ] "Can Agent Do It?" tests for each UI action
• [ ] Location awareness tests ("write to my feed")
• [ ] Parity tests (tool exists, documented in prompt)
• [ ] Context parity tests (agent sees what UI shows)
• [ ] End-to-end flow tests
• [ ] Failure recovery tests

Manual Tests:

• [ ] Natural language variation (multiple phrasings work)
• [ ] Edge case prompts (open-ended requests)
• [ ] Confusion test (agent knows app vocabulary)
• [ ] Surprise test (agent can be creative)

CI Integration:

• [ ] Parity tests run on every PR
• [ ] Capability tests run with API key
• [ ] System prompt completeness check
• [ ] Capability map drift detection

</checklist>

<overview> Architectural patterns for building agent-native systems. These patterns emerge from the five core principles: Parity, Granularity, Composability, Emergent Capability, and Improvement Over Time.

Features are outcomes achieved by agents operating in a loop, not functions you write. Tools are atomic primitives. The agent applies judgment; the prompt defines the outcome.

See also:

• files-universal-interface.md for file organization and context.md patterns
• agent-execution-patterns.md for completion signals and partial completion
• product-implications.md for progressive disclosure and approval patterns

</overview>

<pattern name="event-driven-agent">

Event-Driven Agent Architecture

The agent runs as a long-lived process that responds to events. Events become prompts.

┌─────────────────────────────────────────────────────────────┐
│                    Agent Loop                                │
├─────────────────────────────────────────────────────────────┤
│  Event Source → Agent (Claude) → Tool Calls → Response      │
└─────────────────────────────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
    ┌─────────┐    ┌──────────┐    ┌───────────┐
    │ Content │    │   Self   │    │   Data    │
    │  Tools  │    │  Tools   │    │   Tools   │
    └─────────┘    └──────────┘    └───────────┘
    (write_file)   (read_source)   (store_item)
                   (restart)       (list_items)

Key characteristics:

• Events (messages, webhooks, timers) trigger agent turns
• Agent decides how to respond based on system prompt
• Tools are primitives for IO, not business logic
• State persists between events via data tools

Example: Discord feedback bot

// Event source
client.on("messageCreate", (message) => {
  if (!message.author.bot) {
    runAgent({
      userMessage: `New message from ${message.author}: "${message.content}"`,
      channelId: message.channelId,
    });
  }
});

// System prompt defines behavior
const systemPrompt = `
When someone shares feedback:
1. Acknowledge their feedback warmly
2. Ask clarifying questions if needed
3. Store it using the feedback tools
4. Update the feedback site

Use your judgment about importance and categorization.
`;

</pattern>

<pattern name="two-layer-git">

Two-Layer Git Architecture

For self-modifying agents, separate code (shared) from data (instance-specific).

┌─────────────────────────────────────────────────────────────┐
│                     GitHub (shared repo)                     │
│  - src/           (agent code)                              │
│  - site/          (web interface)                           │
│  - package.json   (dependencies)                            │
│  - .gitignore     (excludes data/, logs/)                   │
└─────────────────────────────────────────────────────────────┘
                          │
                     git clone
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                  Instance (Server)                           │
│                                                              │
│  FROM GITHUB (tracked):                                      │
│  - src/           → pushed back on code changes             │
│  - site/          → pushed, triggers deployment             │
│                                                              │
│  LOCAL ONLY (untracked):                                     │
│  - data/          → instance-specific storage               │
│  - logs/          → runtime logs                            │
│  - .env           → secrets                                 │
└─────────────────────────────────────────────────────────────┘

Why this works:

• Code and site are version controlled (GitHub)
• Raw data stays local (instance-specific)
• Site is generated from data, so reproducible
• Automatic rollback via git history

</pattern>

<pattern name="multi-instance">

Multi-Instance Branching

Each agent instance gets its own branch while sharing core code.

main                        # Shared features, bug fixes
├── instance/feedback-bot   # Every Reader feedback bot
├── instance/support-bot    # Customer support bot
└── instance/research-bot   # Research assistant

Change flow:

Sync tools:

tool("self_deploy", "Pull latest from main, rebuild, restart", ...)
tool("sync_from_instance", "Merge from another instance", ...)
tool("propose_to_main", "Create PR to share improvements", ...)

</pattern>

<pattern name="site-as-output">

Site as Agent Output

The agent generates and maintains a website as a natural output, not through specialized site tools.

Discord Message
      ↓
Agent processes it, extracts insights
      ↓
Agent decides what site updates are needed
      ↓
Agent writes files using write_file primitive
      ↓
Git commit + push triggers deployment
      ↓
Site updates automatically

Key insight: Don't build site generation tools. Give the agent file tools and teach it in the prompt how to create good sites.

## Site Management

You maintain a public feedback site. When feedback comes in:
1. Use write_file to update site/public/content/feedback.json
2. If the site's React components need improvement, modify them
3. Commit changes and push to trigger Vercel deploy

The site should be:
- Clean, modern dashboard aesthetic
- Clear visual hierarchy
- Status organization (Inbox, Active, Done)

You decide the structure. Make it good.

</pattern>

<pattern name="approval-gates">

Approval Gates Pattern

Separate "propose" from "apply" for dangerous operations.

// Pending changes stored separately
const pendingChanges = new Map<string, string>();

tool("write_file", async ({ path, content }) => {
  if (requiresApproval(path)) {
    // Store for approval
    pendingChanges.set(path, content);
    const diff = generateDiff(path, content);
    return {
      text: `Change requires approval.\n\n${diff}\n\nReply "yes" to apply.`
    };
  } else {
    // Apply immediately
    writeFileSync(path, content);
    return { text: `Wrote ${path}` };
  }
});

tool("apply_pending", async () => {
  for (const [path, content] of pendingChanges) {
    writeFileSync(path, content);
  }
  pendingChanges.clear();
  return { text: "Applied all pending changes" };
});

What requires approval:

• src/*.ts (agent code)
• package.json (dependencies)
• system prompt changes

What doesn't:

• data/* (instance data)
• site/* (generated content)
• docs/* (documentation)

</pattern>

<pattern name="unified-agent-architecture">

Unified Agent Architecture

One execution engine, many agent types. All agents use the same orchestrator but with different configurations.

┌─────────────────────────────────────────────────────────────┐
│                    AgentOrchestrator                         │
├─────────────────────────────────────────────────────────────┤
│  - Lifecycle management (start, pause, resume, stop)        │
│  - Checkpoint/restore (for background execution)            │
│  - Tool execution                                            │
│  - Chat integration                                          │
└─────────────────────────────────────────────────────────────┘
          │                    │                    │
    ┌─────┴─────┐        ┌─────┴─────┐        ┌─────┴─────┐
    │ Research  │        │   Chat    │        │  Profile  │
    │   Agent   │        │   Agent   │        │   Agent   │
    └───────────┘        └───────────┘        └───────────┘
    - web_search         - read_library       - read_photos
    - write_file         - publish_to_feed    - write_file
    - read_file          - web_search         - analyze_image

Implementation:

// All agents use the same orchestrator
let session = try await AgentOrchestrator.shared.startAgent(
    config: ResearchAgent.create(book: book),  // Config varies
    tools: ResearchAgent.tools,                 // Tools vary
    context: ResearchAgent.context(for: book)   // Context varies
)

// Agent types define their own configuration
struct ResearchAgent {
    static var tools: [AgentTool] {
        [
            FileTools.readFile(),
            FileTools.writeFile(),
            WebTools.webSearch(),
            WebTools.webFetch(),
        ]
    }

    static func context(for book: Book) -> String {
        """
        You are researching "\(book.title)" by \(book.author).
        Save findings to Documents/Research/\(book.id)/
        """
    }
}

struct ChatAgent {
    static var tools: [AgentTool] {
        [
            FileTools.readFile(),
            FileTools.writeFile(),
            BookTools.readLibrary(),
            BookTools.publishToFeed(),  // Chat can publish directly
            WebTools.webSearch(),
        ]
    }

    static func context(library: [Book]) -> String {
        """
        You help the user with their reading.
        Available books: \(library.map { $0.title }.joined(separator: ", "))
        """
    }
}

Benefits:

• Consistent lifecycle management across all agent types
• Automatic checkpoint/resume (critical for mobile)
• Shared tool protocol
• Easy to add new agent types
• Centralized error handling and logging

</pattern>

<pattern name="agent-to-ui-communication">

Agent-to-UI Communication

When agents take actions, the UI should reflect them immediately. The user should see what the agent did.

Pattern 1: Shared Data Store (Recommended)

Agent writes through the same service the UI observes:

// Shared service
class BookLibraryService: ObservableObject {
    static let shared = BookLibraryService()
    @Published var books: [Book] = []
    @Published var feedItems: [FeedItem] = []

    func addFeedItem(_ item: FeedItem) {
        feedItems.append(item)
        persist()
    }
}

// Agent tool writes through shared service
tool("publish_to_feed", async ({ bookId, content, headline }) => {
    let item = FeedItem(bookId: bookId, content: content, headline: headline)
    BookLibraryService.shared.addFeedItem(item)  // Same service UI uses
    return { text: "Published to feed" }
})

// UI observes the same service
struct FeedView: View {
    @StateObject var library = BookLibraryService.shared

    var body: some View {
        List(library.feedItems) { item in
            FeedItemRow(item: item)
            // Automatically updates when agent adds items
        }
    }
}

Pattern 2: File System Observation

For file-based data, watch the file system:

class ResearchWatcher: ObservableObject {
    @Published var files: [URL] = []
    private var watcher: DirectoryWatcher?

    func watch(bookId: String) {
        let path = documentsURL.appendingPathComponent("Research/\(bookId)")

        watcher = DirectoryWatcher(path: path) { [weak self] in
            self?.reload(from: path)
        }

        reload(from: path)
    }
}

// Agent writes files
tool("write_file", { path, content }) -> {
    writeFile(documentsURL.appendingPathComponent(path), content)
    // DirectoryWatcher triggers UI update automatically
}

Pattern 3: Event Bus (Cross-Component)

For complex apps with multiple independent components:

// Shared event bus
const agentEvents = new EventEmitter();

// Agent tool emits events
tool("publish_to_feed", async ({ content }) => {
    const item = await feedService.add(content);
    agentEvents.emit('feed:new-item', item);
    return { text: "Published" };
});

// UI components subscribe
function FeedView() {
    const [items, setItems] = useState([]);

    useEffect(() => {
        const handler = (item) => setItems(prev => [...prev, item]);
        agentEvents.on('feed:new-item', handler);
        return () => agentEvents.off('feed:new-item', handler);
    }, []);

    return <FeedList items={items} />;
}

What to avoid:

// BAD: UI doesn't observe agent changes
// Agent writes to database directly
tool("publish_to_feed", { content }) {
    database.insert("feed", content)  // UI doesn't see this
}

// UI loads once at startup, never refreshes
struct FeedView: View {
    let items = database.query("feed")  // Stale!
}

</pattern>

<pattern name="model-tier-selection">

Model Tier Selection

Different agents need different intelligence levels. Use the cheapest model that achieves the outcome.

Implementation:

enum ModelTier {
    case fast      // claude-3-haiku: Quick, cheap, simple tasks
    case balanced  // claude-3-sonnet: Good balance for most tasks
    case powerful  // claude-3-opus: Complex reasoning, synthesis
}

struct AgentConfig {
    let modelTier: ModelTier
    let tools: [AgentTool]
    let systemPrompt: String
}

// Research agent: balanced tier
let researchConfig = AgentConfig(
    modelTier: .balanced,
    tools: researchTools,
    systemPrompt: researchPrompt
)

// Profile analysis: powerful tier (complex photo interpretation)
let profileConfig = AgentConfig(
    modelTier: .powerful,
    tools: profileTools,
    systemPrompt: profilePrompt
)

// Quick lookup: fast tier
let lookupConfig = AgentConfig(
    modelTier: .fast,
    tools: [readLibrary],
    systemPrompt: "Answer quick questions about the user's library."
)

Cost optimization strategies:

• Start with balanced tier, only upgrade if quality insufficient
• Use fast tier for tool-heavy loops where each turn is simple
• Reserve powerful tier for synthesis tasks (comparing multiple sources)
• Consider token limits per turn to control costs

</pattern>

<design_questions>

Questions to Ask When Designing

1. What events trigger agent turns? (messages, webhooks, timers, user requests) 2. What primitives does the agent need? (read, write, call API, restart) 3. What decisions should the agent make? (format, structure, priority, action) 4. What decisions should be hardcoded? (security boundaries, approval requirements) 5. How does the agent verify its work? (health checks, build verification) 6. How does the agent recover from mistakes? (git rollback, approval gates) 7. How does the UI know when agent changes state? (shared store, file watching, events) 8. What model tier does each agent type need? (fast, balanced, powerful) 9. How do agents share infrastructure? (unified orchestrator, shared tools) </design_questions>

<overview> How to inject dynamic runtime context into agent system prompts. The agent needs to know what exists in the app to know what it can work with. Static prompts aren't enough—the agent needs to see the same context the user sees.

Core principle: The user's context IS the agent's context. </overview>

<why_context_matters>

Why Dynamic Context Injection?

A static system prompt tells the agent what it CAN do. Dynamic context tells it what it can do RIGHT NOW with the user's actual data.

The failure case:

User: "Write a little thing about Catherine the Great in my reading feed"
Agent: "What system are you referring to? I'm not sure what reading feed means."

The agent failed because it didn't know:

• What books exist in the user's library
• What the "reading feed" is
• What tools it has to publish there

The fix: Inject runtime context about app state into the system prompt. </why_context_matters>

<pattern name="context-injection">

The Context Injection Pattern

Build your system prompt dynamically, including current app state:

func buildSystemPrompt() -> String {
    // Gather current state
    let availableBooks = libraryService.books
    let recentActivity = analysisService.recentRecords(limit: 10)
    let userProfile = profileService.currentProfile

    return """
    # Your Identity

    You are a reading assistant for \(userProfile.name)'s library.

    ## Available Books in User's Library

    \(availableBooks.map { "- \"\($0.title)\" by \($0.author) (id: \($0.id))" }.joined(separator: "\n"))

    ## Recent Reading Activity

    \(recentActivity.map { "- Analyzed \"\($0.bookTitle)\": \($0.excerptPreview)" }.joined(separator: "\n"))

    ## Your Capabilities

    - **publish_to_feed**: Create insights that appear in the Feed tab
    - **read_library**: View books, highlights, and analyses
    - **web_search**: Search the internet for research
    - **write_file**: Save research to Documents/Research/{bookId}/

    When the user mentions "the feed" or "reading feed", they mean the Feed tab
    where insights appear. Use `publish_to_feed` to create content there.
    """
}

</pattern>

<what_to_inject>

What Context to Inject

1. Available Resources

What data/files exist that the agent can access?

## Available in User's Library

Books:
- "Moby Dick" by Herman Melville (id: book_123)
- "1984" by George Orwell (id: book_456)

Research folders:
- Documents/Research/book_123/ (3 files)
- Documents/Research/book_456/ (1 file)

2. Current State

What has the user done recently? What's the current context?

## Recent Activity

- 2 hours ago: Highlighted passage in "1984" about surveillance
- Yesterday: Completed research on "Moby Dick" whale symbolism
- This week: Added 3 new books to library

3. Capabilities Mapping

What tool maps to what UI feature? Use the user's language.

## What You Can Do

| User Says | You Should Use | Result |
|-----------|----------------|--------|
| "my feed" / "reading feed" | `publish_to_feed` | Creates insight in Feed tab |
| "my library" / "my books" | `read_library` | Shows their book collection |
| "research this" | `web_search` + `write_file` | Saves to Research folder |
| "my profile" | `read_file("profile.md")` | Shows reading profile |

4. Domain Vocabulary

Explain app-specific terms the user might use.

## Vocabulary

- **Feed**: The Feed tab showing reading insights and analyses
- **Research folder**: Documents/Research/{bookId}/ where research is stored
- **Reading profile**: A markdown file describing user's reading preferences
- **Highlight**: A passage the user marked in a book

</what_to_inject>

<implementation_patterns>

Implementation Patterns

Pattern 1: Service-Based Injection (Swift/iOS)

class AgentContextBuilder {
    let libraryService: BookLibraryService
    let profileService: ReadingProfileService
    let activityService: ActivityService

    func buildContext() -> String {
        let books = libraryService.books
        let profile = profileService.currentProfile
        let activity = activityService.recent(limit: 10)

        return """
        ## Library (\(books.count) books)
        \(formatBooks(books))

        ## Profile
        \(profile.summary)

        ## Recent Activity
        \(formatActivity(activity))
        """
    }

    private func formatBooks(_ books: [Book]) -> String {
        books.map { "- \"\($0.title)\" (id: \($0.id))" }.joined(separator: "\n")
    }
}

// Usage in agent initialization
let context = AgentContextBuilder(
    libraryService: .shared,
    profileService: .shared,
    activityService: .shared
).buildContext()

let systemPrompt = basePrompt + "\n\n" + context

Pattern 2: Hook-Based Injection (TypeScript)

interface ContextProvider {
  getContext(): Promise<string>;
}

class LibraryContextProvider implements ContextProvider {
  async getContext(): Promise<string> {
    const books = await db.books.list();
    const recent = await db.activity.recent(10);

    return `
## Library
${books.map(b => `- "${b.title}" (${b.id})`).join('\n')}

## Recent
${recent.map(r => `- ${r.description}`).join('\n')}
    `.trim();
  }
}

// Compose multiple providers
async function buildSystemPrompt(providers: ContextProvider[]): Promise<string> {
  const contexts = await Promise.all(providers.map(p => p.getContext()));
  return [BASE_PROMPT, ...contexts].join('\n\n');
}

Pattern 3: Template-Based Injection

# System Prompt Template (system-prompt.template.md)

You are a reading assistant.

## Available Books

{{#each books}}
- "{{title}}" by {{author}} (id: {{id}})
{{/each}}

## Capabilities

{{#each capabilities}}
- **{{name}}**: {{description}}
{{/each}}

## Recent Activity

{{#each recentActivity}}
- {{timestamp}}: {{description}}
{{/each}}

// Render at runtime
const prompt = Handlebars.compile(template)({
  books: await libraryService.getBooks(),
  capabilities: getCapabilities(),
  recentActivity: await activityService.getRecent(10),
});

</implementation_patterns>

<context_freshness>

Context Freshness

Context should be injected at agent initialization, and optionally refreshed during long sessions.

At initialization:

// Always inject fresh context when starting an agent
func startChatAgent() async -> AgentSession {
    let context = await buildCurrentContext()  // Fresh context
    return await AgentOrchestrator.shared.startAgent(
        config: ChatAgent.config,
        systemPrompt: basePrompt + context
    )
}

During long sessions (optional):

// For long-running agents, provide a refresh tool
tool("refresh_context", "Get current app state") { _ in
    let books = libraryService.books
    let recent = activityService.recent(10)
    return """
    Current library: \(books.count) books
    Recent: \(recent.map { $0.summary }.joined(separator: ", "))
    """
}

What NOT to do:

// DON'T: Use stale context from app launch
let cachedContext = appLaunchContext  // Stale!
// Books may have been added, activity may have changed

</context_freshness>

<examples>

Real-World Example: Every Reader

The Every Reader app injects context for its chat agent:

func getChatAgentSystemPrompt() -> String {
    // Get current library state
    let books = BookLibraryService.shared.books
    let analyses = BookLibraryService.shared.analysisRecords.prefix(10)
    let profile = ReadingProfileService.shared.getProfileForSystemPrompt()

    let bookList = books.map { book in
        "- \"\(book.title)\" by \(book.author) (id: \(book.id))"
    }.joined(separator: "\n")

    let recentList = analyses.map { record in
        let title = books.first { $0.id == record.bookId }?.title ?? "Unknown"
        return "- From \"\(title)\": \"\(record.excerptPreview)\""
    }.joined(separator: "\n")

    return """
    # Reading Assistant

    You help the user with their reading and book research.

    ## Available Books in User's Library

    \(bookList.isEmpty ? "No books yet." : bookList)

    ## Recent Reading Journal (Latest Analyses)

    \(recentList.isEmpty ? "No analyses yet." : recentList)

    ## Reading Profile

    \(profile)

    ## Your Capabilities

    - **Publish to Feed**: Create insights using `publish_to_feed` that appear in the Feed tab
    - **Library Access**: View books and highlights using `read_library`
    - **Research**: Search web and save to Documents/Research/{bookId}/
    - **Profile**: Read/update the user's reading profile

    When the user asks you to "write something for their feed" or "add to my reading feed",
    use the `publish_to_feed` tool with the relevant book_id.
    """
}

Result: When user says "write a little thing about Catherine the Great in my reading feed", the agent: 1. Sees "reading feed" → knows to use publish_to_feed 2. Sees available books → finds the relevant book ID 3. Creates appropriate content for the Feed tab </examples>

<checklist>

Context Injection Checklist

Before launching an agent:

• [ ] System prompt includes current resources (books, files, data)
• [ ] Recent activity is visible to the agent
• [ ] Capabilities are mapped to user vocabulary
• [ ] Domain-specific terms are explained
• [ ] Context is fresh (gathered at agent start, not cached)

When adding new features:

• [ ] New resources are included in context injection
• [ ] New capabilities are documented in system prompt
• [ ] User vocabulary for the feature is mapped

</checklist>

<overview> Files are the universal interface for agent-native applications. Agents are naturally fluent with file operations—they already know how to read, write, and organize files. This document covers why files work so well, how to organize them, and the context.md pattern for accumulated knowledge. </overview>

<why_files>

Why Files

Agents are naturally good at files. Claude Code works because bash + filesystem is the most battle-tested agent interface. When building agent-native apps, lean into this.

Agents Already Know How

You don't need to teach the agent your API—it already knows cat, grep, mv, mkdir. File operations are the primitives it's most fluent with.

Files Are Inspectable

Users can see what the agent created, edit it, move it, delete it. No black box. Complete transparency into agent behavior.

Files Are Portable

Export is trivial. Backup is trivial. Users own their data. No vendor lock-in, no complex migration paths.

App State Stays in Sync

On mobile, if you use the file system with iCloud, all devices share the same file system. The agent's work on one device appears on all devices—without you having to build a server.

Directory Structure Is Information Architecture

The filesystem gives you hierarchy for free. /projects/acme/notes/ is self-documenting in a way that SELECT * FROM notes WHERE project_id = 123 isn't. </why_files>

<file_organization>

File Organization Patterns

Needs validation: These conventions are one approach that's worked so far, not a prescription. Better solutions should be considered.

A general principle of agent-native design: Design for what agents can reason about. The best proxy for that is what would make sense to a human. If a human can look at your file structure and understand what's going on, an agent probably can too.

Entity-Scoped Directories

Organize files around entities, not actors or file types:

{entity_type}/{entity_id}/
├── primary content
├── metadata
└── related materials

Example: Research/books/{bookId}/ contains everything about one book—full text, notes, sources, agent logs.

Naming Conventions

Directory Naming

• Entity-scoped: {entityType}/{entityId}/ (e.g., Research/books/{bookId}/)
• Type-scoped: {type}/ (e.g., AgentCheckpoints/, AgentLogs/)
• Convention: Lowercase with underscores, not camelCase

Ephemeral vs. Durable Separation

Separate agent working files from user's permanent data:

Documents/
├── AgentCheckpoints/     # Ephemeral (can delete)
│   └── {sessionId}.checkpoint
├── AgentLogs/            # Ephemeral (debugging)
│   └── {type}/{sessionId}.md
└── Research/             # Durable (user's work)
    └── books/{bookId}/

The Split: Markdown vs JSON

• Markdown: For content users might read or edit
• JSON: For structured data the app queries

</file_organization>

<context_md_pattern>

The context.md Pattern

A file the agent reads at the start of each session and updates as it learns:

# Context

## Who I Am
Reading assistant for the Every app.

## What I Know About This User
- Interested in military history and Russian literature
- Prefers concise analysis
- Currently reading War and Peace

## What Exists
- 12 notes in /notes
- 3 active projects
- User preferences at /preferences.md

## Recent Activity
- User created "Project kickoff" (2 hours ago)
- Analyzed passage about Austerlitz (yesterday)

## My Guidelines
- Don't spoil books they're reading
- Use their interests to personalize insights

## Current State
- No pending tasks
- Last sync: 10 minutes ago

Benefits

• Agent behavior evolves without code changes - Update the context, behavior changes
• Users can inspect and modify - Complete transparency
• Natural place for accumulated context - Learnings persist across sessions
• Portable across sessions - Restart agent, knowledge preserved

How It Works

1. Agent reads context.md at session start 2. Agent updates it when learning something important 3. System can also update it (recent activity, new resources) 4. Context persists across sessions

What to Include

</context_md_pattern>

<files_vs_database>

Files vs. Database

Needs validation: This framing is informed by mobile development. For web apps, the tradeoffs are different.

The principle: Files for legibility, databases for structure. When in doubt, files—they're more transparent and users can always inspect them.

When Files Work Best

• Scale is small (one user's library, not millions of records)
• Transparency is valued over query speed
• Cloud sync (iCloud, Dropbox) works well with files

Hybrid Approach

Even if you need a database for performance, consider maintaining a file-based "source of truth" that the agent works with, synced to the database for the UI:

Files (agent workspace):
  Research/book_123/introduction.md

Database (UI queries):
  research_index: { bookId, path, title, createdAt }

</files_vs_database>

<conflict_model>

Conflict Model

If agents and users write to the same files, you need a conflict model.

Current Reality

Most implementations use last-write-wins via atomic writes:

try data.write(to: url, options: [.atomic])

This is simple but can lose changes.

Options

Recommended Approaches

For files agents write frequently (logs, status): Last-write-wins is fine. Conflicts are rare.

For files users edit (profiles, notes): Consider explicit handling:

• Agent checks modification time before overwriting
• Or keep agent output separate from user-editable content
• Or use append-only pattern

iCloud Considerations

iCloud sync adds complexity. It creates {filename} (conflict).md files when sync conflicts occur. Monitor for these:

NotificationCenter.default.addObserver(
    forName: .NSMetadataQueryDidUpdate,
    ...
)

System Prompt Guidance

Tell the agent about the conflict model:

## Working with User Content

When you create content, the user may edit it afterward. Always read
existing files before modifying them—the user may have made improvements
you should preserve.

If a file has been modified since you last wrote it, ask before overwriting.

</conflict_model>

<examples>

Example: Reading App File Structure

Documents/
├── Library/
│   └── library.json              # Book metadata
├── Research/
│   └── books/
│       └── {bookId}/
│           ├── full_text.txt     # Downloaded content
│           ├── introduction.md   # Agent-generated, user-editable
│           ├── notes.md          # User notes
│           └── sources/
│               ├── wikipedia.md  # Research gathered by agent
│               └── reviews.md
├── Chats/
│   └── {conversationId}.json     # Chat history
├── Profile/
│   └── profile.md                # User reading profile
└── context.md                    # Agent's accumulated knowledge

How it works:

1. User adds book → creates entry in library.json 2. Agent downloads text → saves to Research/books/{id}/full_text.txt 3. Agent researches → saves to sources/ 4. Agent generates intro → saves to introduction.md 5. User edits intro → agent sees changes on next read 6. Agent updates context.md with learnings </examples>

<checklist>

Files as Universal Interface Checklist

Organization

• [ ] Entity-scoped directories ({type}/{id}/)
• [ ] Consistent naming conventions
• [ ] Ephemeral vs durable separation
• [ ] Markdown for human content, JSON for structured data

context.md

• [ ] Agent reads context at session start
• [ ] Agent updates context when learning
• [ ] Includes: identity, user knowledge, what exists, guidelines
• [ ] Persists across sessions

Conflict Handling

• [ ] Conflict model defined (last-write-wins, check-before-write, etc.)
• [ ] Agent guidance in system prompt
• [ ] iCloud conflict monitoring (if applicable)

Integration

• [ ] UI observes file changes (or shared service)
• [ ] Agent can read user edits
• [ ] User can inspect agent output

</checklist>

<overview> Start with pure primitives: bash, file operations, basic storage. This proves the architecture works and reveals what the agent actually needs. As patterns emerge, add domain-specific tools deliberately. This document covers when and how to evolve from primitives to domain tools, and when to graduate to optimized code. </overview>

<start_with_primitives>

Start with Pure Primitives

Begin every agent-native system with the most atomic tools possible:

• read_file / write_file / list_files
• bash (for everything else)
• Basic storage (store_item / get_item)
• HTTP requests (fetch_url)

Why start here:

1. Proves the architecture - If it works with primitives, your prompts are doing their job 2. Reveals actual needs - You'll discover what domain concepts matter 3. Maximum flexibility - Agent can do anything, not just what you anticipated 4. Forces good prompts - You can't lean on tool logic as a crutch

Example: Starting Primitive

// Start with just these
const tools = [
  tool("read_file", { path: z.string() }, ...),
  tool("write_file", { path: z.string(), content: z.string() }, ...),
  tool("list_files", { path: z.string() }, ...),
  tool("bash", { command: z.string() }, ...),
];

// Prompt handles the domain logic
const prompt = `
When processing feedback:
1. Read existing feedback from data/feedback.json
2. Add the new feedback with your assessment of importance (1-5)
3. Write the updated file
4. If importance >= 4, create a notification file in data/alerts/
`;

</start_with_primitives>

<when_to_add_domain_tools>

When to Add Domain Tools

As patterns emerge, you'll want to add domain-specific tools. This is good—but do it deliberately.

Vocabulary Anchoring

Add a domain tool when: The agent needs to understand domain concepts.

A create_note tool teaches the agent what "note" means in your system better than "write a file to the notes directory with this format."

// Without domain tool - agent must infer structure
await agent.chat("Create a note about the meeting");
// Agent: writes to... notes/? documents/? what format?

// With domain tool - vocabulary is anchored
tool("create_note", {
  title: z.string(),
  content: z.string(),
  tags: z.array(z.string()).optional(),
}, async ({ title, content, tags }) => {
  // Tool enforces structure, agent understands "note"
});

Guardrails

Add a domain tool when: Some operations need validation or constraints that shouldn't be left to agent judgment.

// publish_to_feed might enforce format requirements or content policies
tool("publish_to_feed", {
  bookId: z.string(),
  content: z.string(),
  headline: z.string().max(100),  // Enforce headline length
}, async ({ bookId, content, headline }) => {
  // Validate content meets guidelines
  if (containsProhibitedContent(content)) {
    return { text: "Content doesn't meet guidelines", isError: true };
  }
  // Enforce proper structure
  await feedService.publish({ bookId, content, headline, publishedAt: new Date() });
});

Efficiency

Add a domain tool when: Common operations would take many primitive calls.

// Primitive approach: multiple calls
await agent.chat("Get book details");
// Agent: read library.json, parse, find book, read full_text.txt, read introduction.md...

// Domain tool: one call for common operation
tool("get_book_with_content", { bookId: z.string() }, async ({ bookId }) => {
  const book = await library.getBook(bookId);
  const fullText = await readFile(`Research/${bookId}/full_text.txt`);
  const intro = await readFile(`Research/${bookId}/introduction.md`);
  return { text: JSON.stringify({ book, fullText, intro }) };
});

</when_to_add_domain_tools>

<the_rule>

The Rule for Domain Tools

Domain tools should represent one conceptual action from the user's perspective.

They can include mechanical validation, but judgment about what to do or whether to do it belongs in the prompt.

Wrong: Bundles Judgment

// WRONG - analyze_and_publish bundles judgment into the tool
tool("analyze_and_publish", async ({ input }) => {
  const analysis = analyzeContent(input);      // Tool decides how to analyze
  const shouldPublish = analysis.score > 0.7;  // Tool decides whether to publish
  if (shouldPublish) {
    await publish(analysis.summary);            // Tool decides what to publish
  }
});

Right: One Action, Agent Decides

// RIGHT - separate tools, agent decides
tool("analyze_content", { content: z.string() }, ...);  // Returns analysis
tool("publish", { content: z.string() }, ...);          // Publishes what agent provides

// Prompt: "Analyze the content. If it's high quality, publish a summary."
// Agent decides what "high quality" means and what summary to write.

The Test

Ask: "Who is making the decision here?"

• If the answer is "the tool code" → you've encoded judgment, refactor
• If the answer is "the agent based on the prompt" → good

</the_rule>

<keep_primitives_available>

Keep Primitives Available

Domain tools are shortcuts, not gates.

Unless there's a specific reason to restrict access (security, data integrity), the agent should still be able to use underlying primitives for edge cases.

// Domain tool for common case
tool("create_note", { title, content }, ...);

// But primitives still available for edge cases
tool("read_file", { path }, ...);
tool("write_file", { path, content }, ...);

// Agent can use create_note normally, but for weird edge case:
// "Create a note in a non-standard location with custom metadata"
// → Agent uses write_file directly

When to Gate

Gating (making domain tool the only way) is appropriate for:

• Security: User authentication, payment processing
• Data integrity: Operations that must maintain invariants
• Audit requirements: Actions that must be logged in specific ways

The default is open. When you do gate something, make it a conscious decision with a clear reason. </keep_primitives_available>

<graduating_to_code>

Graduating to Code

Some operations will need to move from agent-orchestrated to optimized code for performance or reliability.

The Progression

Stage 1: Agent uses primitives in a loop
         → Flexible, proves the concept
         → Slow, potentially expensive

Stage 2: Add domain tools for common operations
         → Faster, still agent-orchestrated
         → Agent still decides when/whether to use

Stage 3: For hot paths, implement in optimized code
         → Fast, deterministic
         → Agent can still trigger, but execution is code

Example Progression

Stage 1: Pure primitives

Prompt: "When user asks for a summary, read all notes in /notes,
        analyze them, and write a summary to /summaries/{date}.md"

Agent: Calls read_file 20 times, reasons about content, writes summary
Time: 30 seconds, 50k tokens

Stage 2: Domain tool

tool("get_all_notes", {}, async () => {
  const notes = await readAllNotesFromDirectory();
  return { text: JSON.stringify(notes) };
});

// Agent still decides how to summarize, but retrieval is faster
// Time: 10 seconds, 30k tokens

Stage 3: Optimized code

tool("generate_weekly_summary", {}, async () => {
  // Entire operation in code for hot path
  const notes = await getNotes({ since: oneWeekAgo });
  const summary = await generateSummary(notes);  // Could use cheaper model
  await writeSummary(summary);
  return { text: "Summary generated" };
});

// Agent just triggers it
// Time: 2 seconds, 5k tokens

The Caveat

Even when an operation graduates to code, the agent should be able to:

1. Trigger the optimized operation itself 2. Fall back to primitives for edge cases the optimized path doesn't handle

Graduation is about efficiency. Parity still holds. The agent doesn't lose capability when you optimize. </graduating_to_code>

<decision_framework>

Decision Framework

Should I Add a Domain Tool?

Should I Graduate to Code?

Should I Gate Access?

</decision_framework>

<examples>

Examples

Feedback Processing Evolution

Stage 1: Primitives only

tools: [read_file, write_file, bash]
prompt: "Store feedback in data/feedback.json, notify if important"
// Agent figures out JSON structure, importance criteria, notification method

Stage 2: Domain tools for vocabulary

tools: [
  store_feedback,      // Anchors "feedback" concept with proper structure
  send_notification,   // Anchors "notify" with correct channels
  read_file,           // Still available for edge cases
  write_file,
]
prompt: "Store feedback using store_feedback. Notify if importance >= 4."
// Agent still decides importance, but vocabulary is anchored

Stage 3: Graduated hot path

tools: [
  process_feedback_batch,  // Optimized for high-volume processing
  store_feedback,          // For individual items
  send_notification,
  read_file,
  write_file,
]
// Batch processing is code, but agent can still use store_feedback for special cases

When NOT to Add Domain Tools

Don't add a domain tool just to make things "cleaner":

// Unnecessary - agent can compose primitives
tool("organize_files_by_date", ...)  // Just use move_file + judgment

// Unnecessary - puts decision in wrong place
tool("decide_file_importance", ...)  // This is prompt territory

Don't add a domain tool if behavior might change:

// Bad - locked into code
tool("generate_standard_report", ...)  // What if report format evolves?

// Better - keep in prompt
prompt: "Generate a report covering X, Y, Z. Format for readability."
// Can adjust format by editing prompt

</examples>

<checklist>

Checklist: Primitives to Domain Tools

Starting Out

• [ ] Begin with pure primitives (read, write, list, bash)
• [ ] Write behavior in prompts, not tool logic
• [ ] Let patterns emerge from actual usage

Adding Domain Tools

• [ ] Clear reason: vocabulary anchoring, guardrails, or efficiency
• [ ] Tool represents one conceptual action
• [ ] Judgment stays in prompts, not tool code
• [ ] Primitives remain available alongside domain tools

Graduating to Code

• [ ] Hot path identified (frequent, latency-sensitive, or expensive)
• [ ] Optimized version doesn't remove agent capability
• [ ] Fallback to primitives for edge cases still works

Gating Decisions

• [ ] Specific reason for each gate (security, integrity, audit)
• [ ] Default is open access
• [ ] Gates are conscious decisions, not defaults

</checklist>

<overview> How to design MCP tools following prompt-native principles. Tools should be primitives that enable capability, not workflows that encode decisions.

Core principle: Whatever a user can do, the agent should be able to do. Don't artificially limit the agent—give it the same primitives a power user would have. </overview>

<principle name="primitives-not-workflows">

Tools Are Primitives, Not Workflows

Wrong approach: Tools that encode business logic

tool("process_feedback", {
  feedback: z.string(),
  category: z.enum(["bug", "feature", "question"]),
  priority: z.enum(["low", "medium", "high"]),
}, async ({ feedback, category, priority }) => {
  // Tool decides how to process
  const processed = categorize(feedback);
  const stored = await saveToDatabase(processed);
  const notification = await notify(priority);
  return { processed, stored, notification };
});

Right approach: Primitives that enable any workflow

tool("store_item", {
  key: z.string(),
  value: z.any(),
}, async ({ key, value }) => {
  await db.set(key, value);
  return { text: `Stored ${key}` };
});

tool("send_message", {
  channel: z.string(),
  content: z.string(),
}, async ({ channel, content }) => {
  await messenger.send(channel, content);
  return { text: "Sent" };
});

The agent decides categorization, priority, and when to notify based on the system prompt. </principle>

<principle name="descriptive-names">

Tools Should Have Descriptive, Primitive Names

Names should describe the capability, not the use case:

The prompt tells the agent when to use primitives. The tool just provides capability. </principle>

<principle name="simple-inputs">

Inputs Should Be Simple

Tools accept data. They don't accept decisions.

Wrong: Tool accepts decisions

tool("format_content", {
  content: z.string(),
  format: z.enum(["markdown", "html", "json"]),
  style: z.enum(["formal", "casual", "technical"]),
}, ...)

Right: Tool accepts data, agent decides format

tool("write_file", {
  path: z.string(),
  content: z.string(),
}, ...)
// Agent decides to write index.html with HTML content, or data.json with JSON

</principle>

<principle name="rich-outputs">

Outputs Should Be Rich

Return enough information for the agent to verify and iterate.

Wrong: Minimal output

async ({ key }) => {
  await db.delete(key);
  return { text: "Deleted" };
}

Right: Rich output

async ({ key }) => {
  const existed = await db.has(key);
  if (!existed) {
    return { text: `Key ${key} did not exist` };
  }
  await db.delete(key);
  return { text: `Deleted ${key}. ${await db.count()} items remaining.` };
}

</principle>

<design_template>

Tool Design Template

import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

export const serverName = createSdkMcpServer({
  name: "server-name",
  version: "1.0.0",
  tools: [
    // READ operations
    tool(
      "read_item",
      "Read an item by key",
      { key: z.string().describe("Item key") },
      async ({ key }) => {
        const item = await storage.get(key);
        return {
          content: [{
            type: "text",
            text: item ? JSON.stringify(item, null, 2) : `Not found: ${key}`,
          }],
          isError: !item,
        };
      }
    ),

    tool(
      "list_items",
      "List all items, optionally filtered",
      {
        prefix: z.string().optional().describe("Filter by key prefix"),
        limit: z.number().default(100).describe("Max items"),
      },
      async ({ prefix, limit }) => {
        const items = await storage.list({ prefix, limit });
        return {
          content: [{
            type: "text",
            text: `Found ${items.length} items:\n${items.map(i => i.key).join("\n")}`,
          }],
        };
      }
    ),

    // WRITE operations
    tool(
      "store_item",
      "Store an item",
      {
        key: z.string().describe("Item key"),
        value: z.any().describe("Item data"),
      },
      async ({ key, value }) => {
        await storage.set(key, value);
        return {
          content: [{ type: "text", text: `Stored ${key}` }],
        };
      }
    ),

    tool(
      "delete_item",
      "Delete an item",
      { key: z.string().describe("Item key") },
      async ({ key }) => {
        const existed = await storage.delete(key);
        return {
          content: [{
            type: "text",
            text: existed ? `Deleted ${key}` : `${key} did not exist`,
          }],
        };
      }
    ),

    // EXTERNAL operations
    tool(
      "call_api",
      "Make an HTTP request",
      {
        url: z.string().url(),
        method: z.enum(["GET", "POST", "PUT", "DELETE"]).default("GET"),
        body: z.any().optional(),
      },
      async ({ url, method, body }) => {
        const response = await fetch(url, { method, body: JSON.stringify(body) });
        const text = await response.text();
        return {
          content: [{
            type: "text",
            text: `${response.status} ${response.statusText}\n\n${text}`,
          }],
          isError: !response.ok,
        };
      }
    ),
  ],
});

</design_template>

<example name="feedback-server">

Example: Feedback Storage Server

This server provides primitives for storing feedback. It does NOT decide how to categorize or organize feedback—that's the agent's job via the prompt.

export const feedbackMcpServer = createSdkMcpServer({
  name: "feedback",
  version: "1.0.0",
  tools: [
    tool(
      "store_feedback",
      "Store a feedback item",
      {
        item: z.object({
          id: z.string(),
          author: z.string(),
          content: z.string(),
          importance: z.number().min(1).max(5),
          timestamp: z.string(),
          status: z.string().optional(),
          urls: z.array(z.string()).optional(),
          metadata: z.any().optional(),
        }).describe("Feedback item"),
      },
      async ({ item }) => {
        await db.feedback.insert(item);
        return {
          content: [{
            type: "text",
            text: `Stored feedback ${item.id} from ${item.author}`,
          }],
        };
      }
    ),

    tool(
      "list_feedback",
      "List feedback items",
      {
        limit: z.number().default(50),
        status: z.string().optional(),
      },
      async ({ limit, status }) => {
        const items = await db.feedback.list({ limit, status });
        return {
          content: [{
            type: "text",
            text: JSON.stringify(items, null, 2),
          }],
        };
      }
    ),

    tool(
      "update_feedback",
      "Update a feedback item",
      {
        id: z.string(),
        updates: z.object({
          status: z.string().optional(),
          importance: z.number().optional(),
          metadata: z.any().optional(),
        }),
      },
      async ({ id, updates }) => {
        await db.feedback.update(id, updates);
        return {
          content: [{ type: "text", text: `Updated ${id}` }],
        };
      }
    ),
  ],
});

The system prompt then tells the agent how to use these primitives:

## Feedback Processing

When someone shares feedback:
1. Extract author, content, and any URLs
2. Rate importance 1-5 based on actionability
3. Store using feedback.store_feedback
4. If high importance (4-5), notify the channel

Use your judgment about importance ratings.

</example>

<principle name="dynamic-capability-discovery">

Dynamic Capability Discovery vs Static Tool Mapping

This pattern is specifically for agent-native apps where you want the agent to have full access to an external API—the same access a user would have. It follows the core agent-native principle: "Whatever the user can do, the agent can do."

If you're building a constrained agent with limited capabilities, static tool mapping may be intentional. But for agent-native apps integrating with HealthKit, HomeKit, GraphQL, or similar APIs:

Static Tool Mapping (Anti-pattern for Agent-Native): Build individual tools for each API capability. Always out of date, limits agent to only what you anticipated.

// ❌ Static: Every API type needs a hardcoded tool
tool("read_steps", async ({ startDate, endDate }) => {
  return healthKit.query(HKQuantityType.stepCount, startDate, endDate);
});

tool("read_heart_rate", async ({ startDate, endDate }) => {
  return healthKit.query(HKQuantityType.heartRate, startDate, endDate);
});

tool("read_sleep", async ({ startDate, endDate }) => {
  return healthKit.query(HKCategoryType.sleepAnalysis, startDate, endDate);
});

// When HealthKit adds glucose tracking... you need a code change

Dynamic Capability Discovery (Preferred): Build a meta-tool that discovers what's available, and a generic tool that can access anything.

// ✅ Dynamic: Agent discovers and uses any capability

// Discovery tool - returns what's available at runtime
tool("list_available_capabilities", async () => {
  const quantityTypes = await healthKit.availableQuantityTypes();
  const categoryTypes = await healthKit.availableCategoryTypes();

  return {
    text: `Available health metrics:\n` +
          `Quantity types: ${quantityTypes.join(", ")}\n` +
          `Category types: ${categoryTypes.join(", ")}\n` +
          `\nUse read_health_data with any of these types.`
  };
});

// Generic access tool - type is a string, API validates
tool("read_health_data", {
  dataType: z.string(),  // NOT z.enum - let HealthKit validate
  startDate: z.string(),
  endDate: z.string(),
  aggregation: z.enum(["sum", "average", "samples"]).optional()
}, async ({ dataType, startDate, endDate, aggregation }) => {
  // HealthKit validates the type, returns helpful error if invalid
  const result = await healthKit.query(dataType, startDate, endDate, aggregation);
  return { text: JSON.stringify(result, null, 2) };
});

When to Use Each Approach:

The agent-native default is Dynamic. Only use Static when you're intentionally limiting the agent's capabilities.

Complete Dynamic Pattern:

// 1. Discovery tool: What can I access?
tool("list_health_types", "Get available health data types") { _ in
    let store = HKHealthStore()

    let quantityTypes = HKQuantityTypeIdentifier.allCases.map { $0.rawValue }
    let categoryTypes = HKCategoryTypeIdentifier.allCases.map { $0.rawValue }
    let characteristicTypes = HKCharacteristicTypeIdentifier.allCases.map { $0.rawValue }

    return ToolResult(text: """
        Available HealthKit types:

        ## Quantity Types (numeric values)
        \(quantityTypes.joined(separator: ", "))

        ## Category Types (categorical data)
        \(categoryTypes.joined(separator: ", "))

        ## Characteristic Types (user info)
        \(characteristicTypes.joined(separator: ", "))

        Use read_health_data or write_health_data with any of these.
        """)
}

// 2. Generic read: Access any type by name
tool("read_health_data", "Read any health metric", {
    dataType: z.string().describe("Type name from list_health_types"),
    startDate: z.string(),
    endDate: z.string()
}) { request in
    // Let HealthKit validate the type name
    guard let type = HKQuantityTypeIdentifier(rawValue: request.dataType)
                     ?? HKCategoryTypeIdentifier(rawValue: request.dataType) else {
        return ToolResult(
            text: "Unknown type: \(request.dataType). Use list_health_types to see available types.",
            isError: true
        )
    }

    let samples = try await healthStore.querySamples(type: type, start: startDate, end: endDate)
    return ToolResult(text: samples.formatted())
}

// 3. Context injection: Tell agent what's available in system prompt
func buildSystemPrompt() -> String {
    let availableTypes = healthService.getAuthorizedTypes()

    return """
    ## Available Health Data

    You have access to these health metrics:
    \(availableTypes.map { "- \($0)" }.joined(separator: "\n"))

    Use read_health_data with any type above. For new types not listed,
    use list_health_types to discover what's available.
    """
}

Benefits:

• Agent can use any API capability, including ones added after your code shipped
• API is the validator, not your enum definition
• Smaller tool surface (2-3 tools vs N tools)
• Agent naturally discovers capabilities by asking
• Works with any API that has introspection (HealthKit, GraphQL, OpenAPI)

</principle>

<principle name="crud-completeness">

CRUD Completeness

Every data type the agent can create, it should be able to read, update, and delete. Incomplete CRUD = broken action parity.

Anti-pattern: Create-only tools

// ❌ Can create but not modify or delete
tool("create_experiment", { hypothesis, variable, metric })
tool("write_journal_entry", { content, author, tags })
// User: "Delete that experiment" → Agent: "I can't do that"

Correct: Full CRUD for each entity

// ✅ Complete CRUD
tool("create_experiment", { hypothesis, variable, metric })
tool("read_experiment", { id })
tool("update_experiment", { id, updates: { hypothesis?, status?, endDate? } })
tool("delete_experiment", { id })

tool("create_journal_entry", { content, author, tags })
tool("read_journal", { query?, dateRange?, author? })
tool("update_journal_entry", { id, content, tags? })
tool("delete_journal_entry", { id })

The CRUD Audit: For each entity type in your app, verify:

• [ ] Create: Agent can create new instances
• [ ] Read: Agent can query/search/list instances
• [ ] Update: Agent can modify existing instances
• [ ] Delete: Agent can remove instances

If any operation is missing, users will eventually ask for it and the agent will fail. </principle>

<checklist>

MCP Tool Design Checklist

Fundamentals:

• [ ] Tool names describe capability, not use case
• [ ] Inputs are data, not decisions
• [ ] Outputs are rich (enough for agent to verify)
• [ ] CRUD operations are separate tools (not one mega-tool)
• [ ] No business logic in tool implementations
• [ ] Error states clearly communicated via isError
• [ ] Descriptions explain what the tool does, not when to use it

Dynamic Capability Discovery (for agent-native apps):

• [ ] For external APIs where agent should have full access, use dynamic discovery
• [ ] Include a list_* or discover_* tool for each API surface
• [ ] Use string inputs (not enums) when the API validates
• [ ] Inject available capabilities into system prompt at runtime
• [ ] Only use static tool mapping if intentionally limiting agent scope

CRUD Completeness:

• [ ] Every entity has create, read, update, delete operations
• [ ] Every UI action has a corresponding agent tool
• [ ] Test: "Can the agent undo what it just did?"

</checklist>