This MCP server lets an AI assistant read and manage a synthetic operations platform through plain-language tools, with writes gated behind human approval.
Read business records: list employees, projects, and tasks; get project budget/hours tracking; pull per-employee utilization reports.
Create and update tasks: create tasks on projects with assignee and due date; move tasks between todo, in_progress, and done.
Log time entries: record hours worked by employee, project, and date, with an optional note.
Resolve human-friendly names or name fragments to ids; ambiguous or unknown names return candidate lists or errors so the model can self-correct.
Submit all writes as change requests that a human must approve or reject through a separate review CLI; approvals re-check for stale records and every action lands in an audit log.
Optionally use ClickUp as the task backend, with reads available and writes failing closed unless explicitly enabled.
Provides task management integration with the ClickUp API, allowing listing, creating, and updating tasks through a ClickUp backend, with writes disabled by default unless explicitly enabled.
Click on "Deploy 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., "@ops-platform Log 3 hours for Marcus on Orion today"
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.
An MCP server that lets an AI assistant read and write business records in plain language — look up people, create and move tasks, log time, pull utilization — through a synthetic operations platform (FastAPI + SQLite) and an optional, safe-by-default adapter for the real ClickUp API.
Writes need a person: the assistant's write tools file change requests, and nothing changes until a human approves one with a review CLI the assistant has no tool for. Every write, request, and decision lands in a durable audit log, and 27 scenario evals check the tool surface — replayed in CI and run against a live model (results).
Output of scripts/demo_loop.py on a fresh seed (2026-09-23).
Each prompt, taken from the DEMO.md script, is paired with the tool call a
model makes for it and sent through the real MCP server over stdio; the arrow lines are
the server's actual responses. The $ lines are the human reviewer using the review CLI
(excerpt: some steps, audit rows, and audit detail lines omitted; long lines wrapped;
timestamps are UTC).
connected: 9 MCP tools, approval mode on
> "Create a task on the Atlas project to refresh the KPI deck, assign it to Tessa, due next Friday"
create_task(project='Atlas', title='Refresh the KPI deck', assignee='Tessa', due_date='2026-09-25')
-> change request #1 pending: Create task 'Refresh the KPI deck' on Atlas KPI Dashboard,
assigned to Tessa Morgan, due 2026-09-25
[reviewer, outside the assistant: see what is waiting, then approve it]
$ python scripts/review_changes.py approve 1
approved #1: Create task 'Refresh the KPI deck' on Atlas KPI Dashboard, assigned to
Tessa Morgan, due 2026-09-25 -> task 21 (status todo)
> "Did the KPI deck task go through?"
get_change_request(change_request_id=1)
-> change request #1 approved by ops-lead: task 21 'Refresh the KPI deck' status=todo
> "Mark it in progress"
update_task_status(task_id='21', status='in_progress')
-> change request #2 pending: Update task 21 'Refresh the KPI deck': status todo -> in_progress
> "Actually, mark it done"
update_task_status(task_id='21', status='done')
-> change request #3 pending: Update task 21 'Refresh the KPI deck': status todo -> done
[reviewer, outside the assistant: approve both; the second was submitted against the old status]
$ python scripts/review_changes.py approve 2
approved #2: Update task 21 'Refresh the KPI deck': status todo -> in_progress
-> task 21 (status in_progress)
$ python scripts/review_changes.py approve 3
error: HTTP 409: Task 21 changed after this request was submitted (status 'todo' ->
'in_progress'). Nothing was applied; submit a new request if the change is still wanted.
> "Mark task 999 as done"
update_task_status(task_id='999', status='done')
-> ERROR Error executing tool update_task_status: Platform API error 404: Task 999 not found
[reviewer, outside the assistant: read the audit trail]
$ python scripts/review_changes.py audit --limit 30
#1 2026-09-24T04:35:09+00:00 mcp-agent pending create_task request #1
#2 2026-09-24T04:35:09+00:00 ops-lead approved create_task task 21 request #1
#3 2026-09-24T04:35:09+00:00 mcp-agent pending update_task_status task 21 request #2
#4 2026-09-24T04:35:09+00:00 mcp-agent pending update_task_status task 21 request #3
#5 2026-09-24T04:35:09+00:00 ops-lead approved update_task task 21 request #2
#6 2026-09-24T04:35:10+00:00 ops-lead stale update_task task 21 request #3
...
#11 2026-09-24T04:35:10+00:00 mcp-agent error update_task_status
Platform API error 404: Task 999 not foundName fragments ("Tessa", "Atlas") resolve to records; unknown ids and ambiguous names come back as errors the model can act on instead of silent guesses. The full run — including a rejected time entry, the 30-hour validation error, and the ambiguous project name — is reproducible with the commands in Quickstart.
Related MCP server: Asana MCP Server
FastAPI "platform" (SQLite + seed) ◄─HTTP─► MCP server (stdio) ◄─► Claude Code / any MCP client
│ change requests + audit log │
▲ └─ optional: ClickUp API adapter for task tools
└─HTTP── review CLI (a person approves or rejects)Platform API — a small operations system of record: employees, projects, tasks, time entries, plus budget and utilization reports. All data is synthetic.
MCP server — nine tools whose descriptions are written for a model. The server talks to the platform only over HTTP, the way a connector wraps a vendor API.
Human approval — write tools submit change requests. A person approves or rejects
them with scripts/review_changes.py, which calls platform routes that no MCP tool
can reach. Approval re-checks the record and refuses requests that went stale.
Audit log — every applied write, change request, review decision, and failed write-tool call is a row in the platform database: who, which tool, arguments, before/after, outcome, and a UTC timestamp.
Scenario evals — 27 natural-language requests with expected tool calls and outcomes, replayed through the real server in CI and scored against a live model.
Adapter pattern — the three task tools can be served by the real ClickUp API without changing the tool surface. ClickUp writes are off unless explicitly enabled.
Requires uv (it will fetch Python 3.12 automatically).
uv sync # install dependencies
uv run python -m platform_api.seed # create + seed ops_platform.db (re-run anytime to reset)
uv run uvicorn platform_api.main:app # serve the platform API on http://127.0.0.1:8000
uv run python scripts/demo_loop.py # in a second terminal: replay the demo loop over MCPInteractive API docs: http://127.0.0.1:8000/docs
The seed is deterministic (no randomness) with relative dates: time entries are fixed offsets from the current week's Monday and task due dates are offsets from today, so "this week's utilization" always has data no matter when you run the demo. All people, clients, projects, and time entries are fictional. Re-seeding also clears change requests and the audit log.
Local demo boundary: the mock API intentionally has no authentication. Keep it on
127.0.0.1; do not expose it to a network or load production data into it. See SECURITY.md for the full threat-model boundary.
The platform API must be running first (see Quickstart). Then either register the server with the CLI:
claude mcp add ops-platform -- uv run --directory /absolute/path/to/ops-platform-mcp-demo python -m mcp_server.server…or drop a .mcp.json next to wherever you run claude (if that's this repo root,
the relative directory works):
{
"mcpServers": {
"ops-platform": {
"command": "uv",
"args": ["run", "--directory", ".", "python", "-m", "mcp_server.server"]
}
}
}Then ask Claude Code things like:
list the employees · create a task on Atlas to "refresh the KPI deck" for Tessa · has change request 1 been approved? · log 3 hours for Marcus on Orion today · pull this week's utilization report
Approve or reject what it submits from another terminal:
uv run python scripts/review_changes.py list
uv run python scripts/review_changes.py approve 1 --reviewer ops-lead
uv run python scripts/review_changes.py reject 2 --reason "Quartz is on hold"
uv run python scripts/review_changes.py auditA scripted version of this loop — including the error-path curveballs and a troubleshooting section — is in DEMO.md.
Tool | Kind | Notes |
| read | full roster with capacity |
| read | id, client, status, budget |
| read | names or ids accepted; results include names |
| read | logged vs budget |
| read | ISO week e.g. |
| read | pending / approved (with the record written) / rejected (with reason) / stale / failed |
| write | submits a change request; returns it as |
| write | todo / in_progress / done; submits a change request |
| write | submits a change request |
Tools accept human-friendly names where reasonable and resolve them to ids internally; ambiguous or unknown names return errors that list the candidates so the model can self-correct. Write requests are validated when submitted, so a bad id, an invalid value, or an update that would change nothing fails immediately instead of waiting in the queue.
The design goal is that the assistant cannot approve its own changes:
Separate path for decisions. Change requests are submitted and read at
/change-requests; approve and reject live under /admin/change-requests/…. The MCP
server has no tool and no code path for the /admin routes (a test checks both), so
an assistant limited to the MCP tools can ask for a change but never make it happen.
Four-eyes check. The platform refuses a decision whose reviewer name matches the
submitter (mcp-agent).
One decision per request. A decision claims its request with a conditional update
(pending only), so two reviewers acting at the same moment cannot both apply it.
Stale requests. An update snapshots the task when submitted. If the task changed
before approval — another approved request, a direct edit — approval is refused with
the fields that changed, and the request is marked stale.
One transaction. A platform write and its audit row commit together, so a change
cannot land without its audit record. Failed write-tool calls, which never reach a
write, are reported by the MCP server as error rows with the arguments the model
sent.
Turning it off. OPS_REQUIRE_APPROVAL=false restores direct writes (the original
behavior); those writes are still audited as applied.
Browse the log with review_changes.py audit or GET /audit-events. There is no route
to edit or delete events. The boundary is the tool surface, not authentication — see
Known limitations.
evals/scenarios.yaml holds 27 requests a user might type —
lookups, creates, updates, time logging, budget and utilization questions, change-request
status, ambiguous names, missing records, invalid input, and requests the assistant must
not carry out — each with the reference tool calls and the outcome they must produce.
Deterministic layer (CI, no model). tests/test_eval_scenarios.py sends each
scenario's reference calls through the MCP protocol into the real platform on a fresh
seed and checks the outcome: success, pending approval, a candidate list, or the
expected 404/422/ambiguity error. It also re-scores the recorded live run with the
current checks, so the published results cannot drift from the scorer.
Live-model layer (local, not CI). uv run python -m evals.run_model_eval gives each
prompt to Claude Code in headless mode with only these MCP tools allowed, then scores
tool selection, key arguments, whether any write went through when it should not
have, and whether the reply says the change is pending approval or, for a request it
must not carry out, names the problem or declines. The 2026-09-23 run passed 27/27 on
the original checks; re-scored from its recorded replies against stricter reply checks
(--rescore, no new model run), it passes 25/27. evals/RESULTS.md
has the per-scenario table and what that score does not show.
The three task tools (list_tasks, create_task, update_task_status) are
backend-pluggable — same tool surface, different system of record:
OPS_TASK_BACKEND=platform # default: the mock platform above
OPS_TASK_BACKEND=clickup # real ClickUp API (set CLICKUP_API_TOKEN)In ClickUp mode a "project" is a ClickUp list (found by name across all spaces
and folders), an assignee is a workspace member, statuses map todo / in_progress /
done ↔ "to do" / "in progress" / "complete", and task ids are ClickUp's alphanumeric
strings. Get a personal token from ClickUp → Settings → Apps and see .env.example.
The other six tools (employees, hours, time, utilization, change requests) always use
the platform.
Copy the environment template, then ask uv to load it explicitly:
cp .env.example .env
# Edit .env, then run the MCP server directly for a smoke test:
uv run --env-file .env python -m mcp_server.serveruv does not load .env implicitly. When ClickUp mode is launched through an MCP
client, add --env-file /absolute/path/to/.env to the uv run arguments or inject the
same variables through the client's environment configuration.
ClickUp reads are available once a token is configured. The approval queue can only
apply platform changes, so create_task and update_task_status fail closed in ClickUp
mode until both OPS_REQUIRE_APPROVAL=false and CLICKUP_WRITES_ENABLED=true are set;
successful ClickUp writes are then reported to the platform audit log as external
(best effort; not transactional: the report is a separate call made after ClickUp
accepts the write, so if that call fails, for example because the platform is down, the
write stands and the MCP server only logs a warning).
If a token can access multiple workspaces, CLICKUP_TEAM_ID is also required; the
adapter will never choose the first workspace silently. Keep writes disabled for read-
only demos. Task reads explicitly include closed work and paginate through the result
set. Before updating a task by id, the adapter fetches it and verifies its documented
team_id against the selected workspace.
If ClickUp accepts a write but returns an unexpected task payload, the adapter reports that the operation may already have succeeded and requires verification in ClickUp before any retry. Automatic retries and idempotency are intentionally out of scope.
The MCP tool layer does not change when the backend becomes a real vendor API — only the adapter behind it does.
uv run pytest # 243 tests: API, approvals, audit, MCP handlers, review CLI, ClickUp, scenario evals
uv run ruff check . # lint
uv run ruff format --check .Tool-handler tests run against the real FastAPI app in-process (httpx ASGI transport + seeded in-memory SQLite) — no server or network needed. ClickUp tests use an in-memory fake of the ClickUp v2 API. CI runs lint, the format check, the test suite, and the deterministic scenario evals as a separate step on every pull request and every push to main.
This project was built by directing AI coding agents; the split below is deliberate.
What I decided
The scope and architecture: a synthetic platform first, the MCP server talking to it only over HTTP, and a real vendor adapter only after the tool surface was stable.
The tool-design rules the agents had to follow: descriptions written for a model, names resolved to ids, ambiguity returned as an error listing candidates, write tools returning the changed record (with approval on, the pending change request).
The safety posture for the vendor adapter: ClickUp writes off by default and no silent choice of workspace.
Change discipline: every code change landed as a branch and pull request with CI.
What AI tools generated
Claude Code (cloud sessions, June 2026) wrote the platform API, seed data, MCP server, ClickUp adapter, tests, CI workflow, and DEMO.md from phase-by-phase briefs.
OpenAI Codex (September 2026) wrote the ClickUp safety hardening, SECURITY.md, and the input-validation fixes for task updates and blank selectors.
Claude Code (September 2026) assembled this public snapshot and wrote
scripts/demo_loop.py, then built the approval workflow, audit log, review CLI, and
scenario evals, ran and later re-scored the live-model eval, and updated the demo and
docs.
What was verified
The full test suite (243 tests) and ruff lint/format checks pass locally; CI reruns them on every pull request and every push to main.
The demo transcript above is real output (excerpted) from running scripts/demo_loop.py
against a freshly seeded platform.
The live-model eval results are from an actual run, re-scored later from its recorded
replies without a new model run; the per-scenario calls, tool results, replies, and
Claude Code version are recorded in evals/RESULTS.md and evals/last_run.json; the
model identifier is deliberately not recorded.
The published tree was checked for secrets, real personal data, and employer-specific content before release. It was first published as a fresh single-commit history; the earlier development history lives in a private repository.
The platform API has no authentication and is meant for 127.0.0.1 only. The
approval boundary is the MCP tool surface: anything else that can reach the API —
including an assistant that also has shell access and runs the review CLI — can
approve requests. Keep shell tools behind permission prompts when an assistant is
connected.
Actor and reviewer names are self-reported headers and fields, and the audit log is a local SQLite table, not tamper-evident storage.
Change requests do not expire; a stale check runs only when someone approves. The approval queue cannot hold ClickUp writes.
The demo replay script sends fixed tool calls; it shows the MCP and API behavior, not a model's tool choice. The live-model eval covers tool choice, but it is a single run of 27 scenarios on one model, and its reply checks are keyword matches.
The ClickUp adapter has not been exercised against a live ClickUp workspace; it was built from ClickUp's v2 API documentation and is verified only against an in-memory fake.
ClickUp writes have no automatic retry or idempotency key; an ambiguous write result must be checked in ClickUp before retrying.
Not production-ready: a real deployment would need platform authentication and authorization (including authenticated reviewers), scoped OAuth, managed secrets, tamper-evident audit storage, rate-limit handling, and monitoring.
Create a new task on a project. Use this when asked to add a work item, to-do, or
action item. project (required) and assignee (optional) accept a name, a unique
name fragment, or an id; due_date is optional in YYYY-MM-DD format. New tasks
always start in the 'todo' state — use update_task_status afterwards if a different
status is needed. Returns the created task including its id; mention the id so the
user can refer to the task later. The task is created in the system selected by
OPS_TASK_BACKEND (the mock platform by default, or ClickUp).
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| project | Yes | ||
| assignee | No | ||
| due_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses default 'todo' state, return value with id, and backend dependency (OPS_TASK_BACKEND). Could add more on permissions or side effects.
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?
Front-loaded with key information. Some extra details (like OPS_TASK_BACKEND) are relevant but could be more concise. Still, every sentence adds value.
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?
No output schema, but description covers return value (created task with id) and backend context. Missing details on error handling or pagination, but adequate for a creation tool.
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%, but description adds significant meaning: explains project/assignee accept name/fragment/id, due_date format, and which parameters are required/optional.
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 explicitly states 'Create a new task on a project' and lists concrete use cases ('work item, to-do, action item'). It distinguishes itself from sibling tools like update_task_status.
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?
Clearly says when to use the tool and mentions update_task_status for changing status afterward. Lacks explicit 'do not use when' but provides sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report how a single project is tracking against its budget: returns the project's
metadata plus budget_hours, logged_hours (sum of all time entries), and
remaining_hours. Use this for questions like 'how is Orion tracking against budget'
or before logging significant additional time. project accepts a name, a unique
name fragment, or a numeric id.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the return values but does not disclose side effects, auth requirements, or error handling. It implies read-only behavior via 'report' but not explicitly.
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, front-loaded with purpose and output details. Every word adds value; no redundancy.
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 parameter, no output schema, and no annotations, the description covers the main use case and parameter flexibility. It lacks potential error or edge-case info, but is largely complete for a simple report tool.
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 single parameter 'project' is described as accepting a name, unique name fragment, or numeric id—info entirely missing from the input schema. With 0% schema coverage, this description is essential and adds full meaning beyond the schema.
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 it reports on how a single project tracks against its budget, listing returned fields (metadata, budget_hours, logged_hours, remaining_hours) and gives an example query. This distinguishes it from siblings like list_projects or utilization_report.
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 specifies use cases: 'how is Orion tracking against budget' or before logging significant time. It implicitly suggests when to use but does not explicitly mention alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every employee in the platform with their id, name, role, department, and weekly_capacity_hours. Use this to discover who exists, look up an employee's id or exact name, or check someone's capacity before assigning work or interpreting a utilization report. Takes no arguments and returns the full employee list; if you need a subset, filter the result yourself.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description accurately describes a simple read operation with no side effects. Could be more explicit about being read-only or non-destructive, but 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?
Three efficient sentences. Front-loaded with primary purpose, followed by usage guidance. No unnecessary words.
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?
Complete for a no-parameter tool with an output schema. Covers purpose, usage, and return fields. No gaps given the simplicity.
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?
No parameters, schema coverage 100%. Description confirms no arguments, adding no extra meaning but confirming the fact.
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 'List every employee in the platform' with specific fields. Distinguishes from sibling tools which focus on tasks, projects, and time logging.
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 states use cases: discovering employees, looking up IDs/names, checking capacity. Says to filter manually for subsets. No explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every project with its id, name, client, status (active, on_hold, or closed), and budget_hours. Use this to discover which projects exist or to find a project's id or exact name before creating tasks, logging time, or requesting an hours report. Takes no arguments and returns the full project list.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states 'Takes no arguments and returns the full project list', which is transparent about its input and output scope. However, it does not mention authorization, rate limits, or that it is a read-only operation, but for a simple list tool, this is adequate.
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 three sentences: first sentence lists what is returned, second sentence explains usage, third sentence confirms no arguments. Each sentence is essential and well-front-loaded. No wasted words.
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 is simple (0 parameters, output schema exists), the description covers purpose, usage, and output fields completely. It tells the agent exactly what to expect and when to use it.
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 0 parameters with 100% schema description coverage. Since there are no parameters, the baseline is 4. The description correctly notes 'Takes no arguments', adding no redundant information.
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 explicitly states 'List every project with its id, name, client, status (active, on_hold, or closed), and budget_hours', providing a specific verb+resource with detailed fields. It distinguishes from sibling tools by mentioning use cases like finding project id before creating tasks, logging time, or requesting hours report, which implies differentiation from tools like create_task, log_time, and get_project_hours.
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 clearly states when to use: 'Use this to discover which projects exist or to find a project's id or exact name before creating tasks, logging time, or requesting an hours report.' It does not explicitly mention when not to use or alternatives, but the context of sibling tools makes it clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tasks, optionally narrowed by project, assignee, and/or status. Use this to
answer what is on someone's plate, what work remains on a project, or to find a
task's id before updating its status. project and assignee accept a name, a
unique name fragment, or an id; status must be todo, in_progress, or done. All
filters combine with AND. Returns the matching tasks with project and assignee
names included for readability. Tasks live in the system selected by
OPS_TASK_BACKEND (the mock platform by default, or ClickUp).
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| project | No | ||
| assignee | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It discloses that the backend is dynamic (OPS_TASK_BACKEND) and that the return includes project and assignee names for readability. This provides useful context beyond the basic list operation, though it omits potential behavioral traits like rate limits or ordering.
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 concise (5 sentences) and front-loaded with the core purpose and filters. Every sentence adds value: use cases, parameter details, filter logic, return info, and backend note. No redundancy or fluff.
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?
With no annotations but an output schema present, the description explains the return includes project and assignee names, mentions the dynamic backend, and covers filter behavior. However, it does not address pagination, limit, or sorting, which are typical for list 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 coverage is 0%, but the description adds rich semantics: project and assignee accept 'a name, a unique name fragment, or an id', and status must be exact enums 'todo, in_progress, or done'. This fully compensates for the schema's lack of specificity, making parameters usable.
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 verb+resource: 'List tasks, optionally narrowed by project, assignee, and/or status.' It then provides concrete use cases (e.g., 'what is on someone's plate') and mentions finding a task ID for updates, distinguishing it from sibling tools like create_task or update_task_status by focusing on reading.
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 states when to use the tool: 'Use this to answer what is on someone's plate, what work remains on a project, or to find a task's id before updating its status.' It also explains how filters combine (AND) and parameter formats. However, it does not contrast with siblings like list_projects or provide exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log hours that an employee worked on a project for a specific day. Use this when
someone reports time worked or asks you to record effort. employee and project
accept a name, a unique name fragment, or a numeric id; date is YYYY-MM-DD; hours
must be greater than 0 and at most 24; note is an optional short description of the
work. Returns the created time entry including its id. Logged time immediately shows
up in get_project_hours and utilization_report.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| note | No | ||
| hours | Yes | ||
| project | Yes | ||
| employee | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description carries the full burden. It discloses the mutation effect (logging hours), the return value (created entry with id), and the immediate impact on other tools (get_project_hours and utilization_report). It does not discuss potential side effects like overwriting existing entries, but the behavior is straightforward.
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 concise: just a few sentences without unnecessary detail. It is front-loaded with purpose, then usage, then parameter details, return value, and downstream effects. 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 moderate complexity (5 simple parameters, no output schema), the description covers purpose, usage, parameter semantics, and effects. It does not discuss error handling or edge cases, but those are generally beyond expectations. The inclusion of downstream tool visibility adds completeness.
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. It adds meaning to all parameters: explains that employee and project accept names, fragments, or numeric IDs; date format YYYY-MM-DD; hours range (0 to 24); note optional. This is thorough and goes beyond the schema's type-only information.
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 action: 'Log hours that an employee worked on a project for a specific day.' It uses a specific verb (log) and resource (hours), and distinguishes itself from sibling tools like get_project_hours (read) and create_task (different domain).
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 explicit usage context: 'Use this when someone reports time worked or asks you to record effort.' It does not list explicit alternatives or when-not-to-use, but the context is clear and sufficient given the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a task to a new status: todo, in_progress, or done. Use this when asked to
start, finish, reopen, or otherwise progress a task. Requires the task_id — if you
only know the task by title or assignee, call list_tasks first to find the id (ids
are numeric on the platform backend, alphanumeric strings on ClickUp). Returns the
full updated task so you can confirm the change took effect.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the tool requires task_id and status, returns the full updated task for confirmation. Could be slightly improved by explicitly noting the mutation is destructive, but the update nature is implied. A minor gap.
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, front-loaded with action and allowed values. Every sentence adds value: what it does, when to use, prerequisites, return value. No waste.
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 tool with two required parameters and no output schema, the description covers purpose, usage, prerequisites, and response. It is complete and leaves no ambiguity.
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%, but description adds meaning beyond schema: it specifies that task_id is required and explains how to obtain it, and lists the allowed status values (todo, in_progress, done). It also clarifies ID formats for different backends. Only missing explicit mapping of parameter names to descriptions.
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 moves a task to a new status (todo, in_progress, done) and lists example use cases (start, finish, reopen). It distinguishes from sibling tools by explaining that list_tasks should be called first to obtain the task_id.
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 states when to use the tool (start/finish/reopen/progress tasks) and when to use an alternative (list_tasks if only task title or assignee is known). Also provides platform-specific notes about ID formats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-employee utilization for one week: logged hours against weekly capacity, with
a utilization_pct per person. Use this for questions like 'who is over or under
capacity' or 'pull this week's utilization'. week is an ISO week string such as
'2026-W24'; omit it for the current week. Returns the week's start/end dates and one
row per employee (including employees with zero logged hours).
| Name | Required | Description | Default |
|---|---|---|---|
| week | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: returns one row per employee including zero hours, week start/end dates, and parameter default handling. No contradictions.
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?
Four sentences, front-loaded with purpose, each sentence adds value (purpose, usage, parameter, return structure). Efficient.
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?
Describes return fields (week dates, per-employee rows with utilization_pct) without output schema. Missing explicit output structure (e.g., array), but adequate for low complexity.
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?
Only parameter 'week' has 0% schema coverage, but description explains ISO week string format and default behavior (current week if omitted), adding critical meaning beyond schema.
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?
Description clearly states 'Per-employee utilization for one week' with specific metrics (logged hours, capacity, utilization_pct), distinguishing it from siblings like get_project_hours.
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 explicit use case examples ('who is over or under capacity') and parameter guidance (ISO week format, omit for current week), but does not explicitly exclude alternatives or mention when not to use.
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.
v0.1.0create_taskget_project_hourslist_employeeslist_projectslist_taskslog_timeupdate_task_statusutilization_reportScored across 8 tools
Each tool targets a distinct resource and action: listing employees, projects, tasks, getting project hours, utilization, creating tasks, updating status, and logging time. There is no overlap between them; even list_tasks is distinct from the other list tools by focusing on tasks with filters, while utilization and hours are separate reports.
All tool names follow a clear verb_noun pattern: list_*, get_project_hours, utilization_report, create_task, update_task_status, log_time. The verbs are consistent (list, get, create, update, log) and the nouns are specific, making the naming predictable and easy to parse.
With 8 tools, the server is well-scoped for a workforce/project management domain. Each tool serves a distinct and necessary function, covering the core operations without redundancy or unnecessary bloat. This is within the ideal 3-15 tool range.
The tool set covers the main lifecycle: reading all entities, creating tasks, updating status, logging time, and generating reports. Missing operations include updating/deleting projects or employees, and editing or deleting time entries, but these are not critical for the core purpose of task and time management. Minor gap, but agents can work around it.
Manage projects, tasks, time tracking, and team collaboration through natural language.
Time tracking, tasks and team chat for humans and AI agents.
Gives your AI assistant persistent memory and intelligence about your work patterns.
Shared company knowledge, workflows, and connected apps for the AIs your team already uses.
