---
phase: 02-agent-workflow-optimization
plan: 1
type: execute
wave: 1
depends_on: []
files_modified:
  - "src/fs_mcp/server.py"
  - ".planning/PROJECT.md"
autonomous: true

must_haves:
  truths:
    - "The `grep` tool's description explicitly guides the agent to use it for locating file paths and line numbers."
    - "The `grep` tool's description contains a clear, copy-pasteable example of the 'grep -> read' workflow."
    - "The `read` tool's description is updated to mention its synergy with `grep` for targeted file reading."
    - "Project documentation in `PROJECT.md` explains the 'grep -> read' workflow for human developers."
  artifacts:
    - path: "src/fs_mcp/server.py"
      provides: "Updated tool descriptions for `grep_content` and `read_files`."
    - path: ".planning/PROJECT.md"
      provides: "Documentation for the 'grep -> read' agent workflow."
  key_links:
    - from: "grep_content tool description"
      to: "read_files tool"
      via: "Explicit mention and example."
      pattern: "Use `read_files`"
    - from: ".planning/PROJECT.md"
      to: "grep -> read workflow"
      via: "A new documentation section."
      pattern: "The Grep -> Read Pattern"
---

<objective>
Optimize agent workflow by refining the `grep` and `read` tool descriptions to guide agents towards the efficient "grep -> read" pattern. This plan also adds documentation for human developers on this workflow.

Purpose: To reduce agent token consumption and improve the quality of agent interactions by making the intended search workflow explicit and easy to follow.
Output: Modified `server.py` with updated tool descriptions and an updated `PROJECT.md` with new documentation.
</objective>

<execution_context>
@~/.config/opencode/get-shit-done/workflows/execute-plan.md
@~/.config/opencode/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/02-agent-workflow-optimization/RESEARCH.md
@src/fs_mcp/server.py
</context>

<tasks>

<task type="auto">
  <name>Task 1: Update `grep_content` tool description</name>
  <files>
    src/fs_mcp/server.py
  </files>
  <action>
    Modify the docstring for the `grep_content` function in `src/fs_mcp/server.py`.

    The new description should:
    1.  Clearly state that this tool's primary purpose is to **locate file paths and line numbers**, not to read full file contents.
    2.  Emphasize that its output is optimized for use with the `read_files` tool for targeted reading.
    3.  Include a clear, copy-pasteable example demonstrating the two-step `grep` -> `read_files` workflow.

    **Example of new docstring section to add:**

    """
    **Workflow:**
    This tool is the first step in a two-step "grep -> read" workflow.

    1.  **`grep_content`**: Use this tool with a specific pattern to find *which files* are relevant and *where* in those files the relevant code is (line numbers).
    2.  **`read_files`**: Use the file path and line numbers from the output of this tool to perform a targeted read of only the relevant file sections.

    **Example:**
    ```
    # Step 1: Find where 'FastMCP' is defined.
    grep_content(pattern="class FastMCP")

    # Output might be: File: src/fs_mcp/server.py, Line: 20

    # Step 2: Read the relevant section of that file.
    read_files([{"path": "src/fs_mcp/server.py", "start_line": 15, "end_line": 25}])
    ```
    """
  </action>
  <verify>
    Read the file `src/fs_mcp/server.py` and confirm the docstring for `grep_content` has been updated to include the new workflow description and example.
  </verify>
  <done>
    The `grep_content` tool description guides agents toward the intended `grep -> read` workflow.
  </done>
</task>

<task type="auto">
  <name>Task 2: Update `read_files` tool description</name>
  <files>
    src/fs_mcp/server.py
  </files>
  <action>
    Modify the docstring for the `read_files` function in `src/fs_mcp/server.py`.

    The update should:
    1.  Add a note explaining its synergy with `grep_content`.
    2.  Reference the "grep -> read" workflow, explaining that `read_files` is the second step.
    3.  Use the `start_line` and `end_line` parameters in its example to show how to perform a targeted read based on `grep_content` output.
  </action>
  <verify>
    Read the file `src/fs_mcp/server.py` and confirm the docstring for `read_files` has been updated to mention `grep_content` and the workflow.
  </verify>
  <done>
    The `read_files` tool description helps agents understand its synergy with `grep_content`.
  </done>
</task>

<task type="auto">
  <name>Task 3: Document the 'grep -> read' workflow in PROJECT.md</name>
  <files>
    .planning/PROJECT.md
  </files>
  <action>
    Add a new section to `.planning/PROJECT.md` to onboard human developers to the intended agent workflow.

    The new section should be titled "### Agent Workflows" and include a subsection called "The Grep -> Read Pattern".

    This section should briefly explain the two-step process:
    1.  Use `grep` to locate.
    2.  Use `read` to inspect.
    3.  Explain *why* this is important (token efficiency, context quality).
  </action>
  <verify>
    Read `.planning/PROJECT.md` and confirm the new "Agent Workflows" section exists and clearly explains the `grep -> read` pattern.
  </verify>
  <done>
    Project documentation explains the optimal search workflow to human developers.
  </done>
</task>

</tasks>

<verification>
After all tasks are complete:
1.  The `grep_content` tool description in `src/fs_mcp/server.py` should be prescriptive and workflow-oriented.
2.  The `read_files` tool description in `src/fs_mcp/server.py` should reference its use with `grep_content`.
3.  The `PROJECT.md` file should contain a new section documenting the "grep -> read" pattern for developers.
</verification>

<success_criteria>
The phase is successful when the tool descriptions and project documentation are updated to clearly and effectively guide both agents and humans to use the efficient `grep -> read` workflow, measurably reducing the likelihood of agents reading large, irrelevant file contents.
</success_criteria>

<output>
After completion, create `.planning/phases/02-agent-workflow-optimization/02-01-SUMMARY.md`
</output>
