productive-mcp is an MCP server for Productive.io that lets you manage time tracking, projects, people, and reporting through natural language commands.
Time Tracking:
Log time entries on a project with optional notes, date, and service hints
List time entries filtered by date range, project, or owner (defaults to your own entries)
Update existing time entries (hours, date, note, or service)
Permanently delete time entries
Project & Service Management:
List all active projects; fuzzy-search by partial name or number
List services (billable activity types) for a given project
Set or override the default service remembered for a project to streamline logging
People Search:
Fuzzy-search team members by name or email
Reporting & Briefings:
Generate time reports with categorized summaries (worked, client, internal, holidays)
Retrieve hours summaries for any team member
Get a personal weekly briefing with total hours and per-project breakdown
View projects on which you've recently logged time
Smart Features:
Fuzzy matching for projects and people supports natural input
Billing-cutoff-aware period resolution (e.g. adjusts "this month" based on your invoicing cycle)
Local cache for projects, people, and services with manual refresh option
Token-Optimized Output (TOON) mode for reduced token usage
Abstracts Productive.io's internal minute-based tracking — interact in hours only
Secure credential storage via OS keychain, Credential Manager, Secret Service, or environment variables
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., "@productive-mcp log 3 hours on the Q4 marketing campaign project"
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 for Productive.io — log time, inspect projects, manage entries, and get team reports from any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.) using plain English:
"log 2.5 hours on the Acme security review project"
"how many hours did Alice log this week?"
"give me my weekly briefing"
Built around the Productive.io JSON:API v2 with fuzzy project and person matching, a local disk cache, billing-cutoff-aware period resolution, and per-project default-service memory.
14 tools covering projects, people, services, time entries, reports, and briefings
Cross-platform credential storage — macOS Keychain, Windows Credential Manager (DPAPI/TPM-backed), Linux Secret Service, or environment variables
Fuzzy matching for projects and people — "Acme", "1099 Acme", "Alice", or "me" all resolve naturally
Billing-cutoff-aware period resolution — "this_month" shifts based on your invoicing cycle
Remembers your default service per project so you don't have to specify it every time
Local cache for projects, people, and services (1-hour TTL, manually refreshable)
TOON output mode — optional token-optimised encoding for 30–60% fewer tokens
hours in, hours out — the API uses minutes internally, but you never see them
Scoped to "me" by default — list_time_entries only shows your own entries unless you opt out
Related MCP server: Work-Timer
Python 3.11+
A Productive.io account with API access enabled
macOS, Windows, or Linux
git clone https://github.com/cameronfairbairn/productive-mcp.git
cd productive-mcp
uv venv
uv pip install -e .(or python -m venv .venv && .venv/bin/pip install -e . if you don't use uv)
You need three values:
Value | Where to find it |
API token | Productive → Settings → API integrations → Generate new token |
Organization ID | The numeric segment in your Productive URL: |
Person ID | Your own user ID — open your profile in Productive; it's the numeric segment in the URL |
Works on any platform via the keyring library:
python -c "import keyring; keyring.set_password('productive-mcp', 'token', '<token>')"
python -c "import keyring; keyring.set_password('productive-mcp', 'org_id', '<org_id>')"
python -c "import keyring; keyring.set_password('productive-mcp', 'person_id', '<person_id>')"Platform | Backend | Security |
macOS | Keychain | Secure Enclave where available |
Windows | Credential Manager (DPAPI) | TPM-backed on TPM 2.0 systems |
Linux (desktop) | Secret Service (GNOME Keyring / KWallet) | Session-encrypted |
On macOS, the security CLI also works (keyring reads from the same Keychain):
security add-generic-password -s productive-mcp -a token -w "<token>" -U
security add-generic-password -s productive-mcp -a org_id -w "<org_id>" -U
security add-generic-password -s productive-mcp -a person_id -w "<person_id>" -Uexport PRODUCTIVE_MCP_TOKEN="<token>"
export PRODUCTIVE_MCP_ORG_ID="<org_id>"
export PRODUCTIVE_MCP_PERSON_ID="<person_id>"Environment variables take precedence over the credential store.
~/.claude.json){
"mcpServers": {
"productive": {
"type": "stdio",
"command": "/path/to/productive-mcp/.venv/bin/productive-mcp",
"args": []
}
}
}claude_desktop_config.json){
"mcpServers": {
"productive": {
"command": "/path/to/productive-mcp/.venv/bin/productive-mcp"
}
}
}Restart the client after editing its config.
bash scripts/install.shThis creates ~/.local/share/productive-mcp/ containing a fresh venv and a run.sh launcher. Point your MCP client at ~/.local/share/productive-mcp/run.sh instead. Re-running the script upgrades in place.
All tools are prefixed with productive_ so they namespace cleanly alongside other MCP servers.
Tool | Purpose |
| Create a time entry |
| List time entries with date/project/owner filters |
| Edit hours / date / note / service on an existing entry |
| Permanently delete a time entry |
Tool | Purpose |
| Categorised hours summary (worked/client/internal/holidays) |
| Hours summary for any team member by name |
| Projects you've logged time on recently |
| Weekly summary with hours-by-project breakdown |
Tool | Purpose |
| List all active projects |
| Fuzzy-search projects by name and/or number |
| Fuzzy-search people by name or email |
| List services (billable activity types) on a project |
Tool | Purpose |
| Force an immediate cache refresh |
| Override the remembered default service for a project |
productive_get_time_reportperiod : str? — "this_month", "last_month", "this_week", "last_week"
after : str? — ISO date; ignored if period set
before : str? — ISO date; ignored if period set
person : str? — Name, email, id, or "me" (default)
project : str? — Scope to a specific projectReturns totals_hours: {worked, client, internal, holidays}. When PRODUCTIVE_BILLING_CUTOFF_DAY is set, "this_month" shifts based on your billing cycle.
productive_my_briefingperiod : str — Default "this_week"Returns total hours, projects touched, hours-by-project breakdown, and recent entries. Designed for the Monday-morning "what am I working on?" question.
productive_get_employee_hoursperson : str — Fuzzy name, email, or "me"
period : str? — Symbolic period (default: no filter)
after : str? — ISO date
before : str? — ISO dateFinds a person by fuzzy match, returns their hours for the period.
Variable | Default | Purpose |
| — | API token (overrides credential store) |
| — | Organization ID (overrides credential store) |
| — | Person ID (overrides credential store) |
| unset | Day of month (1–31) when "this_month" flips to the current calendar month |
|
| Set to |
The PRODUCTIVE_BILLING_CUTOFF_DAY controls how symbolic periods resolve for invoicing workflows:
Before cutoff day: "this_month" = previous calendar month (you're still closing invoices)
From cutoff day onward: "this_month" = current calendar month
Unset: "this_month" always means the current calendar month
Example: with PRODUCTIVE_BILLING_CUTOFF_DAY=10, on April 5th, "this_month" resolves to March 1–31.
API tokens are never written to disk by this project. They live in the OS credential store (Keychain / Credential Manager / Secret Service) or in environment variables.
Each team member generates their own API token via Productive → Settings → API integrations (docs). Tokens inherit the generating user's permissions:
"API tokens inherit the same access restrictions as the user they are associated with. If a user does not have permission to access certain features or data within Productive, these limitations will also apply to their API token."
Tokens also have a read-only vs read/write scope chosen at creation time.
What this means for team deployments:
A "Member"-role user's token cannot query other members' time entries — Productive returns 403.
The real access boundary is the Productive role (Settings → People → Role), not MCP-side configuration.
Tools like productive_get_employee_hours will simply return empty/error for users whose Productive role doesn't grant team visibility.
For more on roles: User Permissions Overview | Productive API docs
┌─────────────────────┐ stdio ┌──────────────────────┐ HTTPS ┌─────────────────┐
│ MCP client │ ─────────► │ productive-mcp │ ────────► │ Productive.io │
│ (Claude Code etc.) │ │ (FastMCP server) │ │ JSON:API v2 │
└─────────────────────┘ └──────────┬───────────┘ └─────────────────┘
│
▼
~/.config/productive-mcp/
├── cache.json (projects, people, services)
└── preferences.json (per-project default service)Environment variable (PRODUCTIVE_MCP_TOKEN / _ORG_ID / _PERSON_ID)
OS credential store via keyring (Keychain / Credential Manager / Secret Service)
Error with a helpful message pointing at both options
Two files under ~/.config/productive-mcp/, both 0600:
cache.json — projects, people (active only), per-project services. 1-hour TTL.
preferences.json — { "default_services": { "<project_id>": "<service_id>" } }.
Neither file ever contains credentials.
uv pip install -e ".[dev]"
# unit tests (no network required)
pytest
# integration tests (hit the real Productive API — requires credentials)
pytest -m integration
# lint + type check
ruff check .
mypy srcsrc/productive_mcp/
├── __main__.py Entrypoint (python -m productive_mcp)
├── server.py FastMCP tool definitions (14 tools)
├── client.py Async Productive.io API client + fuzzy matcher
├── auth.py Cross-platform credential loader (keyring + env)
├── storage.py Local cache + preferences persistence
├── periods.py Billing-cutoff-aware period resolution
└── reporting.py Time entry categorisation for reports
scripts/
└── install.sh One-shot deploy script for the global launcher
tests/
├── test_client.py Fuzzy matching + trim functions
├── test_periods.py Period resolution + billing cutoff
├── test_reporting.py Entry categorisation
└── test_formatter.py TOON output encoding"Credential store lookup failed"
The keyring backend isn't configured or accessible. Check: python -c "import keyring; print(keyring.get_keyring())". On headless Linux, use environment variables instead.
"No credential found for service=productive-mcp"
Credentials haven't been stored yet. Run the keyring.set_password(...) commands from the install section.
"No project matches 'X'"
Cache may be stale. Call productive_refresh_cache and retry.
"Ambiguous project query" Two projects scored nearly identically. Be more specific — add the project number.
"Project has multiple services; pass service_hint"
Either pass service_hint="…" (it'll be remembered), or call productive_set_default_service once upfront.
Several other Productive.io MCP servers exist:
berwickgeek/productive-mcp — the most feature-complete general-purpose server (projects, tasks, boards, people, workflows). Node.js. No time tracking.
adamchrabaszcz/productive-time-mcp — companion time-tracking server for the above.
druellan/Productive-Simple-MCP — read-only Python/FastMCP server using TOON output for low token usage.
laurkee/productive-mcp (Codeberg) — ticketing-focused.
Why pick this one?
Cross-platform credential store — not a .env file. macOS Keychain, Windows Credential Manager (TPM-backed), Linux Secret Service.
Fuzzy matching for projects and people — say "Alice" or "1099 Acme" instead of looking up IDs.
Per-project default service memory — log time without specifying the service after the first call.
Billing-cutoff-aware reports — "this_month" means what your invoicing cycle says it means.
TOON output mode — 30–60% fewer tokens for long sessions.
MIT — see LICENSE.
Issues and PRs welcome. Please include tests for new behaviour.
Not affiliated with Productive.io. "Productive" is a trademark of its respective owners.
Permanently delete a time entry.
Args: entry_id: Time entry ID.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavior. It states 'permanently delete' implying irreversibility, but no details on permissions, side effects, or error conditions. The description is minimal.
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 extremely short (one line plus argument list), wasting no words. However, it could be more informative within a similar length.
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 destructive operation with one parameter and an output schema, the description is minimally adequate. It states the action and parameter but lacks context about the operation's impact or error handling.
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 description only restates the parameter name 'entry_id' and its type 'Time entry ID', adding no additional meaning beyond the schema. With 0% schema description coverage, the description fails to compensate.
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 action 'Permanently delete' and the resource 'a time entry'. It is specific and distinguishes from sibling tools which focus on finding, listing, logging, or updating time entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like update_time_entry or log_time. The description does not mention prerequisites, consequences, or context for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fuzzy-search people in the organisation by name or email.
Args: query: Partial name or email (e.g. "Alice", "alice@example.com"). limit: Max matches to return (default 5).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses fuzzy search behavior and parameter info but lacks details on actionable constraints like data freshness, access rights, or result handling. More context would improve transparency.
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 extremely concise: two sentences plus a bullet-style Args section. Every sentence serves a distinct purpose and no information is redundant. Properly 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 the presence of an output schema and only 2 simple parameters, the description covers inputs adequately but could mention what happens when no matches are found or any other edge cases. It's minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds significant value by explaining the 'query' parameter (partial name/email with examples) and the 'limit' parameter (max matches, default 5). This exceeds the baseline expectation.
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 performs a fuzzy search for people by name or email, using specific verbs and resources. It distinguishes from sibling tools like productive_find_project by specifying the resource (people) and search type (fuzzy).
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 when to use the tool (searching people by partial name or email) but does not explicitly state when not to use it or mention alternatives among siblings. No exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fuzzy-search projects by name or number.
Args: query: Partial name or number (e.g. "Acme", "1099"). limit: Max matches to return (default 5).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It indicates fuzzy matching but lacks details on ranking, case sensitivity, scope of projects searched, or what happens on no results. Moderately transparent.
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?
Very concise: two sentences plus args block. Front-loaded with purpose. No extraneous 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 search tool with output schema, the description covers basic usage. Could benefit from behavioral details (matching logic, empty results) but is generally adequate.
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 has 0% description coverage for parameters. Description adds meaning: query is partial name/number, limit with default 5. Adds value 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?
The description clearly states the tool performs fuzzy-search on projects by name or number, with examples. It distinguishes from sibling tools like productive_list_projects and productive_find_person.
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 usage context: use for partial name or number. Gives example queries. Does not explicitly state when not to use or mention alternatives, but the purpose is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a named employee's hours summary for a period.
Args: person: Person name, email, or "me" (fuzzy matched). period: Symbolic period — "this_month", "last_month", "this_week", "last_week". after: ISO date (YYYY-MM-DD). Ignored if period is set. before: ISO date (YYYY-MM-DD). Ignored if period is set.
| Name | Required | Description | Default |
|---|---|---|---|
| person | Yes | ||
| period | No | ||
| after | No | ||
| before | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It explains parameters and their interactions (e.g., 'after' and 'before' ignored if period is set). However, it does not disclose whether the tool requires specific permissions, how data is aggregated (e.g., approved hours only), or if there are rate limits. The returned data format is not described.
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 clear and front-loaded with the purpose. The argument list is structured but slightly verbose with individual docstrings for each param. Could be trimmed to a single sentence about each param inline, but still 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?
Given 4 parameters and no annotations, the description covers parameter semantics well. However, it lacks context about output (though an output schema exists). It does not explain how this tool fits with siblings (e.g., 'productive_get_time_report' vs this). For a summary tool, it should clarify scope (e.g., billable vs non-billable hours).
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 does: explains that 'person' supports fuzzy matching (name, email, 'me'), 'period' uses symbolic values, and 'after'/'before' are ISO dates with dependency on 'period'. This adds significant meaning beyond the raw 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 retrieves a named employee's hours summary for a period. The verb 'Get' and resource 'employee hours summary' are specific. However, it does not differentiate from sibling tools like 'productive_get_time_report', which might also return hours but aggregated differently.
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 usage for period-based summaries of a specific employee. No explicit guidance on when to use this tool versus alternatives like 'productive_get_time_report' or 'productive_list_time_entries'. The 'period' parameter suggests snapshots, but no exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a categorised hours summary (worked, client, internal, holidays).
Args: period: Symbolic period — "this_month", "last_month", "this_week", "last_week". Affected by PRODUCTIVE_BILLING_CUTOFF_DAY. after: ISO date (YYYY-MM-DD). Ignored if period is set. before: ISO date (YYYY-MM-DD). Ignored if period is set. person: Person name, email, id, or "me" (default: "me"). project: Optional project name or id to scope the report.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | ||
| after | No | ||
| before | No | ||
| person | No | ||
| project | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that period is affected by PRODUCTIVE_BILLING_CUTOFF_DAY and that after/before are ignored if period is set. These are behavioral details beyond the schema. No annotations exist, so the description carries full burden. It does not discuss error handling or empty results, but the output schema covers return format.
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: a clear one-sentence purpose followed by a structured bullet list of parameters. No redundancy or unnecessary words. 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?
Given the presence of an output schema (return format is covered elsewhere), the description sufficiently explains inputs and key behavioral constraints. It could mention that the report may return empty results, but overall it is complete for a summary 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?
With 0% schema description coverage, the description provides essential meaning for all 5 parameters: period lists symbolic values, after/before specify ISO dates and precedence, person accepts multiple formats, project is optional. This adds significant value beyond the bare 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 gets a 'categorised hours summary' listing worked, client, internal, holidays. This distinguishes it from sibling tools like productive_list_time_entries (lists individual entries) and productive_get_employee_hours (likely different focus). The verb 'Get' and resource 'categorised hours summary' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains parameter behavior (period overrides after/before, person defaults to 'me', project optional) but does not explicitly state when to use this tool versus alternatives. No when-not or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all active Productive.io projects from local cache.
Returns id, name, number, and company for each project. Cache refreshes automatically every hour, or call productive_refresh_cache to force it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden, disclosing that the tool uses a local cache that refreshes automatically every hour and can be forced refreshed. It also states the return fields. Potential side effects or auth needs are not mentioned, but the behavior is well-scoped.
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 concise sentences with no redundancy. The most critical information (action, resource, return fields, cache mechanism) is front-loaded and efficiently conveyed.
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 simple nature (no params, output schema exists), the description covers the essential aspects: cache behavior, fields, and refresh option. It is arguably complete for a list tool, though it could mention if the cache lists only active projects and not archived ones.
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 input schema has no parameters, so the description adds no parameter-level detail, but the baseline for 0 parameters is 4. The tool's behavior is fully captured without needing 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?
Description clearly states 'List all active Productive.io projects from local cache,' specifying the action (list) and resource (projects). It distinguishes itself from sibling tools like productive_find_project (search) and productive_my_projects (personal scope) by implying full list vs. filtered.
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?
While the description mentions cache behavior and an alternative force-refresh tool (productive_refresh_cache), it does not explicitly guide when to use this tool vs. other project-related siblings like productive_find_project or productive_my_projects. Usage context is implied but not clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List services (billable activity types) on a given project.
Args: project: Project name (fuzzy) or numeric project id.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description implies a read operation ('List') and mentions fuzzy matching for project parameter, but lacks explicit statement on safety, destructiveness, or permissions.
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 structured Args section, front-loaded purpose, no superfluous content.
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?
Simple tool with one parameter and output schema; description covers main purpose and parameter usage, but could mention that it returns a list of billable activity types (though output schema likely covers that).
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 has 0% coverage for parameter description; description adds meaning: 'Project name (fuzzy) or numeric project id.' Compensates for missing schema detail.
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 verb 'List' and resource 'services (billable activity types)', and distinguishes from sibling tools like productive_list_projects and productive_list_time_entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; no mention of when not to use or context for selection among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List time entries, newest first.
Args: after: ISO date (YYYY-MM-DD) — include entries on/after this date. before: ISO date (YYYY-MM-DD) — include entries on/before this date. project: Project name or id to filter by. mine_only: If True (default), only return entries for the authenticated user.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| project | No | ||
| mine_only | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the default behavior of mine_only (True) and the ordering, but does not mention pagination, rate limits, or any 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?
The description is concise and well-structured, starting with a clear purpose statement followed by a parameter list. No unnecessary 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?
Given the existence of an output schema, the description adequately covers the parameters and their semantics. It does not need to explain return values, making it contextually complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description adds necessary context for each parameter: after/before as ISO dates, project as name or id, and mine_only as boolean with default. This compensates for the lack of schema 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 action ('List time entries') and the resource, and includes ordering ('newest first'). This distinguishes it from siblings like productive_log_time and productive_delete_time_entry.
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 does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or conditions. It merely describes the parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a time entry on a Productive.io project.
Args: project: Project name (fuzzy match, e.g. "1099 Acme") or numeric id. hours: Hours worked (float, e.g. 2.5). Converted to minutes internally. note: Optional description of the work. date: ISO date (YYYY-MM-DD). Defaults to today. service_hint: Optional service name/id if the project has multiple services. Once chosen, remembered as the project default.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| hours | Yes | ||
| note | No | ||
| date | No | ||
| service_hint | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: fuzzy matching for project, hours conversion, defaults for date, and the remembered service_hint trait. It does not cover auth requirements or rate limits, but these are less critical for a creation 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?
The description is concise: a clear one-line purpose followed by a well-structured bullet list of parameters. Every sentence adds value without 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 the number of parameters and absence of annotations, the description is thorough. It covers all parameters, explains defaults, conversions, and a behavioral nuance (service_hint remembered). The output schema exists to handle return values, so the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining each parameter's meaning, format (ISO date, float), conversion (hours to minutes), default behavior (date defaults to today), and special behavior (fuzzy match, service_hint remembered).
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 'Create a time entry on a Productive.io project.' with a specific verb and resource. It distinguishes from sibling tools like productive_update_time_entry and productive_delete_time_entry.
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 purpose is clear (creating a time entry), and the description implies when to use it. However, it does not explicitly state when not to use or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a summary of your week: projects touched, hours logged, recent entries.
Args: period: Symbolic period — defaults to "this_week". Also accepts "last_week", "this_month", "last_month".
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | this_week |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It states the output includes projects, hours, and entries, implying a read operation, but does not explicitly confirm read-only status, data scope (authenticated user), or potential 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?
The description is concise (two sentences plus args) with no wasted words. It could be slightly improved by using a bulleted list for args, but overall it is clear and 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?
Given the presence of an output schema (not shown), the description does not need to detail return values. It mentions key output elements. However, missing behavioral context like read-only semantics or authentication requirements prevents a higher score.
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 'period' is described with allowed values (this_week, last_week, this_month, last_month) and default, which adds full meaning beyond the schema that only provides type and default. Schema coverage is 0%, so the description fully compensates.
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 'Get a summary of your week: projects touched, hours logged, recent entries' clearly states the specific verb and resource. It distinguishes from sibling tools like productive_log_time or productive_get_time_report by focusing on a personal weekly overview.
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 usage for personal weekly summaries but does not explicitly state when to use this tool versus alternatives like productive_get_time_report or productive_list_time_entries. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active projects where you have logged time in the last 30 days.
Returns project id, name, number, and company for each.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses this is a read operation and lists returned fields. Could mention that it only includes projects with time logged in last 30 days, which it does.
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 short sentences, no fluff, front-loaded with action and condition. Every word 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?
Low complexity with no parameters and output schema present. Description covers the main purpose and output fields sufficiently.
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 exist; schema coverage is 100%. Description adds meaning about the tool's purpose without needing to describe parameters. Baseline for 0 params 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?
Description clearly states it lists active projects where time was logged in last 30 days, distinguishing it from sibling 'productive_list_projects' which likely lists all projects.
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 describes when to use (for recently logged time projects) and implicitly excludes use for full project list. Lacks explicit alternatives but context with sibling tools makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Force-refresh the projects/services/deals cache from Productive.
Call after creating new projects or services in Productive so they're visible to find_project.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose all behavioral traits. It indicates a 'force-refresh,' which implies cache clearing, but does not detail side effects like potential delays, rate limits, or whether it invalidates other cached data.
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 short sentences, front-loading the action and purpose. No unnecessary words, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema (not shown), the description is adequate but lacks details on the output or whether the tool is idempotent. It mentions 'deals' without definition, but domain context is assumed.
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 no parameters, and the input schema is fully documented (100% coverage). The description adds value by explaining the tool's purpose, though it does not need to elaborate on 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 explicitly states 'Force-refresh the projects/services/deals cache from Productive,' clearly identifying the tool as a cache refresh operation, distinct from sibling tools that handle CRUD or query operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Call after creating new projects or services in Productive so they're visible to find_project,' telling the agent exactly when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explicitly set (or override) the remembered default service for a project.
Args: project: Project name or id. service: Service name or id. Must belong to the project.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| service | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool sets or overrides a default, implying state mutation, but does not detail side effects, permissions, or reversibility.
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 extremely concise, with one sentence and a brief args list. Every word earns its place, and it is front-loaded with the purpose.
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's simplicity and the presence of an output schema, the description is minimally adequate. It covers basic intent and parameters but lacks usage guidelines and behavioral details, leaving some gaps.
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 description includes an 'Args' section that adds meaning beyond the input schema: 'Project name or id.' and 'Service name or id. Must belong to the project.' This compensates for the schema's 0% description 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 clearly states the tool 'Explicitly set (or override) the remembered default service for a project,' which is a specific action. However, it does not explicitly differentiate from sibling tools, though the purpose is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives or any prerequisites. It only states the action without contextual usage cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a time entry. Only provide fields you want to change.
Args: entry_id: Time entry ID (from productive_list_time_entries). hours: New hours value. date: New ISO date (YYYY-MM-DD). note: New note text. service_hint: New service name or id.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes | ||
| hours | No | ||
| date | No | ||
| note | No | ||
| service_hint | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states 'Edit' which implies mutation, and 'Only provide fields you want to change' suggests partial update behavior. But it doesn't disclose reversibility, auth needs, or side effects like whether empty fields are cleared.
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 very concise: one sentence followed by a bullet-style argument list. Every line adds value, no fluff. The key behavior ('only provide fields you want to change') 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 the 5 parameters and no annotations, the description sufficiently covers inputs. The existence of an output schema reduces need to explain return values. It could mention error handling or expected response, but not critical.
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%, so description must explain each parameter. It provides clear meaning: entry_id source, hours, date format (ISO), note, and service_hint (name or id). This adds essential context beyond the raw 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 uses the verb 'Edit' with 'a time entry', clearly specifying the action and resource. It distinguishes from siblings like productive_delete_time_entry (delete) and productive_log_time (log) by focusing on modification.
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 explicitly says 'Only provide fields you want to change', indicating a partial update pattern. However, it does not directly contrast with logging or deleting, leaving some ambiguity for the agent.
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.2.0productive_find_personproductive_get_employee_hoursproductive_get_time_reportproductive_my_briefingproductive_my_projectsv0.1.0productive_delete_time_entryproductive_find_projectproductive_list_projectsproductive_list_servicesproductive_list_time_entriesproductive_log_timeproductive_refresh_cacheproductive_set_default_serviceproductive_update_time_entryScored across 14 tools
Each tool has a clearly distinct purpose: searching people, searching projects, listing/creating/updating/deleting time entries, reporting hours, managing cache, etc. No two tools appear to do the same thing.
All tools follow a consistent verb_noun pattern with snake_case (e.g., productive_list_time_entries, productive_log_time). Even 'my_briefing' and 'my_projects' fit the pattern as personal retrieval operations.
14 tools is an appropriate number for a time-tracking MCP server, covering core operations without being overwhelming. Each tool serves a necessary function.
The tool set covers CRUD for time entries, project and person search, reporting, and cache management. Minor gaps exist (e.g., no direct 'get project details' tool, but list_projects provides adequate info).
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for generating rough-draft project plans from natural-language prompts.
MCP server for Linear project management and issue tracking
A MCP server built for developers enabling Git based project management with project and personal…
