TeamHub MCP is a git-native MCP server that gives AI coding agents shared, structured team context—plans, tasks, file notes, and activity—so teammates working on the same repo stay in sync.
Start a session by pulling a full handoff brief: plan docs, open/abandoned/done tasks, structured completions, file history, and recent activity (optionally filtered by scope).
Declare tasks with scope and dependencies, get conflict warnings against other declared tasks and recent git commits, then claim tasks for yourself.
Update task statuses: mark done with a structured completion report (what was built, decisions, files changed, limitations, next steps) or abandon with a reason.
Read and revise the living requirements.md and design.md plan documents.
Log what you're doing right now, including mid-task pivots so teammates see direction changes.
Attach rationale notes to files that are pinned to the current commit; later reads tell you if the note is still verified, changed, or gone.
Quickly check a file just before editing it for fresh teammate commits and related notes, avoiding stale assumptions in long sessions.
Inspect a task's full status history to understand how it reached its current state.
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., "@teamhub-mcp show me the current handoff brief for this repo"
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.
Shared context for teams where everyone uses their own AI coding agent — Claude Code, Cursor, Antigravity, OpenCode, doesn't matter which — on the same repo.
If everyone on your team is running their own AI agent session, nobody's agent knows what a teammate already decided, what they're building right now, or why some file looks the way it does. People end up duplicating each other's work or quietly stepping on it, and eventually one person is doing everything by hand because the AI-assisted parallel work just doesn't hold together.
The normal fix is git pull, then tell your agent "look at this and build X" — which just moves the burden back onto a human, every single handoff. And it gets worse when teammates use different models: Claude, Gemini, and GPT will happily draw different conclusions from the same paragraph of context.
teamhub-mcp is git-native. No hosted backend, nothing to deploy, no account to make. It's a small MCP server that each person runs locally against their own clone (the CLI is called hub-server). State is just JSON files under .hub/ in the repo, and it moves around the same way your code does — git push, git pull. If you have access to the repo, you have access to the shared context. There's no separate workspace ID or token to hand out.
Related MCP server: CollabMCP
cd your-repo
npx -y teamhub-mcp initThat scaffolds .mcp.json, .claude/settings.json, and the hook scripts into your repo. One thing worth knowing: the npm package is teamhub-mcp, but the command it installs is hub-server — there's already an unrelated package called hub-server on npm, so typing npx -y hub-server will silently grab the wrong thing. Stick to npx -y teamhub-mcp <command>.
init won't clobber anything — it skips files that already exist unless you pass --force, and if you already have a .claude/settings.json it merges the hooks in rather than overwriting whatever else you've got configured there. Commit whatever it creates so teammates get the same setup the moment they clone the repo.
Want to poke at it without going through an agent? npx -y teamhub-mcp dashboard prints a plain-text summary of the current tasks and activity.
If you're working on teamhub-mcp itself rather than using the published package:
npm install && npm run build && npm link
cd your-repo && hub-server initA living plan, not just a to-do list. requirements.md and design.md live in .hub/plan/ and get updated as the project evolves, so the big picture isn't stuck in one person's head or buried in a chat transcript somewhere.
Completion reports with a fixed shape, not a paragraph. When someone finishes a task, they fill in what was built, the decisions they made and why, which files changed, known gaps, and what's next — as structured fields, not prose. The reason this matters more than it sounds: if your teammates are on different models, free text gets reinterpreted differently by whoever reads it next. A fixed shape doesn't have that problem.
File notes that check their own freshness. Every note about a file is pinned to the commit it was written against. Read it later and it'll tell you verified (nothing's changed), changed (go re-read the file, don't trust this blindly), or gone. A note that's quietly out of date is worse than no note at all.
One call that gets you everything. get_handoff_brief bundles the plan, open tasks, recent completions, and file history into a single response, and it's what gets auto-injected at session start. The point is that it's the same for everyone — nobody's agent has to decide on the fly how much digging is "enough."
Conflict detection that looks at real git history, not just declared tasks. declare_task checks other declared tasks and actual recent commits touching the same files, so it catches a teammate who's mid-edit even if they never bothered to declare anything.
Dependencies, for the case file-overlap can't catch. "Build POST /api/auth" and "wire the login form to it" touch completely different files, so nothing about overlapping scopes will ever flag that the second can't start until the first exists. Mark it with dependsOn and you get told at claim time — and the handoff brief shows which tasks are actually startable versus waiting on something.
Completions written from the real diff, not memory. get_diff_for_task shows everything that changed since you claimed it, committed and uncommitted, so the completion report lists what you actually touched. In a long session it's easy to forget files you edited early, or to describe an approach you later reverted — and since the uncommitted-file check only inspects the paths you list, an incomplete list quietly defeats that check too.
You just tell it which repo you're working on. At session start it asks (via MCP's elicitation feature) which GitHub repo you're on, and figures out your local clone from there. Whoever's working on the same repo is on the same team — nothing extra to set up.
Handoffs here are sequential — one person finishes and pushes, the next person pulls and continues — not simultaneous editing, so a plain git-synced log is enough to keep everyone in sync. No CRDTs, no custom merge logic, and (after actually looking into it) no live messaging between agents either — more on that below.
your-repo/
.hub/
plan/requirements.md the why/what
plan/design.md the architecture/how
tasks/<taskId>.json one file per task
activity/<ts>-<id>.json one file per activity event
notes/<file/path>/<ts>-<id>.json one file per file note, anchored to a commitOne file per record is the important decision here. Two people writing "at the same time" never touch the same file, so git can't produce a merge conflict from ordinary use. The one real race condition — two people claiming the same task at once — is handled explicitly: claim_task re-checks after a rejected push and tells you the truth instead of quietly overwriting the other person's claim.
Tool | What it does |
| Call this when you're picking up someone else's work. Bundles the plan, open tasks, recent completions, and file history in one shot. Can filter by |
| The lightweight version — just tasks and recent activity. |
| Read or replace |
| Propose a task with a scope. Comes back with any declared tasks that overlap, plus real git commits touching the same files in the last 10 minutes from anyone else. Takes an optional |
| Claim an unclaimed task, or your own. Tells you about recent activity on those files and any dependencies that aren't finished yet. |
| What actually changed since you claimed the task, committed and uncommitted. Call this before writing a completion. |
| Move a task forward. Marking it |
| "Here's what I'm doing right now." Use |
| Leave a note on a file you just finished touching. |
| Read a file's notes, each one tagged with whether it's still trustworthy. |
| A fast check on one file before you touch it — cheaper than the full handoff brief, useful in a long session where your original context might be stale. This is what backs the Claude Code enforcement gate. |
| The full status history of a task. |
No login, no auth tool. Every tool takes an optional memberName, and if you don't pass one it just uses git config user.name.
Hooks are plain Node scripts (.mjs), not bash — Node's already a hard requirement, so this avoids needing Git Bash or WSL on Windows. This wasn't just a style choice: npm installs hub-server as a .cmd file on Windows, which Node can't run directly without a shell, and getting that right (safely, without the argument-injection issues that come with shelling out carelessly) took some real work.
Claude Code is the one I've actually verified end to end. The SessionStart hook really does get its output into the model's context — I checked by putting a made-up string in the hook and asking a fresh session if it saw anything unusual, and it reported the string back. The PreToolUse enforcement gate works too: I ran a real claude -p session, watched it get denied on a raw edit, watched it correctly call get_handoff_brief to clear the gate, then watched the edit go through. It's not bulletproof — a blocked model can still route around it through Bash instead of Edit, and it can only catch built-in tool calls, not MCP calls directly, so the gate works by having the MCP server itself leave a marker the hook can check. It also only enforces checking in before you edit, not recording what you did afterward — there's no equally clean hook for that yet.
Antigravity should get context injected the same way, but I haven't been able to verify it live — there's no scriptable CLI on my machine to test it the way I could with Claude Code. The enforcement gate isn't built for it at all: Antigravity's docs mention something that might allow blocking a tool call, but it's not confirmed, and I'd rather leave it out than ship something that looks like it works and quietly doesn't.
Cursor and OpenCode have hooks written for them but I haven't tested either against a real install. Codex CLI has nothing yet — there's no session-start hook to attach to upstream, so it'd need a different approach (wrapping the binary) that isn't built.
This is asked once per session and then cached for the rest of that process:
If you set HUB_REPO_PATH, that wins, full stop.
Otherwise it asks you directly — "which GitHub repo are you working on?" — through MCP's elicitation feature, and then works out your local clone from the answer: checking if the auto-detected folder's git remote matches, checking a cache of past answers on this machine, doing a quick scan of ~, ~/Desktop, and ~/Documents for a matching clone, or just asking where you put it.
If the client doesn't support elicitation, or you don't answer, it falls back to MCP's roots protocol and then plain process.cwd().
I built a test client that supports elicitation to confirm this actually works, including launching from a totally unrelated folder and having it find the right clone anyway. Claude Code itself doesn't trigger the prompt as of writing — I tested with claude -p and no prompt showed up, so it just falls through to the cwd-based fallback, which still works fine. Whether Antigravity supports elicitation, I don't know yet.
One thing to be aware of: if you've got more than one local clone of the same repo, it'll pick whichever one it finds first, which might not be the one you meant. Normal one-clone-per-person setups are unaffected.
The reason there's a fallback chain at all is that some harnesses — Antigravity is the one I ran into — launch a globally registered MCP server from their own install folder instead of your actual project. That's a known issue on their end (there are open GitHub issues about it), not something specific to this tool.
The obvious fix for "my teammate's agent doesn't know what happened" is to hand it more text — a longer summary, more files. That doesn't really solve it, for two reasons:
Different models read the same prose differently. Claude, Gemini, and GPT can draw genuinely different conclusions from the same free-text explanation. A fixed set of fields doesn't have that problem — the shape stays the same no matter which model wrote it or which one is reading it.
And a summary that's gone stale is worse than no summary, because it looks trustworthy while being wrong. Pinning every note to the commit it was written against, and checking that on every read, means you're told explicitly when something's moved on instead of quietly building on outdated information.
I looked into this seriously before deciding against it. There's a study measuring exactly this tradeoff that found adding messaging channels increases overhead for sequential handoffs like this one — one person finishes, another continues later — because the files already carry the coordination; messaging mainly helps when work is genuinely simultaneous. Every option I found for doing this without standing up a hosted service either broke the "no server to run" idea or had already been tried and dropped by similar tools for good reasons (auto-committing on every file save floods a shared branch with half-finished code, for instance).
Conflict detection on declare_task is a plain string match on scope — good for "same file," won't catch two people building the same feature under different names. (Dependencies between tasks are handled separately, via dependsOn.)
Dependencies are a warning at claim time, not a hard block. If you want to start something that isn't ready yet, nothing stops you — you're just told.
Small hub: commits pile up fast. Might batch these later if it turns out to bother people in practice.
If there's no git remote (a solo project, or just testing), everything still works — it just skips the sync step.
Cursor and OpenCode hooks exist but haven't been tested against real installs. Antigravity doesn't have an enforcement gate yet.
I'm maintaining this alone, and it depends on hook/MCP APIs from several companies that are all still changing quickly. Expect some breakage as those move.
Support for Codex CLI, probably via wrapping the binary since there's no hook to attach to.
A fallback that keeps AGENTS.md in sync for harnesses without real hooks at all.
A small local web dashboard on top of the same data dashboard --json already returns.
Turning the scope-overlap warning into an actual block, with a way to negotiate instead of just flagging it.
The PreToolUse gate for Cursor, once I can confirm it actually works there.
Role-based visibility, surfacing tasks on GitHub PRs, multi-repo setups.
Issues and PRs are welcome, especially reports of what happens when you try this on a harness I haven't verified yet (Cursor, OpenCode, Antigravity's gate). Right now, an honest "I tried it and here's what broke" is more useful than a feature request.
MIT — see LICENSE.
Fast, single-file freshness check - call this immediately before editing any file that's part of a shared interface or that you haven't touched yet this session, ESPECIALLY in a long-running session. Returns anchor-verified notes on the file plus real commits from anyone else touching it in the last 15 minutes. This is cheaper than get_handoff_brief and catches drift a session-start snapshot misses (a teammate can commit to this exact file while you're mid-session).
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full behavioral burden. It discloses useful traits: the check is fast, single-file, returns anchor-verified notes, includes real commits from the last 15 minutes, and catches mid-session drift. It does not explicitly state side-effect behavior (e.g., read-only) or failure behavior, but 'check' strongly implies a non-mutating operation.
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 compact, front-loaded with the key action and timing, and every sentence earns its place: usage conditions, return contents, and a comparative cost signal. No redundant or filler phrasing is present.
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 one-parameter tool with no output schema and no annotations, the description covers the main invocation context, what is returned, and how it relates to alternatives. It does not specify the exact response structure or how to interpret 'anchor-verified' results, but it provides enough for most agents to call and use the tool correctly.
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%, and the description does not explain the filePath parameter's required format, whether it must be absolute or relative, or any constraints. Phrases like 'single-file' and 'this exact file' merely reinforce the parameter name rather than adding semantic detail an agent would need to invoke it correctly.
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 a specific action ('freshness check') and resource ('single-file'), and clearly positions the tool as the thing to call immediately before editing a file. It also differentiates from alternatives by naming get_handoff_brief as more expensive and by contrasting against a session-start snapshot.
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 gives explicit conditions for when to use it: 'immediately before editing any file that's part of a shared interface or that you haven't touched yet this session, ESPECIALLY in a long-running session.' It also provides an alternative comparison, noting it is cheaper than get_handoff_brief and catches drift that a session-start snapshot misses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim an existing task (e.g. one from get_context) so teammates know you're working on it. Returns recentActivityNearby - real commits touching this task's scope in the last 10 minutes from anyone else. A non-empty list doesn't block the claim, but check it before diving in.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | ||
| memberName | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the behavioral burden and does a good job: it discloses the recentActivityNearby return value, explains it contains real recent commits from others, and explicitly notes that a non-empty list does not block the claim. It could go further on persistence, permissions, or side effects, but the core behavior is clearly communicated.
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?
Three sentences, each earning its place: purpose first, then the key return value, then the important caveat about non-blocking behavior. No wasted words and the most decision-relevant information is front-loaded.
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 no annotations, no output schema, and minimal input schema, the description is fairly complete for a simple claim action. It explains purpose, source of the task, what the return contains, and how to interpret it. The main missing piece is parameter semantics, particularly memberName, and clearer routing against sibling tools.
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%, and the description adds little parameter-level meaning. It implies taskId comes from get_context, but never explicitly names or explains taskId, and memberName is entirely absent from the description. This is a meaningful gap for two parameters.
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 uses a specific verb ('claim') and resource ('existing task'), and clearly states the purpose: signaling to teammates that you're working on it. It also points to get_context as a source of the task, helping differentiate from creation-oriented siblings like declare_task.
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 implies the usage context: after getting a task from get_context and before diving in. However, it never explicitly states when not to use this tool or names alternatives like declare_task, update_task_status, or log_activity, so the agent must infer the boundary between these siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Propose a task: title, scope (file paths / module / route names it'll touch), and optionally the interface it'll expose and assumptions being made. Leaves the task UNCLAIMED (owner is not set to you automatically) - call claim_task right after if you intend to build it yourself, so teammates can otherwise pick it up. Commits and pushes to .hub/tasks/. Returns conflicts (other declared tasks touching the same scope) AND recentActivityNearby (real git commits touching this scope in the last 10 minutes, from anyone else - catches a teammate mid-edit right now even if they never declared a task for it). Check both before proceeding.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes | File paths, module names, or API routes this task will touch. | |
| title | Yes | ||
| memberName | No | Defaults to git config user.name. | |
| assumptions | No | ||
| declaredInterface | No | e.g. 'POST /reconcile -> {status, exceptions[]}'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so well. It explicitly states that the task remains UNCLAIMED, that the tool commits and pushes to '.hub/tasks/', and that it returns both 'conflicts' and 'recentActivityNearby' to catch teammates mid-edit. These are exactly the side effects and behavioral nuances an agent needs to know.
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 and front-loaded: the first sentence states the core purpose and inputs, the second clarifies ownership semantics, the third discloses side effects, and the fourth explains return values and required checks. Every sentence earns its place, and there is no filler or repetition.
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 no output schema and no annotations, the description covers most essential operational context: what it writes, what it returns, and what to do next. It names the return fields with explanations, but does not describe the exact structure of 'conflicts' or 'recentActivityNearby', nor any failure modes. For a 5-parameter tool with no schema on return values, this is still a strong, mostly complete description.
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 coverage is 60%, and the description adds meaningful context for the main parameters: 'scope' is defined as file paths, module names, or API routes; 'interface' and 'assumptions' are framed as optional. It does not mention 'memberName', but the schema already documents its default behavior, so this is a minor gap. Overall, the description compensates for the schema's missing parameter details for title and assumptions.
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's purpose: 'Propose a task' with title, scope, optional interface, and assumptions. It also names the exact artifact it touches ('.hub/tasks/') and explicitly differentiates itself from the sibling 'claim_task' by noting the task is left unclaimed. This makes it easy for an agent to select this tool over its siblings.
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 explicitly says when to use this tool vs. alternatives: call it to propose a task, then call 'claim_task' if you intend to build it yourself, so teammates can otherwise pick it up. It also instructs the agent to check 'conflicts' and 'recentActivityNearby' before proceeding, giving concrete next-step guidance. This is unusually clear usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the current shared plan from .hub/ in this repo: all tasks (status/owner/declared interface), and recent teammate activity. Pulls the latest from git first. For picking up someone else's work, prefer get_handoff_brief instead - it also includes the requirements/design docs, structured completion reports, and anchor-verified file history in one deterministic call.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It transparently states that it fetches from .hub/, what content it returns, and that it pulls the latest from git first. It does not detail failure modes or explicitly label the operation as read-only, but the side effect of the git pull is disclosed, which is meaningful for a zero-parameter tool.
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?
Two sentences accomplish a lot: the first fronts the primary purpose and content, the second adds the git behavior and the sibling alternation. Every sentence earns its place, with no filler or repetition.
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 zero-parameter tool with no output schema and no annotations, the description covers the source, the data returned, the git-pull behavior, and the main alternative. It could go slightly further by noting the output shape or failure conditions, but the enumerated content gives an agent a solid mental model of what to expect.
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 tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to explain. Per the rubric, a zero-parameter tool gets a baseline of 4; the description adds no misleading parameter information and focuses on behavior and output content.
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 a specific verb ('Fetch') and resource (shared plan from .hub/ plus recent teammate activity), and enumerates the contained data: tasks with status/owner/declared interface. It also names the sibling alternative get_handoff_brief, making it easy for an agent to distinguish this tool from similar context-gathering tools.
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?
Explicitly tells the agent when to use a different tool: 'For picking up someone else's work, prefer get_handoff_brief instead', with a concrete reason (it includes richer handoff-specific context). This is clear routing guidance beyond a generic description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the rationale trail for a specific file - what teammates did to it and why, before you continue it. Each note carries an anchorStatus: 'verified' (file unchanged since the note), 'changed' (modified since - re-read the file before trusting the note), 'gone' (deleted), 'unknown'.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. It goes beyond the tool name by explaining the anchorStatus values and their practical implications ('re-read the file before trusting the note'), which is genuinely useful. It does not mention side effects or error behavior, but 'get' implies a read operation.
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?
Two sentences with the core purpose front-loaded and the status semantics compactly explained in the second. Every phrase contributes information; no padding or restatement of the title.
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 simple one-parameter read tool, the description covers purpose, usage timing, and the key return nuance (anchorStatus). The main gap is the lack of filePath semantics and a fuller response shape, but the definition is sufficient for selection and likely 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?
The only parameter, filePath, has no schema description (0% coverage), so the description was expected to compensate. It says 'a specific file' but provides no path format, relative/absolute distinction, or workspace context. An agent would still need to guess the accepted path form.
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 a specific verb ('Get') and resource ('rationale trail for a specific file'), and clearly defines what the history contains: what teammates did and why. This distinguishes it from sibling tools like get_task_history or check_file_before_edit, which target different resources or current state.
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?
Explicitly positions the tool as something to use 'before you continue' a file, which gives a clear trigger for invocation. It does not name alternative tools or explicitly say when not to use it, but the contextual cue is strong enough for most routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
THE tool to call when picking up work someone else started, or at the start of any session on a shared repo - call this INSTEAD OF assembling context yourself from several calls. Deterministically bundles: requirements + design (why/how), active/unclaimed tasks (what's left), recently completed tasks with their structured completion reports (what was just built, key decisions, why), recently ABANDONED tasks with why they were dropped (so you don't redo a dead end or wonder why something looks half-finished), recent activity, and anchor-verified file history for every file those completions touched. Optionally filter by scope (e.g. ["frontend"]) to focus on one area.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Filter to tasks/files touching any of these scope tags. Omit for everything. | |
| doneLimit | No | Max recently-done tasks to include (default 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the tool deterministically bundles multiple data categories, includes abandoned tasks specifically to avoid redoing dead ends, and provides anchor-verified file history. It does not mention auth, rate limits, or exact output structure, but it gives a strong sense of what happens and why.
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 primary use case and then packs in detailed content about what the brief contains and why. It is a long, dense sentence, but each clause contributes useful context about the tool's behavior or rationale.
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 there is no output schema and no annotations, the description does a good job of explaining what the tool returns by enumerating the bundled content areas and the reasoning behind them. It could be more complete by mentioning the sibling get_context tool or explicitly describing the response shape, but it provides enough 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 coverage is 100%, so the baseline is 3. The description adds meaningful value to the scope parameter by giving a concrete example ('frontend') and explaining that it focuses the brief on one area. The doneLimit parameter is not mentioned in the description, but the schema already documents its default and purpose.
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 a specific action and resource: getting a bundled handoff brief containing requirements, tasks, completions, and file history. It is very clear about the intended session contexts, but it does not explicitly distinguish itself from sibling tools like get_context, instead differentiating against manual context assembly.
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 gives explicit trigger conditions: picking up someone else's work or starting a session on a shared repo, and it explicitly tells the agent to use this instead of assembling context from several calls. It does not name alternative sibling tools or provide a 'when not to use' condition, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the two living plan documents: requirements (the why/what) and design (the architecture/how). Read this alongside get_context/get_handoff_brief to understand intent, not just the task list.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. 'Read' clearly signals a non-mutating operation, and 'living plan documents' conveys that these are current, maintained artifacts. It adds context about document contents, though it does not describe return format or staleness handling.
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?
Two compact sentences front-load the core action and resource, then add complementary guidance. The phrase 'not just the task list' efficiently disambiguates from sibling tools without unnecessary bulk.
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 simple, parameter-less read tool, the description provides the action, the exact documents, their semantic purpose, and guidance to combine with sibling tools. Nothing required for correct invocation is missing.
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 tool has zero parameters, so the schema covers parameter semantics completely. The description adds no parameter-specific detail, but none is needed; the baseline for zero-parameter tools is 4.
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 specifies a concrete action ('Read') on a clear resource ('the two living plan documents') and identifies their contents (requirements and design). It also distinguishes itself from task-list tools by noting 'not just the task list,' which differentiates it from siblings like get_context.
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 explicitly tells the agent to use this tool alongside get_context/get_handoff_brief to understand intent, providing a clear complementary usage context. It does not spell out when not to use it or name alternatives beyond that, so it stops short of fully explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
See every status transition a task went through (todo -> claimed -> in_progress -> done/abandoned) with who made each change and when - useful when a task's current state alone doesn't explain how it got there, e.g. it was abandoned then reclaimed then abandoned again.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses what the tool returns (status transitions, actor, and timing) and uses 'See' to imply a read-only operation. It does not explicitly state non-mutation or edge-case behavior, but for a history getter this is mostly sufficient.
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 one focused sentence that front-loads the core behavior and adds a useful usage example after the dash. Every clause adds value, with no filler or repetition.
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 one required parameter, no output schema, and no annotations, the description provides sufficient context: what is returned, who/when, and when it is useful. Minor gaps include no explicit ordering or mention of how missing taskIds are handled, but these do not prevent correct selection and 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 coverage is 0% and the description does not explicitly define taskId or its format. However, the phrase 'a task went through' indirectly maps the taskId parameter to the task whose history is returned, and the single self-explanatory parameter limits ambiguity.
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 identifies the action and resource: seeing every status transition for a task, including who made each change and when. It is clearly about task status history rather than current state, but it does not explicitly differentiate itself from sibling tools like get_file_history or get_context.
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 a concrete when-to-use condition: when a task's current state alone doesn't explain how it got there, with an abandoned/reclaimed example. It does not mention alternatives or when not to use the tool, so it stops short of a full routing guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Broadcast what you're currently doing, so teammates' get_context/get_handoff_brief calls show it in recent activity. Use kind 'pivoted' specifically when you change approach mid-task without abandoning it outright - detail should say what you were doing, what you're doing instead, and why - so teammates see the change of direction immediately instead of working from your original (now stale) plan.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | e.g. 'started', 'editing', 'committed', 'finished', 'pivoted'. | |
| files | No | ||
| detail | Yes | ||
| memberName | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of explaining side effects. It does so by stating that the call broadcasts to teammates, surfaces in recent activity, and is immediately visible so teammates do not rely on stale plans. It does not mention optional-field side effects or persistence details, but the core behavioral impact is disclosed.
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 two sentences with no filler. The first sentence front-loads the core purpose, and the second adds the only non-obvious usage detail—pivoted semantics and required detail content—without repeating schema information.
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 simple broadcasting tool with no output schema and no annotations, the description gives enough guidance to call it correctly for the required parameters. The main gap is the undocumented optional parameters 'files' and 'memberName,' but the central behavior and required-input expectations are clear.
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 coverage is only 25%, so the description must compensate. It adds meaningful semantics for 'kind' and 'detail' by specifying the pivoted case and what detail should contain. However, 'files' and 'memberName' remain completely unexplained, so the description only partially compensates for the low schema coverage.
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 uses a specific verb—'Broadcast'—and a clear object, 'what you're currently doing.' It also explains the outcome: the activity will appear in get_context/get_handoff_brief calls. This clearly distinguishes it from sibling task-management and planning tools.
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 gives clear context for when to log activity and provides an explicit rule for the 'pivoted' kind: use it when changing approach mid-task without abandoning it outright. It also explains what detail should capture. However, it does not explicitly name alternative tools or state when not to use log_activity versus those alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach a short rationale note to a file you finished touching (what you did, why). Pinned to the current commit as an anchor - anyone continuing this file later gets told via get_file_history whether the file has changed since (so they know if the note is still trustworthy).
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | ||
| filePath | Yes | ||
| reasoning | No | ||
| memberName | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does reveal that the note is pinned to the current commit and that consumers can check whether the file has changed to judge trustworthiness. However, it does not disclose whether repeated calls append or overwrite notes, what happens if the file changes, or any permission/mutation implications.
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 two sentences with no filler. The core action is front-loaded, and the second sentence adds only the high-value anchoring and trustworthiness context. Every clause 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?
The description covers the tool's purpose and its main downstream interaction with get_file_history, which is helpful. However, it leaves important operational gaps: parameter semantics for memberName, repeated-call behavior, and whether the note is one-per-file or one-per-commit. For a four-parameter tool with no output schema and no annotations, this is a moderate but not complete definition.
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%, so the description must compensate for the absence of parameter documentation. It partially does by mapping 'what you did, why' to the summary/reasoning fields and implying filePath via 'file', but it gives no meaning for memberName and leaves the relationship between summary and reasoning ambiguous.
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 names a specific verb and resource: attach a rationale note to a file. It also clarifies the content (what you did, why) and distinguishes the tool from siblings like get_file_history by describing the note as a commit-anchored comment rather than a retrieval or task-tracking 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 phrase 'a file you finished touching' gives a clear trigger condition for when to use the tool. It also references get_file_history as the mechanism through which the note will later be surfaced, giving the agent a meaningful context signal. It does not explicitly list exclusions or alternatives, but the timing guidance is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the full content of one plan document (requirements.md or design.md) with new markdown. Read get_plan first and edit the whole doc, don't append blindly - this is the shared source of truth for project intent that every teammate's agent reads.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | ||
| content | Yes | Full replacement markdown content for this document. | |
| memberName | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It clearly warns that this is a full-content replacement affecting a shared source of truth read by every teammate's agent, which is crucial context. It does not mention recovery or permissions, but the destructive overwrite nature is well conveyed.
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?
Two focused sentences convey the operation, the precondition, the warning, and the rationale. There is no filler or repetition of schema details.
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 straightforward document-replacement tool, the description covers the essential behavior, the risk of overwriting shared content, and the recommended read-before-write flow. It doesn't describe the return value, but no output schema exists and the operation is simple enough that this is a minor gap.
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 only 33%, with only 'content' described. The description adds useful meaning by mapping the 'doc' parameter to requirements.md or design.md, but it does not clarify the optional 'memberName' parameter, leaving a gap.
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 names a specific verb and resource: it replaces the full content of one plan document (requirements.md or design.md) with new markdown. This clearly distinguishes it from sibling read tools like get_plan and other task-status tools.
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?
It gives clear procedural guidance: read get_plan first, edit the whole document, and do not append blindly. It does not explicitly enumerate when-not-to-use cases or alternative update paths, so it falls just short of a top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a task's status. When marking a task 'done', ALWAYS include completion with this fixed shape (not a free-text summary) - a structured report is what stays consistent when a different model reads it later, unlike prose that gets reinterpreted differently by every reader: whatWasBuilt (1-3 sentences), decisions (each with decision/why/alternativesConsidered), filesChanged (each with path/purpose), knownLimitations, nextSteps. This becomes the permanent, queryable design record in .hub/tasks/ for teammates, and feeds get_handoff_brief. IMPORTANT: if the response includes uncommittedFileWarnings, the files you listed in filesChanged are NOT actually committed/pushed yet - commit and push them for real before telling the user this is done, or teammates will never see the code. If you're changing direction WITHOUT finishing (switching approach, or dropping it), set status 'abandoned' with abandonReason instead of just going quiet - an abandoned task is reclaimable by teammates and shows up honestly in get_handoff_brief; a task silently left 'in_progress' forever looks like someone's still on it.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| taskId | Yes | ||
| completion | No | Required (in practice) when status is 'done'. | |
| memberName | No | ||
| abandonReason | No | Required (in practice) when status is 'abandoned' - why you stopped without finishing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden and delivers richly: it discloses that the completion record becomes 'the permanent, queryable design record in .hub/tasks/' that 'feeds get_handoff_brief,' and that uncommittedFileWarnings means the listed files are 'NOT actually committed/pushed yet.' It also reveals the social consequence of abandoning versus silently leaving a task in_progress, which the schema and annotations do not convey. No contradiction with annotations.
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?
Roughly 200 words, but the tool has conditional behavior, a nested object, and a side-effect warning, so the length is largely earned. It front-loads the core purpose and highest-stakes rule (done → completion) before the abandon guidance. Some rationale prose, such as 'unlike prose that gets reinterpreted differently by every reader,' is verbose but reinforces a constraint worth emphasizing.
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 state-transition tool with nested parameters and no annotations or output schema, the description covers the essential ground: required shapes, persistence, handoff integration, and the commit warning. The main gaps are the undocumented memberName parameter and no statement of what a successful update returns. An agent still has enough to call it correctly in the common and risky cases.
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 only 40%, so the description must compensate, and it does for the consequential parameters: it defines the fixed shape of completion (whatWasBuilt, decisions, filesChanged, knownLimitations, nextSteps) and the meaning of 'done' and 'abandoned' states. It does not touch memberName, which remains unexplained in both schema and description, though taskId is self-evident and the gap is limited.
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 a specific verb and resource ('Update a task's status') and goes on to define the two status transitions that carry real consequences ('done' with completion, 'abandoned' with abandonReason). The description makes the tool's scope unambiguous against siblings like update_plan, claim_task, and log_activity by the resource it mutates, even without naming them.
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?
Gives explicit conditional guidance: 'When marking a task done, ALWAYS include completion' and 'If you're changing direction WITHOUT finishing... set status abandoned with abandonReason instead of just going quiet.' It also warns against silently leaving a task in_progress indefinitely. It does not name alternative tools or state when to prefer a sibling such as log_activity, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.2check_file_before_editclaim_taskdeclare_taskget_contextget_file_historyget_handoff_briefget_planget_task_historylog_activityrecord_file_noteupdate_planupdate_task_statusEach tool maps to a distinct resource/action in the task/plan/file-note lifecycle, but get_context, get_plan, and get_handoff_brief have overlapping retrieval purposes. The descriptions mitigate this with explicit guidance (prefer get_handoff_brief for handoffs), so misselection is unlikely but not impossible.
All tools use clear snake_case verb_noun names like get_context, declare_task, update_plan, and check_file_before_edit. Retrieval consistently uses get_, while mutations use declare/claim/update/log/record, forming a predictable pattern.
12 tools is well-scoped for a team-coordination server: task lifecycle, plan management, file annotations, activity logging, and context aggregation are each represented. There is no obvious bloat or thinness.
Core workflows are covered end-to-end: task declaration/claiming/status updates, plan read/write, file rationale notes, freshness checks, and handoff context. Minor gaps exist—such as no way to delete or retract a file note—but agents can work around these without dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Shared, versioned context that humans and AI agents can publish, review, annotate, and continue.
Shared, permission-aware company context for AI agents, with provenance, approvals and audit.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/imortis/teamhub-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
