The obo-mcp server provides tools for managing structured one-by-one (OBO) workflow sessions, enabling coding agents to create, navigate, and resolve prioritized work items in a durable, ordered manner.
Create Sessions (obo_create): Create a new OBO session with a title, description, and list of work items (supporting optional urgency, importance, effort, dependencies, and category fields).
List Sessions (obo_list_sessions): Retrieve all sessions from the index, with optional filtering by status (active, completed, incomplete).
Session Status (obo_session_status): Get summary statistics for a session, such as item counts by status and overall progress.
Get Next Item (obo_next): Retrieve the next actionable item — prioritizing in_progress items first, then highest-priority pending items.
List Items (obo_list_items): List all items in a session sorted by priority score, with optional filtering by lifecycle status (pending, in_progress, completed, skipped).
Get Item Detail (obo_get_item): Retrieve full details for a single item by ID.
Mark Complete (obo_mark_complete): Mark an item as completed, recording a resolution description.
Mark Skipped (obo_mark_skip): Mark an item as skipped, with an optional reason.
Update Item Field (obo_update_field): Update any field on an item, with automatic priority score recalculation when relevant attributes change.
Manages One-By-One (OBO) review sessions by storing and organizing session data within a GitHub repository's .github directory.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@obo-mcp give me the next item to review"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Structured one-by-one workflows for coding agents.
MCP server for durable one-by-one review workflows, with prioritized session state for coding agents.
Provides 20 tools for creating, navigating, and resolving items in priority-scored session files, including blocked-item handling, first-class approval updates, and nested child sessions.
Licensed under AGPL-3.0-or-later with commercial licensing available.
See LICENSE for full terms.
Install or run Oboe MCP directly from PyPI using either of these alternatives:
Run it without installing: uvx oboe-mcp
Install it into your current environment: pip install oboe-mcp
Installing oboe-mcp also installs the oboe-cli command:
# After pip install oboe-mcp
oboe-cli --help
# From PyPI
uvx --from oboe-mcp oboe-cli --help
# From a local checkout (no install needed)
uvx --from /path/to/oboe-mcp oboe-cli --helpRelated MCP server: AgentIssueTracker
oboe-cli)Installing oboe-mcp also installs oboe-cli, a human-friendly command-line
companion for the same session files the MCP tools operate on.
oboe-cli [--session SESSION] [--base-dir DIR] COMMAND [ARGS...]Global options:
Option | Description |
| Session filename (e.g. |
| Project root containing |
Base-dir auto-detection: when --base-dir is omitted, oboe-cli uses the
current working directory if it contains a .github/oboe_sessions/ folder,
otherwise it falls back to the working directory as-is.
Command | Description |
| List all sessions (supports |
| Rebuild |
| Show session summary statistics |
| Create a new session from a JSON items file |
| Append new items to an existing session |
| Mark the entire session as completed |
| List items, sorted by priority score (supports |
| Show the next actionable item |
| Show full detail for one item |
| Mark an item as completed |
| Mark an item as skipped |
| Mark an item as in progress |
| Mark an item as blocked |
| Set approval metadata |
| Update a single field on an item |
| Create a child session and pause the parent |
| Complete a child session and resume the parent |
# Create a session from a JSON items file
oboe-cli --base-dir /path/to/project create \
--title "Code review findings" \
--input-file findings.json
# List sessions
oboe-cli --base-dir /path/to/project sessions
# Work through items
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json next
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json \
in-progress 1
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json \
complete 1 "Fixed the validation bug"Note: the
oboe_helper.pyscript shipped in previous versions is now a thin deprecation shim that delegates tooboe-cli.
Tool | Description |
| Create session file + update index.json atomically |
| List sessions from index.json |
| Rebuild index.json from the session files on disk ( |
| Summary stats for a session |
| Next item: in_progress first, then highest-priority pending, then deferred |
| All items sorted by priority_score desc |
| Full detail for one item |
| Mark an item blocked and store blocker information |
| Mark item completed with resolution text |
| Mark item in progress |
| Mark item skipped |
| Set approval metadata and optional lifecycle state |
| Mark a session completed when no actionable items remain |
| Create a child session, pause the parent, and step into the child |
| Complete a child session and resume the parent |
| Append new items to an existing session and reactivate it |
| Session header fields: title, status, parent/child refs |
| Mark an item deferred with optional reason and deferred_until |
| Update any field; auto-recalculates priority_score |
| Cancel a session, recording an optional reason |
| Delete old sessions by age and/or status |
Migration from
obo_tool names (pre-0.3.0): All MCP tools were renamed fromobo_*tooboe_*in v0.3.0. The session directory was also renamed from.github/obo_sessions/to.github/oboe_sessions/(a backward-compat symlink is created automatically). Run the bundled migration to update existing projects:uvx oboe-mcp migrate /path/to/your/project # preview first, changing nothing: uvx oboe-mcp migrate /path/to/your/project --dry-run # or, from a local checkout: python -m oboe_mcp.migrate /path/to/your/project
One-by-One sessions are not just saved chat notes. They are a workflow model for handling multi-item work as a durable, ordered interaction session.
Compared with plain chat or an agent's built-in follow-up questions, OBO adds capabilities that those lighter interaction modes do not usually provide:
an overview-first workflow, where the agent can begin with the scope, item count, major categories, and proposed execution order
explicit reprioritization based on urgency, importance, effort, and dependency pressure instead of whatever order happened to appear in chat
durable lifecycle states through pending, in_progress, deferred, blocked, completed, and skipped
separate approval metadata through approval_status, approval_mode, approved_at, and approval_note
stored blocker metadata so blocked work is still visible and explainable instead of silently disappearing from the active queue
nested child sessions that pause a parent session, handle a sub-problem, then resume the parent session cleanly
first-class session lifecycle management: list, create, inspect, merge, pause, resume, and close sessions as named workflow objects
deterministic recovery after model restarts, editor reloads, or agent handoff
a machine-readable audit trail in session files instead of relying on conversational memory
This matters most when the work spans many findings, requires explicit user approvals, depends on intermediate sub-investigations, or must survive across several agent turns. Chat is good at conversation. A structured question tool is good at getting a clean answer in the current turn. OBO is for durable workflow orchestration.
Use OBO when you need controlled sequential handling, durable queue state, or nested sub-work. Use plain chat when the task is small enough that a full workflow object would add more overhead than value.
OBO tracks each item on two independent axes.
pending: work is queued but not yet started
in_progress: work is actively being done now
deferred: work is approved for later execution and should stay out of the immediate review queue until the active review pass is exhausted or the user explicitly requests deferred work
blocked: work cannot continue until an external dependency or sub-problem is resolved
completed: work is finished and closed
skipped: work is intentionally not being executed
unreviewed: no explicit user decision has been recorded yet
approved: the user has authorized the work
denied: the user has explicitly rejected the work
Approval metadata fields:
approval_status: approval decision for the item
approval_mode: immediate or delayed when an approval timing decision was recorded
approved_at: timestamp for when approval was recorded
approval_note: optional free-text note about the approval decision
Common pairings:
Approve Immediate: call oboe_set_approval(..., approval_status="approved", approval_mode="immediate"); the item normally remains pending until work begins or is moved to in_progress
Approve Delayed: call oboe_set_approval(..., approval_status="approved", approval_mode="delayed"); this records delayed approval and moves the item to deferred
Deny: set approval_status=denied; if the item is being closed out of the queue, pair it with status=skipped
Session files are shared state. The MCP server, oboe-cli, a second editor
window, and any script you run can all reach the same
.github/oboe_sessions/ directory at once, so every operation takes a
cross-process lock over that directory.
What you get:
A mutation writes the session file and index.json under a single held
lock, so the two never drift apart, and an error mid-operation writes
nothing at all.
Writes are atomic (temp file + rename). A reader never sees a truncated or half-written file.
Readers take a shared lock, so concurrent reads do not block each other. Writers are exclusive.
Choosing what happens when the lock is held. The default is to wait up to 30 seconds and then raise an error naming the lock file and its recorded holder. An agent that would rather retry later than stall can ask to fail immediately instead:
Surface | Wait longer | Fail immediately |
MCP |
|
|
CLI |
|
|
Environment |
|
|
Pass --lock-timeout none (or OBOE_LOCK_TIMEOUT=none) to wait indefinitely.
Be aware that a wedged holder will then hang the call with no diagnostic,
which is why it is not the default. oboe_get_lock_policy reports what is
currently in effect.
Platform note. POSIX uses fcntl.flock. Elsewhere a portable lockfile
fallback is used which cannot express shared mode, so readers are serialized
along with writers; oboe_get_lock_policy reports this as
concurrent_readers: false. The lock file is .oboe.lock inside the sessions
directory and should not be committed.
The three common interaction patterns are plain chat, a structured question tool, and a full OBO session. They solve different problems.
Standard chat | askQuestions style interaction | One-by-One session |
Best for small, fast back-and-forth tasks where the state can stay in the conversation. | Best when the agent needs the user to choose from a short set of options in the current turn. | Best when work involves multiple findings or decisions that must be tracked, resumed, reordered, blocked, nested, or approved one item at a time. |
State is mostly conversational and can become hard to recover after a long session. | State is still mostly conversational; the question tool improves input quality but does not provide durable workflow state by itself. | State is persisted to |
Good example: "rename this function" or "explain this error". | Good example: "resume, merge, replace, or stop?" | Good example: "review these 12 findings one by one and wait for approval on each". |
Main benefit: lowest friction. | Main benefit: clearer user decisions and fewer ambiguous replies. | Main benefit: durable queue management, explicit blockers, nested sub-sessions, and deterministic recovery across many items. |
Example progression:
Standard chat: an agent lists several findings in prose and the conversation itself becomes the only record of what was handled.
askQuestions: the agent can ask for a clean menu choice, but still has no persistent item queue unless it stores one elsewhere.
OBO session: the agent starts with an overview, stores the full item list, orders it intentionally, records approvals, skips, and blockers, and can resume later without reconstructing the session from chat history.
Suppose an agent reviews a small toy to-do app and finds five items in this raw discovery order:
Improve an ambiguous settings label in the UI.
Resolve a race condition in the background sync job.
Add a regression test for duplicate task IDs.
Add missing input validation on the create-task endpoint.
Fix password logging in the login handler.
Agent:
I found five issues in the toy app: Issue 1: Improve an ambiguous settings label in the UI. Issue 2: Resolve a race condition in the background sync job. Issue 3: Add a regression test for duplicate task IDs. Issue 4: Add missing input validation on the create-task endpoint. Issue 5: Fix password logging in the login handler.
What do you want to do next?
User:
Do 4 and 2 first.
Commentary:
This is fast, but the chat itself becomes the only record of the sequence, the dependency between items 4 and 3 is implicit.
The status of the other issues is not captured, and the user will need to explicitly request that the agent display or work on the other issues.
If the session is interrupted, another agent would have to reconstruct state from the transcript.
Agent:
I found five issues. Which should we do first?
Options: • 4. Add missing input validation on the create-task endpoint • 2. Resolve a race condition in the background sync job • 5. Fix password logging in the login handler • 3. Add a regression test for duplicate task IDs • 1. Improve an ambiguous settings label in the UI
User:
4
Agent:
Next action?
Options: • Continue with 2 • Reorder the remaining list • Stop
Commentary:
This gives cleaner user choices than plain chat, but the tool still does not create a durable, dependency-aware workflow object by itself.
The status of the other issues is still not captured, and the user will need to explicitly request that the agent display or work on the other issues.
Likewise, if the session is interrupted, another agent would have to reconstruct state from the transcript.
Following the OBO agent prompt instructions, the agent assigns this ordering logic:
Item 4 goes first because the create-task endpoint behavior should be stabilized before the follow-up regression test is written.
Item 2 comes next because the race condition can affect correctness across the sync flow and may require a nested investigation session.
Item 5 follows because it is an important security fix, but it does not block the validation and concurrency work.
Item 3 stays behind item 4 because the regression test should lock in the final validation behavior instead of preceding it.
Item 1 is still useful, but it is low impact compared with the other four items, so it comes last.
Agent:
I created an OBO session for 5 findings.
Executive summary: • Total items: 5 • Categories: 1 API correctness, 1 concurrency, 1 security, 1 testing, 1 UX • Priority order: 4, 2, 5, 3, 1 • Estimated effort: 11 • Critical items: 3 • Dependency note: item 3 follows item 4 so the regression test targets the stabilized endpoint behavior • Child-session note: item 2 may branch into a nested investigation session • Current session state: 5 pending, 0 in progress, 0 completed
Current item: • Item 4 • Title: Add missing input validation on the create-task endpoint • Category: API correctness • Priority score: 18 • Rationale: stabilize the endpoint contract before the follow-up regression test is addressed
Reply with one of these: • Approve Immediate • Approve Delayed • Deny • Next • More Options
User:
Approve Immediate
[ ... agent does the item 4 work here ... ]
Agent:
Item 4 completed.
Session status: • 1 completed • 4 pending • 20% done
Current item: • Item 2 • Title: Resolve a race condition in the background sync job • Category: Concurrency • Priority score: 15 • Rationale: this can affect correctness across the sync flow and may need a nested investigation before the parent item can be resolved
Child-session note: • If you approve immediate, I will present the nested flow
Reply with one of these: • Approve Immediate • Approve Delayed • Deny • Next • More Options
User:
Approve Immediate.
Agent:
Item 2 needs isolated investigation before I can finish it. I created a child OBO session for the race-condition investigation and paused the parent session.
Child session summary: • Scope: reproduce the sync race, identify the conflicting code path, and verify a fix. • Proposed child order: reproduce, isolate, patch, verify.
User:
Proceed.
[ ... agent does the child-session investigation work here ... ]
Agent:
Child session completed. Root cause was overlapping writes from two sync workers.
I resumed the parent session, applied the fix, and I am ready to complete item 2.
Current item: • Item 2 • Title: Resolve a race condition in the background sync job • Category: Concurrency • Priority score: 15
Reply with one of these: • Approve Immediate • Approve Delayed • Deny • Next • More Options
User:
Approve Immediate
Agent:
[ ... agent records the resolution and resumes the parent workflow here ... ]
Item 2 completed.
Session status: • 2 completed • 3 pending • 40% done
Current item: • Item 5 • Title: Fix password logging in the login handler • Category: Security • Priority score: 15 • Rationale: remove plaintext password logging without disturbing the validation and race-condition fixes
Reply with one of these: • Approve Immediate • Approve Delayed • Deny • Next • More Options
User:
Proceed.
Agent:
[ ... agent does the item 5 work here ... ]
Item 5 completed.
Session status: • 3 completed • 2 pending • 60% done
Current item: • Item 3 • Title: Add a regression test for duplicate task IDs • Category: Testing • Priority score: 14 • Rationale: this now follows item 4 as planned, because the endpoint behavior has been stabilized
Reply with one of these: • Approve Immediate • Approve Delayed • Deny • Next • More Options
User:
Proceed.
Agent:
[ ... agent does the item 3 work here ... ]
Item 3 completed.
Session status: • 4 completed • 1 pending • 80% done
Current item: • Item 1 • Title: Improve an ambiguous settings label in the UI • Category: UX • Priority score: 10 • Rationale: this is the remaining low-impact cleanup item
Reply with one of these: • Approve Immediate • Approve Delayed • Deny • Next • More Options
User:
Approve Immediate
[ ... agent does the item 1 work here ... ]
Agent:
Item 1 completed.
Session status: • 5 completed • 0 pending • 100% done
All actionable items are now resolved. I completed the OBO session and the final record includes the child-session detour, the dependency-aware ordering, and the resolution for each item.
Commentary: this preserves the reordered plan, stores the dependency constraint, allows item 2 to branch into a child session, and gives another agent a durable session state to resume later.
Run the interactive installer from this repository:
./install.shThe installer:
asks which client or clients you want to configure: Copilot, Codex, Claude Code, Cline, or all of them
asks whether to install shared workflow instructions at the user level when supported or into a target project
writes the oboe-mcp MCP server entry into each client's real config file
installs the packaged OBO instructions, prompt, and skill files into the matching destination
explains what it is changing and makes timestamped backups before it updates existing files
The automated installer uses the current checkout path in uvx --from ..., so it is best when you are installing from a local clone of this repository.
If you want clients to install oboe-mcp from PyPI instead of a local checkout, follow the manual steps below.
Install the MCP server first so your agent can call the oboe_* tools. Then install the shared OBO instructions so your agent knows when to use those tools and how to follow the workflow correctly.
If you are wiring up an MCP config by hand, point it at either your local checkout or the published PyPI package.
Local checkout example:
"oboe-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "/absolute/path/to/oboe-mcp", "oboe-mcp"]
}Published PyPI example:
"oboe-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["oboe-mcp"]
}This repository includes reusable templates under templates/agent-setup/:
templates/agent-setup/copilot/copilot-instructions.md
templates/agent-setup/copilot/skills/one-by-one/SKILL.md
templates/agent-setup/copilot/prompts/obo.prompt.md
templates/agent-setup/AGENTS.md
templates/agent-setup/CLAUDE.md
Registering oboe-mcp only exposes the oboe_* tools. It does not by itself guarantee the overview-first, dependency-aware, one-item-at-a-time workflow shown in the toy example above. To make agent behavior reliable, install both parts:
the MCP server registration, so the agent can call the tools
the shared OBO instructions, so the agent knows when to switch from plain chat or a simple question tool into a real OBO session
Across clients, the same pattern applies:
Register oboe-mcp in the client's MCP configuration.
Copy or merge the packaged OBO instructions into the client's instruction location.
Keep existing repository guidance and merge the OBO rules into it instead of overwriting it.
Expect the installed instructions to tell the agent when OBO is preferred over plain chat, how to start with an overview, how to resume or merge existing sessions, and how to avoid direct JSON edits.
For Copilot, register oboe-mcp in your VS Code MCP config and then copy the packaged OBO files into either your VS Code user configuration or the target repository's .github/ folder.
Without those installed files, Copilot may still use plain chat or askQuestions-style interaction even though the MCP tools are available. The packaged instruction, skill, and prompt files are what push Copilot toward the full OBO workflow.
VS Code MCP config files are normally stored in the same user configuration folder as copilot-instructions.md. Add an oboe-mcp entry to mcp.json with either your local checkout path or the published PyPI package.
VS Code user configuration folders:
macOS: $HOME/Library/Application Support/Code/User
Linux: $HOME/.config/Code/User
Windows: $HOME/AppData/Roaming/Code/User
Install the packaged Copilot files in one of these two ways:
User-level installation:
Copy or merge templates/agent-setup/copilot/copilot-instructions.md into your user-level copilot-instructions.md
Copy or merge templates/agent-setup/copilot/skills/one-by-one/SKILL.md into skills/one-by-one/SKILL.md
Copy or merge templates/agent-setup/copilot/prompts/obo.prompt.md into prompts/obo.prompt.md
Repository-level installation:
Copy or merge templates/agent-setup/copilot/copilot-instructions.md into the target repository's .github/copilot-instructions.md
Copy or merge templates/agent-setup/copilot/skills/one-by-one/SKILL.md into the target repository's .github/skills/one-by-one/SKILL.md
Copy or merge templates/agent-setup/copilot/prompts/obo.prompt.md into the target repository's .github/prompts/obo.prompt.md
Use user-level installation when you want the OBO workflow available across repositories. Use repository-level installation when you want the workflow to travel with a specific project.
If the destination file already exists, merge the OBO rules into it instead of overwriting it. Adjust the wording where needed so the OBO instructions fit the project's existing review rules and conventions.
The templates/agent-setup/copilot/ folder in this repository is only the source package. Copilot will only discover the files after you install them into your VS Code user configuration folders or into the target repository's .github/ folder.
The Copilot instruction template tells agents to:
avoid direct edits to .github/oboe_sessions/*.json
use OBO when the user asks for one-by-one handling, when multiple findings need explicit sequential approval, or when resumable queue state is needed
use oboe_list_sessions, oboe_create, oboe_merge_items, oboe_next,
oboe_mark_in_progress, oboe_mark_blocked, oboe_mark_complete,
oboe_mark_skip, oboe_create_child_session,
oboe_complete_child_session, oboe_session_status, and
oboe_complete_session
use a structured question tool for predefined OBO choices such as resume, merge, replace, approval, navigation, reorder, restore, and stop
ask the user whether to resume, merge, replace, or stop when an active session already exists
only fall back to plain text when the structured question tool is unavailable, failing, or the response truly must be freeform, and explicitly state that reason
The packaged skill provides the trigger logic for when OBO should be used, and the prompt template provides an on-demand /obo workflow that walks an agent through the full sequential session lifecycle using the MCP server.
When VS Code connects to a remote host (SSH, Dev Container, or Codespaces), user-level MCP servers are launched on the local machine, not on the remote host. This means oboe-mcp will run locally and try to open workspace paths on the local filesystem — but those paths exist only on the remote host.
Symptom: tool calls like oboe_list_sessions(base_dir="/home/user/project") return an error such as:
ERROR: base_dir does not exist: /home/user/project
This often happens when the oboe-mcp server is running on your LOCAL machine
but your VS Code workspace is on a REMOTE host (SSH, Dev Container, Codespaces).
...Workaround: Add a workspace-level .vscode/mcp.json file inside the remote repository. VS Code Remote will then launch the server on the remote host where the workspace paths are accessible:
{
"servers": {
"oboe-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["oboe-mcp"]
}
}
}This requires uv to be installed on the remote host:
curl -LsSf https://astral.sh/uv/install.sh | shOnce uv is installed and .vscode/mcp.json is committed to the repository, VS Code Remote will launch oboe-mcp on the remote host automatically, where it can access workspace paths directly.
For Codex, the same two-part pattern applies: register the MCP server in ~/.codex/config.toml, then copy or merge the shared OBO instruction template into the target repository's AGENTS.md.
Register oboe-mcp in ~/.codex/config.toml:
[mcp_servers.oboe-mcp]
command = "uvx"
args = ["oboe-mcp"]Replace the GitHub URL with your local checkout path if you want Codex to run from a clone you already have on disk.
Then copy or merge templates/agent-setup/AGENTS.md into the target repository as AGENTS.md. If AGENTS.md already exists, merge the OBO rules into the existing file instead of replacing it.
The packaged AGENTS.md template tells Codex to:
switch from normal chat into OBO when the work needs durable queue state, explicit sequential approval, reordering, blocker tracking, or nested child sessions
start with oboe_list_sessions and ask whether to resume, merge, replace, or stop when an incomplete session already exists
begin each OBO session with an overview of scope, dependencies, and proposed order instead of jumping straight into the first item
use the MCP tools as the source of truth for session state rather than editing session JSON directly
use the agent's structured question UI/tool by default for predefined OBO menus and explain any plain-text fallback
For Claude Code, register the MCP server in ~/.claude/settings.json or by using the Claude CLI, and then copy the shared OBO instructions into CLAUDE.md or .claude/CLAUDE.md in the target repository.
As with Copilot and Codex, the MCP registration only exposes the tools. The instruction file is what tells Claude Code when OBO is preferable to plain chat and how the session flow should behave.
JSON config example for ~/.claude/settings.json:
{
"mcpServers": {
"oboe-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["oboe-mcp"]
}
}
}Register oboe-mcp in Claude Code:
claude mcp add --transport stdio --scope project oboe-mcp -- \
uvx oboe-mcpReplace the PyPI package with your local checkout path if you want Claude Code to run from a clone you already have on disk.
Then copy or merge templates/agent-setup/CLAUDE.md into the target repository as CLAUDE.md or .claude/CLAUDE.md. If one of those files already exists, merge the OBO rules into the existing instructions instead of replacing them.
The packaged Claude template tells Claude Code to:
use OBO for multi-item review flows that need durable state, explicit approvals, reordering, blockers, or nested child sessions
open with a summary of scope, major dependencies, and proposed order
keep the session updated after each approved action instead of letting the chat transcript become the only record
stop and surface a tool gap if a needed OBO action is not available through MCP
use the agent's structured question UI/tool by default for predefined OBO menus and explain any plain-text fallback
For Cline, register the MCP server in cline_mcp_settings.json and then copy or merge the OBO instructions into your Cline workspace guidance.
This follows the same pattern as the other clients: MCP registration exposes the tools, while the instruction text tells Cline when to use a durable OBO workflow instead of a lighter prompt or chat interaction.
A local stdio configuration for oboe-mcp looks like this:
{
"mcpServers": {
"oboe-mcp": {
"command": "uvx",
"args": ["oboe-mcp"],
"disabled": false
}
}
}On macOS, the default VS Code Cline MCP settings path is $HOME/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json. On Linux it is $HOME/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json. On Windows it is $HOME/AppData/Roaming/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json.
After registering the server, copy or merge the same rules from the Copilot or AGENTS template into Cline's workspace instructions or custom prompt setup. Cline's MCP config only exposes the tools; it does not replace explicit workflow instructions. If the target workspace already has Cline instructions, merge the OBO rules into the existing guidance rather than replacing it wholesale.
The installed Cline guidance should tell the agent to:
use OBO when work needs persistent queue state rather than a one-turn menu
start with a summary and proposed order before presenting the first item
update the stored session after each approval, skip, block, or completion
avoid direct edits to .github/oboe_sessions/*.json and index.json
use Cline's structured question UI/tool by default for predefined OBO menus and explain any plain-text fallback
If you are installing OBO for another agent, copy the shared OBO workflow rules into that client's preferred instruction location. If the agent only supports user-level or UI-defined instructions, paste the same rules there and keep the MCP registration separate. When an instruction file already exists, merge these rules with the existing guidance and resolve any conflicts explicitly.
The goal is to reproduce the same behavior described earlier in this README:
plain chat remains available for small single-step tasks
question tools remain available for short menu choices in the current turn
OBO becomes the preferred mode when the work needs a durable ordered queue, explicit approvals, dependency-aware ordering, blocker tracking, or nested child sessions
Minimal rule set to reuse across agents:
Never directly edit .github/oboe_sessions/*.json or index.json.
Start with oboe_list_sessions.
If an incomplete session exists, use a structured question tool when available to ask whether to resume, merge, replace, or stop.
Use oboe_create for new sessions and oboe_merge_items to append findings.
Start OBO work with an overview of scope, item ordering, and major dependencies.
Use a structured question tool by default for predefined OBO menus such as approval, navigation, reorder, restore, and stop.
Only fall back to plain text when no structured question tool exists, the tool is failing, or the response truly must be open-ended, and say why.
Present one item at a time and wait for explicit user approval before moving on.
Use oboe_next to choose work, oboe_mark_in_progress when starting,
oboe_mark_blocked when progress is blocked, and oboe_mark_complete or
oboe_mark_skip when resolving items.
Use oboe_create_child_session to step into nested sub-work and
oboe_complete_child_session to resume the parent session.
Use oboe_session_status or oboe_list_items to inspect state.
Use oboe_complete_session when no actionable items remain.
Session file paths, filename rules, JSON fields, status semantics, priority scoring, and the index.json summary format are documented in docs/SESSION_FORMAT.md.
Create a new OBO session file and update index.json atomically.
Args: base_dir: Project root directory (session goes in {base_dir}/.github/obo_sessions/) title: Human-readable session title description: What this session is reviewing items: List of item dicts (title, description, urgency, importance, effort, dependencies, category are all optional with defaults) session_filename: Optional explicit filename (e.g. session_20260314_120000.json). If omitted, generated from current timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| base_dir | Yes | ||
| title | Yes | ||
| description | Yes | ||
| items | Yes | ||
| session_filename | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It successfully discloses the atomic update behavior and the file path convention ({base_dir}/.github/obo_sessions/). However, it omits critical behavioral details such as error handling (e.g., what happens if the file exists), idempotency guarantees, or permission requirements for file system operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The docstring format is well-structured with a summary line followed by an Args section. Every sentence serves a purpose—either defining the operation or parameter semantics. The length is appropriate given the need to compensate for zero schema coverage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter tool with an output schema, the description adequately covers inputs and primary behavioral traits (atomicity, file location). Since an output schema exists, the description appropriately omits return value details, focusing instead on input requirements and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 0% schema description coverage, the Args section comprehensively compensates by documenting all 5 parameters. It provides semantic meaning for base_dir (project root with path template), explains the auto-generation logic for session_filename, and details the structure of items (listing optional sub-fields like urgency, importance, effort).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear action statement ('Create a new OBO session file') and specifies the atomic side effect ('update index.json atomically'). While it clearly distinguishes itself from sibling tools by verb ('Create' vs 'List', 'Mark', 'Update'), it does not explicitly name alternatives or differentiate use cases within the text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus its siblings (e.g., when to create a new session vs. updating an existing one with obo_update_field). There are no prerequisites, conditions, or exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return full detail for a single item.
Args: session_file: Absolute path or filename relative to {base_dir}/.github/obo_sessions/ item_id: Item ID (integer or string) base_dir: Required if session_file is a bare filename
| Name | Required | Description | Default |
|---|---|---|---|
| session_file | Yes | ||
| item_id | Yes | ||
| base_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions returning 'full detail,' it lacks information about error handling (e.g., item not found), caching behavior, idempotency, or side effects. The existence of an output schema is noted in context signals, but the description doesn't characterize the return value structure beyond the single phrase.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by a structured Args section. There is minimal waste, though the Args format duplicates structural information already present in the schema (parameter names) rather than integrating descriptions into prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (reducing the need for return value description) and only three parameters, the description is reasonably complete. It documents all parameters and states the retrieval purpose. However, it could improve by briefly mentioning the OBO domain context or error scenarios given the lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description effectively compensates by documenting all three parameters in the Args section: session_file includes path resolution logic relative to {base_dir}/.github/obo_sessions/, item_id clarifies acceptable types (integer or string), and base_dir explains its conditional requirement. This adds significant semantic value beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Return[s] full detail for a single item,' specifying the verb (return), resource (item), and scope (single, full detail). However, it does not explicitly differentiate from sibling tool obo_list_items or clarify when to use this versus other retrieval operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like obo_list_items, nor does it mention prerequisites (such as requiring an existing session) or error conditions. The Args section documents parameters but does not contextualize usage patterns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all items in a session, sorted by priority_score descending.
Args: session_file: Absolute path or filename relative to {base_dir}/.github/obo_sessions/ base_dir: Required if session_file is a bare filename status_filter: Optional — 'pending', 'in_progress', 'completed', 'skipped'
| Name | Required | Description | Default |
|---|---|---|---|
| session_file | Yes | ||
| base_dir | No | ||
| status_filter | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It adds valuable behavioral context about sorting (priority_score descending) but omits other important traits like whether the operation is read-only, idempotent, or what happens if the session file doesn't exist. It mentions 'List' which implies safety, but doesn't explicitly confirm this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear one-sentence purpose statement followed by an Args section. Every sentence earns its place—no filler text, and the parameter documentation is concise yet complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (covering return values), the description adequately covers the input parameters and core behavior. It successfully documents the complex path resolution logic. Minor gap: doesn't mention error handling scenarios (e.g., file not found), but this is acceptable given the parameter complexity handled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description excellently compensates by documenting all three parameters. It explains path resolution logic for session_file (absolute vs relative), conditional requirements for base_dir, and valid enum values for status_filter ('pending', 'in_progress', 'completed', 'skipped').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description provides a specific verb ('List') and resource ('items in a session'), and explicitly states the sorting behavior ('sorted by priority_score descending'). This clearly distinguishes it from siblings like obo_get_item (single item retrieval) and obo_list_sessions (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage context through the Args section, explaining when base_dir is required ('Required if session_file is a bare filename'). However, it lacks explicit guidance on when to use this versus alternatives like obo_get_item or obo_next, and doesn't state any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List OBO sessions from index.json.
Args: base_dir: Project root directory status_filter: Optional filter — 'active', 'completed', or 'incomplete' (incomplete = active sessions with pending items)
| Name | Required | Description | Default |
|---|---|---|---|
| base_dir | Yes | ||
| status_filter | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions data source 'index.json' and explains business logic for 'incomplete' status filtering. Missing safety/disposition info (read-only implied by 'List' but not stated), error handling, or performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Efficiently structured with purpose statement followed by Args block. No redundant sentences. The docstring-style 'Args:' format is slightly technical but serves the same function as front-loaded narrative without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a listing tool with output schema present (no return value explanation needed). Covers input parameters well given zero schema coverage. Could be improved by clarifying relationship to session management workflow and other list operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Excellent compensation for 0% schema description coverage. Documents both parameters: base_dir as 'Project root directory' and status_filter with valid enum values ('active', 'completed', 'incomplete') plus behavioral definition of 'incomplete'. Adds significant value beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb ('List') and resource ('OBO sessions') with data source ('index.json'). Clearly distinguishes from sibling obo_list_items by targeting sessions rather than items, though it doesn't explicitly reference the sibling differentiation in text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides implicit usage guidance by defining filter values ('active', 'completed', 'incomplete') and explaining the semantics of 'incomplete' status. However, lacks explicit when-to-use guidance relative to siblings like obo_session_status or obo_list_items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an item as completed with resolution text.
Args: session_file: Absolute path or filename relative to {base_dir}/.github/obo_sessions/ item_id: Item ID to mark complete resolution: Text describing how the item was resolved base_dir: Required if session_file is a bare filename
| Name | Required | Description | Default |
|---|---|---|---|
| session_file | Yes | ||
| item_id | Yes | ||
| resolution | Yes | ||
| base_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden but only states the core action. It lacks disclosure on persistence (is completion reversible?), side effects (what happens to the item after?), idempotency, or what the output schema contains despite the tool having a return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with a clear front-loaded purpose statement followed by structured parameter documentation. The Args format is scannable and information-dense, though slightly informal. No wasted words or redundant explanations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description correctly omits return value details. However, for a state-changing workflow tool with multiple siblings, it lacks context about the OBO session lifecycle, error conditions (e.g., already completed items), and the semantic meaning of 'complete' in this domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description fully compensates by documenting all 4 parameters in the Args section. It adds critical semantic context: the path relationship between session_file and base_dir, the purpose of resolution text, and conditional requirements for base_dir.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (mark as completed), the resource (item), and the distinguishing feature (resolution text). It effectively differentiates from siblings like obo_mark_skip (different outcome) and obo_get_item (read vs. write operation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus similar alternatives, particularly obo_mark_skip. It fails to mention prerequisites (e.g., item must exist) or when completion is appropriate versus other state changes like obo_update_field.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an item as skipped.
Args: session_file: Absolute path or filename relative to {base_dir}/.github/obo_sessions/ item_id: Item ID to skip base_dir: Required if session_file is a bare filename reason: Optional reason for skipping
| Name | Required | Description | Default |
|---|---|---|---|
| session_file | Yes | ||
| item_id | Yes | ||
| base_dir | No | ||
| reason | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It adds valuable behavioral context for path resolution (base_dir logic relative to .github/obo_sessions/), but fails to disclose mutation semantics, reversibility, side effects, or what the output schema contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Efficient Args-based structure with zero redundancy. Each line documents exactly one parameter with precise constraints. Front-loaded purpose statement followed by detailed parameter specs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a state-change tool with 4 parameters, given the output schema handles return value documentation. However, lacks workflow context (session advancement behavior) and safety implications of the skip action that would help an agent use it correctly in sequence with obo_next or obo_mark_complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Critical compensation for 0% schema description coverage. The Args section comprehensively documents all 4 parameters, including conditional requirements (base_dir required if bare filename) and path resolution logic that the schema completely lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the core action ('Mark') and target state ('skipped') for an 'item'. It implicitly distinguishes from sibling 'obo_mark_complete' via the 'skipped' vs 'complete' state distinction, though it doesn't explicitly name the sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use skip versus complete (obo_mark_complete), or workflow context (e.g., whether this advances to the next item). No prerequisites or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the next item to work on.
Returns in_progress items first (highest priority_score), then pending.
Args: session_file: Absolute path or filename relative to {base_dir}/.github/obo_sessions/ base_dir: Required if session_file is a bare filename
| Name | Required | Description | Default |
|---|---|---|---|
| session_file | Yes | ||
| base_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It successfully documents the selection algorithm (priority_score ordering and status precedence), but fails to disclose critical behavioral traits such as whether calling this tool locks/assigns the item, triggers state transitions, or error conditions when sessions are empty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately front-loaded with the core purpose, followed by behavioral details and an Args section. The formatting is clear despite being embedded in a string, with no redundant or wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (relieving the description of return value documentation), the description adequately covers the 2 parameters and retrieval logic. It could be improved by noting error states or side effects, but it is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, requiring the description to fully compensate. It successfully documents both parameters: session_file clarifies the path format relative to {base_dir}/.github/obo_sessions/, and base_dir explicitly states its conditional requirement ('Required if session_file is a bare filename').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Return[s] the next item to work on' with specific prioritization logic (in_progress items first by highest priority_score, then pending). This effectively distinguishes it from siblings like obo_list_items (which returns all) or obo_get_item (specific lookup).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the internal prioritization algorithm (which implies when certain items are returned), but lacks explicit guidance on when to use this versus alternatives like obo_get_item or obo_list_items, and does not mention prerequisites such as requiring an existing session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return summary statistics for an OBO session.
Args: session_file: Absolute path or filename relative to {base_dir}/.github/obo_sessions/ base_dir: Required if session_file is a bare filename
| Name | Required | Description | Default |
|---|---|---|---|
| session_file | Yes | ||
| base_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read-only operation via the word 'Return,' but does not disclose idempotency, error behavior (e.g., what happens if session_file doesn't exist), performance characteristics, or what specific statistics are included in the summary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is optimally concise with zero wasted words. It front-loads the purpose statement and uses a structured Args section to document parameters efficiently. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (which obviates the need to describe return values) and the description's coverage of both parameters, the definition is adequately complete for a simple retrieval tool. It could be improved by mentioning error handling for missing files.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by documenting both parameters in the Args section: session_file's path resolution logic (absolute vs. relative to {base_dir}/.github/obo_sessions/) and base_dir's conditional requirement. This adds essential meaning missing from the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Return[s] summary statistics for an OBO session,' providing a clear verb and resource. However, it does not explicitly differentiate from sibling tool obo_list_sessions, which also deals with sessions but returns a list rather than statistics for a specific session file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like obo_list_sessions or obo_get_item. There are no prerequisites, conditions, or workflow context provided to help the agent select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update any field on an item. Auto-recalculates priority_score when a score component (urgency, importance, effort, dependencies) is changed.
Args: session_file: Absolute path or filename relative to {base_dir}/.github/obo_sessions/ item_id: Item ID to update field: Field name (e.g. 'urgency', 'title', 'description', 'status') value: New value (always passed as string; numeric fields are cast automatically) base_dir: Required if session_file is a bare filename
| Name | Required | Description | Default |
|---|---|---|---|
| session_file | Yes | ||
| item_id | Yes | ||
| field | Yes | ||
| value | Yes | ||
| base_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full disclosure burden. It successfully documents important behavioral traits: automatic recalculation of priority_score, string-to-numeric type casting for values, and the conditional path resolution logic for base_dir.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Appropriately structured with purpose stated first, followed by behavioral side effects, then detailed parameter semantics. Dense but necessary given schema deficiencies. No redundant content, though the docstring-style Args format is slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (covering return values), the description provides sufficient context for this mutation tool. It covers the 5 parameters, side effects, and path resolution logic. Minor gap regarding explicit sibling relationships prevents a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage. The Args block comprehensively compensates by documenting all 5 parameters with specific path semantics (session_file), examples (field names), type handling rules (value casting), and conditional requirements (base_dir).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the core action ('Update any field on an item') and identifies the resource. The mention of 'any field' implicitly distinguishes this general-purpose updater from specialized siblings like obo_mark_complete, though explicit differentiation is absent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when auto-recalculation of priority_score occurs (score component changes), providing useful context for side effects. However, it lacks explicit guidance on when to use this tool versus specialized alternatives like obo_mark_complete or obo_mark_skip for status changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose with no ambiguity: create sessions, get/list items, list sessions, mark items complete/skip, find next item, get session status, and update item fields. The operations target specific resources and actions without overlap.
All tools follow a consistent 'obo_verb' or 'obo_verb_noun' pattern (e.g., obo_create, obo_get_item, obo_list_sessions). The naming is uniform throughout, using snake_case and clear action descriptors.
With 9 tools, the server is well-scoped for managing OBO sessions and items. Each tool serves a distinct function in the workflow, from creation to status tracking, without being excessive or insufficient for the domain.
The toolset provides complete CRUD/lifecycle coverage for OBO sessions and items: create sessions, list/get/update items, mark items as complete/skip, track status, and find next tasks. No obvious gaps exist for the stated purpose of session management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for Product Management
Evidence-readiness MCP server: validate, audit, and score briefs, memos, and evidence packs.
MCP server for VC pitch-deck scoring, thesis-fit matching, and deal-flow management.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Warnes-Innovations/oboe-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
