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.
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 (excerpt, long lines wrapped).
connected: 8 MCP tools
> "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')
-> task 21 'Refresh the KPI deck' status=todo assignee=Tessa Morgan
> "Actually, mark that in progress"
update_task_status(task_id='21', status='in_progress')
-> task 21 'Refresh the KPI deck' status=in_progress assignee=Tessa Morgan
> "Log 3 hours for Marcus on Orion today - pipeline fixes"
log_time(employee='Marcus', project='Orion', date='2026-09-23', hours=3, note='Pipeline fixes')
-> time entry 61: 3.0h on 2026-09-23
> "How is Orion tracking against its budget?"
get_project_hours(project='Orion')
-> Orion Data Migration: 139.0 of 480.0 budget hours
> "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
> "Log an hour on project 'a' for Marcus"
log_time(employee='Marcus', project='a', date='2026-09-23', hours=1)
-> ERROR Error executing tool log_time: Ambiguous project 'a' — matches: Orion Data Migration (id 1);
Atlas KPI Dashboard (id 2); Quartz CRM Cleanup (id 3); Phoenix Onboarding Portal (id 4);
Legacy Archive Extract (id 5). Retry with the exact name or the id.Name fragments ("Tessa", "Orion") 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 the 30-hour validation error and the utilization report, 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
│
└─ optional: ClickUp API adapter for task toolsPlatform API — a small operations system of record: employees, projects, tasks, time entries, plus budget and utilization reports. All data is synthetic.
MCP server — eight 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.
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.
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 · mark task 21 in progress · log 3 hours for Marcus on Orion today · pull this week's utilization report
A 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. |
| write | returns created task |
| write | todo / in_progress / done |
| write | returns created entry |
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.
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 five tools (employees, hours, time, utilization) 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, but create_task and
update_task_status fail closed until CLICKUP_WRITES_ENABLED=true is explicitly set.
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 # 83 tests: API, MCP handlers, name resolution, ClickUp safety/error paths
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 the same three commands 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.
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.
What was verified
The full test suite (83 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 published tree was checked for secrets, real personal data, and employer-specific content before release. It is a fresh single-commit history; the development history lives in a private repository.
The platform API has no authentication and is meant for 127.0.0.1 only.
The demo replay script sends fixed tool calls; it shows the MCP and API behavior, not a model's tool choice. A live model run follows DEMO.md.
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, scoped OAuth, managed secrets, write approvals, durable audit logging, 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.
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.
Search recordings, summarize meetings, create clips, and automate workflows from your AI assistant.
