Operate Hubstaff via MCP: read account/org/project/task/member data, view tracked time and daily summaries, create tasks, and make authenticated raw API calls.
Get the authenticated Hubstaff user
List organizations, projects, members, and tasks
Get a project by ID
Create tasks in a project
List tracked-time activities for an organization/time range
Get per-day aggregated tracked-time activities
Make arbitrary authenticated Hubstaff v2 API requests (GET/POST/PUT/PATCH/DELETE)
Per README: log manual time, view timesheets, and read teams
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., "@hubstify-mcp show my tracked time for this week"
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.
A Model Context Protocol (MCP) server for Hubstaff. Operate your Hubstaff organizations, projects, tasks, members, tracked-time activities and timesheets through any MCP-compatible LLM client. Read your timesheet, log time, and inspect your team in natural language.
Built on FastMCP and scaffolded from
the-momentum/python-ai-kit.
You need two things: a Hubstaff Personal Access Token, and one config entry in your
client. No clone required: uv runs the server
straight from GitHub.
1. Get a Personal Access Token at
developer.hubstaff.com/account/personal-access-tokens.
That's the value of HUBSTAFF_PERSONAL_ACCESS_TOKEN in the steps below.
2. Add the server to your client:
claude mcp add hubstaff \
-e HUBSTAFF_PERSONAL_ACCESS_TOKEN=your_pat_here \
-- uvx --from git+https://github.com/farce1/hubstify-mcp.git hubstaff-mcpclaude mcp list should then show hubstaff connected. Add -s user to enable it
across all your projects.
Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/,
Windows: %APPDATA%\Claude\). Cowork shares the same desktop MCP configuration:
{
"mcpServers": {
"hubstaff": {
"command": "uvx",
"args": ["--from", "git+https://github.com/farce1/hubstify-mcp.git", "hubstaff-mcp"],
"env": { "HUBSTAFF_PERSONAL_ACCESS_TOKEN": "your_pat_here" }
}
}
}Restart the app afterward.
Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects)
with the same mcpServers block shown above for Claude Desktop.
Add to ~/.codex/config.toml:
[mcp_servers.hubstaff]
command = "uvx"
args = ["--from", "git+https://github.com/farce1/hubstify-mcp.git", "hubstaff-mcp"]
env = { HUBSTAFF_PERSONAL_ACCESS_TOKEN = "your_pat_here" }Prefer a local clone? After
git clone … && uv sync, replace the launch command everywhere above withuv --directory /absolute/path/to/hubstify-mcp run hubstaff-mcp.
3. Try it. Ask your assistant:
"Who am I on Hubstaff?" → get_current_user
"Show my tracked time this week." → get_tracked_time
"Give me my timesheet summary for last month." → get_timesheet
"What projects and tasks am I assigned to?" → get_projects + get_tasks
"Log 2 hours to project Acme today with note 'API integration'." → log_time
Related MCP server: timedoctor-mcp
Tool | Kind | Description |
| read | The authenticated user (you) |
| read | Organizations you belong to |
| read | Projects in an organization (defaults to your default org) |
| read | Tasks in a project |
| read | Members of an organization |
| read | Teams in an organization |
| read | Your tracked time per day for a period (optional project filter) |
| read | Your tracked time summarised per project for a period |
| create | Create a manual time entry for yourself |
| create | Create a task in a project |
| read | Guarded raw GET for |
Hubstaff v2 limitation: time entries are create-only. The v2 API has no endpoint to edit or delete a tracked-time entry, so this server intentionally does not expose update/delete tools; do that in the Hubstaff web app. Tracked time is read via daily activities.
🔑 PAT auth with automatic access-token refresh and rotation handling (the rotated refresh token is persisted; the token endpoint's 5/hour limit is respected)
⏱️ Read tracked time and per-project timesheets over natural periods ("this week", "last month", …)
✍️ Log manual time entries and create tasks
🛡️ Rate-limit aware (honors Retry-After, backs off on 5xx) with cursor pagination
🧰 A guarded read-only escape hatch for endpoints without a dedicated tool
The config above needs no clone, but the same hubstaff-mcp command is available via:
uv tool install git+https://github.com/farce1/hubstify-mcp.git # persistent, on PATH
pipx run --spec git+https://github.com/farce1/hubstify-mcp.git hubstaff-mcp # pipx
pip install git+https://github.com/farce1/hubstify-mcp.git # into a venv
# From source (development):
git clone https://github.com/farce1/hubstify-mcp.git && cd hubstify-mcp && uv syncVariable | Required | Default | Description |
| ✅ | - | Your Hubstaff Personal Access Token |
| - |
| Where the rotated token cache is persisted |
| - | first org | Organization id used when a tool isn't given one |
| - |
|
|
| - |
| Bind address when |
| - |
| Port when |
Hubstaff rotates the refresh token on every exchange; this server persists the newest token (mode
0600) so it survives restarts. If you revoke the token, updateHUBSTAFF_PERSONAL_ACCESS_TOKENand delete the token store file.
HUBSTAFF_PERSONAL_ACCESS_TOKEN is not set: the env var didn't reach the
server; check the env block in your client config.
Auth errors after it worked before: the token may have been revoked or
rotated out of band. Update HUBSTAFF_PERSONAL_ACCESS_TOKEN and delete
~/.hubstaff-mcp/tokens.json.
Wrong day for "today"/"this week": the server uses your Hubstaff account's timezone; check it under your Hubstaff profile settings.
By default the server talks stdio (the client spawns it as a subprocess). To run
it as a long-lived HTTP service instead, set MCP_TRANSPORT=http:
HUBSTAFF_PERSONAL_ACCESS_TOKEN=your_pat MCP_TRANSPORT=http MCP_PORT=8000 \
uvx --from git+https://github.com/farce1/hubstify-mcp.git hubstaff-mcpThe endpoint is then http://<host>:<port>/mcp, which any HTTP-capable MCP client
can connect to.
⚠️ Single-user only. The server acts as the one identity behind
HUBSTAFF_PERSONAL_ACCESS_TOKEN; every request reads and writes that account's Hubstaff data. Do not expose this endpoint to other people or the public internet; keep it bound to localhost or your private network and put your own authentication in front of it. Multi-tenant hosting (each user with their own Hubstaff token) is not yet supported.
make install # uv sync --all-groups
make test # pytest
make lint # ruff check
make typecheck # ty check
make check # lint + typecheck + tests + format checkA thin, layered design (each layer has one responsibility):
app/
├── domain/ # Pydantic models + value objects (Duration, DateRange)
├── hubstaff/ # auth (token rotation) + HTTP client (retry, pagination)
├── repositories/ # one per aggregate: endpoints + envelope -> domain models
├── services/ # use-case logic (date normalization, timesheet projection)
└── mcp/ # FastMCP tools (thin adapters) + composition rootMIT. See LICENSE.
Create a new task within a project.
| Name | Required | Description | Default |
|---|---|---|---|
| details | No | Optional task details. | |
| summary | Yes | Task summary / title. | |
| project_id | Yes | Project id the task belongs to. | |
| assignee_ids | No | User ids to assign the task to. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'Create' without disclosing any behavioral traits such as permissions required, idempotency, side effects, or return behavior. This is insufficient for an agent to anticipate the tool's full behavior.
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 a single, short sentence that is concise and front-loaded. However, it could include more detail without significant bloat, so it is not at a perfect 5.
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 lack of an output schema, no annotations, and 4 parameters, the description is too minimal. It does not explain expected outcomes, error conditions, or any constraints, leaving the agent without enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. The description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.
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 'Create a new task within a project' uses a specific verb (create) and resource (task within a project), clearly distinguishing it from sibling tools like hubstaff_list_tasks which are for listing.
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 is provided on when to use this tool vs alternatives, such as when to use list_tasks instead. There are no prerequisites or contextual usage hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get per-day aggregated tracked-time activities for an organization over a date range (dates are YYYY-MM-DD).
| Name | Required | Description | Default |
|---|---|---|---|
| user_ids | No | Filter by user ids. | |
| date_stop | Yes | End date, YYYY-MM-DD. | |
| date_start | Yes | Start date, YYYY-MM-DD. | |
| page_limit | No | Number of records per page (max 500). | |
| project_ids | No | Filter by project ids. | |
| page_start_id | No | Cursor id to start the page from (for pagination). | |
| organization_id | Yes | Organization id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavior. It reveals aggregation per day and date range, but omits details like authentication, rate limits, or what happens with overlapping dates. The behavioral context 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?
A single, concise sentence that communicates the core purpose without extraneous words. Perfectly structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (aggregation over date range). No output schema exists, but the description adequately explains what is returned (per-day aggregated activities). However, it could detail pagination or the aggregation formula. Still, it's mostly complete for the complexity level.
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?
All 7 parameters are described in the schema (100% coverage), so the baseline is 3. The description adds no additional meaning beyond what's in the schema, merely restating the date range concept.
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 retrieves per-day aggregated tracked-time activities for an organization over a date range, with explicit date format. This distinguishes it from sibling tools like list_activities, which likely returns raw activities.
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 explicit guidance on when to use this versus alternatives (e.g., sibling list_activities). Usage is implied by the description (when daily aggregates are needed), but no exclusions or conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the authenticated Hubstaff user (the owner of the access token).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It correctly indicates a read-only operation ('get'). While it does not detail rate limits or authentication, the simplicity of the tool and the description's clarity are sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys the tool's purpose. No redundant 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?
Given the tool has no parameters and no output schema, the description is fully adequate. It explains what the tool returns (the authenticated user) and is complete for its 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?
The input schema has zero parameters. Per guidelines, baseline is 4. The description does not need to add parameter information since there are none.
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 function: retrieving the authenticated Hubstaff user. It specifies the user is the owner of the access token, distinguishing it from sibling tools that operate on projects, tasks, or activities.
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 explicit guidance on when to use this tool versus alternatives. However, the tool is simple (no parameters) and the context implicitly suggests it is for obtaining current user info. No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single project by id.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations; description fails to disclose read-only nature, authentication needs, or any behavioral traits beyond basic retrieval.
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?
Single sentence, front-loaded, no wasted words. Could be more informative but efficient for a simple tool.
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, no annotations, no error handling or return format described; incomplete for a tool with no supplementary docs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description adds minimal value by restating 'by id'. Baseline 3 applies.
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 verb 'Get', resource 'single project', and identifier 'by id'. Distinguishes from sibling list_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?
No guidance on when to use this vs list_projects or other tools. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tracked time activities for an organization within a time range. Times are ISO 8601 (e.g. 2024-01-01T00:00:00Z).
| Name | Required | Description | Default |
|---|---|---|---|
| user_ids | No | Filter by user ids. | |
| page_limit | No | Number of records per page (max 500). | |
| project_ids | No | Filter by project ids. | |
| page_start_id | No | Cursor id to start the page from (for pagination). | |
| time_slot_stop | Yes | End of the range, ISO 8601 timestamp. | |
| organization_id | Yes | Organization id. | |
| time_slot_start | Yes | Start of the range, ISO 8601 timestamp. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions ISO 8601 format but omits critical details like pagination behavior, data volume, ordering, rate limits, or whether the tool is read-only. The schema reveals pagination parameters but the description does not explain the cursoring mechanism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences with no wasted words. The structure is logical: action first, then format clarification. Could be improved by integrating more behavioral info without sacrificing conciseness.
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 7 parameters (including optional filters and pagination), no output schema, and no annotations, the description should cover pagination, ordering, result format, and usage constraints. It fails to address these, leaving significant gaps for an AI agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds the ISO 8601 format hint, which is already present in the schema descriptions for the time parameters. Minimal added 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 lists tracked time activities for an organization within a time range, using specific verbs and resources. It distinguishes the tool from siblings like hubstaff_daily_activities by implying a more granular time-based listing, but does not explicitly differentiate.
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 (e.g., hubstaff_daily_activities) or when not to use it. The description provides no context on prerequisites, exclusion criteria, or recommended scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List members (users) of an organization.
| Name | Required | Description | Default |
|---|---|---|---|
| page_limit | No | Number of records per page (max 500). | |
| page_start_id | No | Cursor id to start the page from (for pagination). | |
| organization_id | Yes | Organization id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It merely says 'List members' without mentioning pagination behavior (evident from input schema params), rate limits, or what constitutes a 'member' (e.g., active vs. inactive). This lack of disclosure makes it insufficiently 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?
The description is a single, concise sentence with no wasted words. It is appropriately short for a simple list operation.
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 absence of an output schema and the presence of pagination parameters, the description should explain pagination behavior and the return format. It fails to do so, leaving the agent uncertain about how to iterate through results. This incompleteness lowers the 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?
With 100% schema description coverage, the description adds no additional meaning beyond the schema. The baseline is 3, and the description does not provide new insights into parameter usage, but the schema itself is clear.
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 members (users)' and specifies the resource 'of an organization', distinguishing it from sibling tools that list other resources like projects or activities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use or when-not-to-use guidance. The context from sibling tool names implies it lists members, but there is no mention of prerequisites (e.g., needing an organization ID) or alternatives. A score of 3 is appropriate for implied usage with no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Hubstaff organizations the authenticated user has access to. Use the returned organization id for project, member and activity tools.
| Name | Required | Description | Default |
|---|---|---|---|
| page_limit | No | Number of records per page (max 500). | |
| page_start_id | No | Cursor id to start the page from (for pagination). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It describes a read-only list operation but omits any mention of pagination behavior, rate limits, authentication requirements, or side effects, leaving significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and front-loaded with the core purpose. Every sentence earns its place with 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 list tool with two optional parameters and no output schema, the description covers the primary purpose and usage hint. It lacks mention of pagination details but is otherwise sufficient for basic agent decision-making.
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 100% for both parameters, meeting the baseline. The description adds no additional meaning beyond the schema, which is adequate but does not enhance parameter understanding.
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 lists organizations the authenticated user has access to, specifying the verb 'List' and resource 'organizations'. It additionally explains the purpose of the returned organization ID for use in other tools, distinguishing it clearly from sibling tools like task or activity tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use the returned organization ID for project, member, and activity tools, providing a direct use case. However, it does not mention when not to use this tool or compare it with alternatives, leaving some implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List projects within an organization.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by project status. | |
| page_limit | No | Number of records per page (max 500). | |
| page_start_id | No | Cursor id to start the page from (for pagination). | |
| organization_id | Yes | Organization id. |
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 only states the basic action, omitting behavioral traits such as required permissions, pagination behavior, default ordering, or whether it returns all projects or only those with specific statuses. The agent has no insight into resource consumption 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?
The description is a single concise sentence that covers the core purpose without extraneous words. However, it could be slightly more structured by front-loading key constraints like required organization_id.
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 4 parameters, no output schema, and no annotations, the description is insufficient. It fails to explain pagination (page_start_id), filtering (status), or the output format, leaving the agent without critical context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all four parameters, including type, enum, and constraints. The description adds no additional meaning beyond the schema, so a baseline of 3 is appropriate.
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 'List projects within an organization,' specifying the verb (list) and resource (projects) with scope (within an organization). This distinguishes it from sibling tools like hubstaff_get_project (single project) and hubstaff_list_tasks (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool over alternatives, nor any context for best usage. For example, it doesn't mention that to get details of a single project one should use hubstaff_get_project, or that filtering by status is available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tasks belonging to a project.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by task status. | |
| page_limit | No | Number of records per page (max 500). | |
| project_id | Yes | Project id. | |
| page_start_id | No | Cursor id to start the page from (for pagination). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral transparency. It only states 'List tasks belonging to a project' without disclosing pagination behavior, sorting, rate limits, or any side effects. The presence of pagination parameters in the schema is not echoed in the description.
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 a single sentence that efficiently conveys the core purpose. It is front-loaded and contains no superfluous information, earning a top score for conciseness.
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 pagination parameters and no output schema, the description is incomplete. It does not explain pagination behavior, return format, or ordering. A more complete description would address these aspects to help the agent use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for each parameter. It does not mention or contextualize any parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'tasks belonging to a project', clearly indicating the tool's function. It distinguishes from the sibling 'hubstaff_create_task' but not from other list tools like 'hubstaff_list_activities' or 'hubstaff_list_projects', though the resource name provides differentiation.
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. There is no mention of when not to use it or any listed alternatives, leaving the agent to infer based solely on the tool name and resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform an arbitrary authenticated request against the Hubstaff v2 API. Use this for endpoints not covered by a dedicated tool. Path is relative to https://api.hubstaff.com/v2 (e.g. '/organizations').
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | JSON request body (for writes). | |
| path | Yes | API path relative to the v2 base URL. | |
| query | No | Query parameters as a key/value object. | |
| method | No | HTTP method. | GET |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions authentication and the base URL, but does not disclose potential destructive actions, rate limits, or error behavior. Adequate but not comprehensive.
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, no wasted words. Exceptionally concise and structured.
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?
Covers purpose, usage, and path structure. Lacks details on authentication method, error handling, and safety warnings, which would be important for a raw request tool. Complete enough for its simplicity but leaves 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?
Schema coverage is 100%, so description adds marginal value. It provides the base URL and an example path, which clarifies the path parameter beyond the schema. Baseline 3 is appropriate.
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 the tool performs arbitrary authenticated requests against the Hubstaff v2 API, with explicit note to use for endpoints not covered by dedicated tools. This distinguishes it from sibling tools effectively.
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 clear guidance: 'Use this for endpoints not covered by a dedicated tool.' This tells the agent when to prefer this tool over siblings, though it lacks explicit when-not-to-use scenarios.
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.0hubstaff_create_taskhubstaff_daily_activitieshubstaff_get_current_userhubstaff_get_projecthubstaff_list_activitieshubstaff_list_membershubstaff_list_organizationshubstaff_list_projectshubstaff_list_taskshubstaff_raw_requestScored across 10 tools
Most tools have clearly distinct purposes. However, `daily_activities` and `list_activities` both deal with tracked time and could cause confusion if an agent does not read the descriptions carefully.
The `hubstaff_` prefix is consistent, but the verb pattern is mixed: most use verb_noun (e.g., `list_projects`, `create_task`), but `daily_activities` uses an adjective instead of a verb, and `raw_request` is adjective_noun. `get_` vs `list_` is acceptable for single vs multiple.
10 tools is well-scoped for a Hubstaff API client. Each tool covers a distinct resource (organizations, projects, tasks, members, activities, current user) and the set is not overwhelming.
Core read and create operations are present for tasks, projects, and activities. However, there are no update or delete tools for any resource, and time tracking actions like start/stop are missing. The `raw_request` tool can fill gaps but reduces the dedicated surface.
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
GibsonAI MCP server: manage your databases with natural language
The HubSpot MCP Server acts as a bridge that enables AI assistants and Large Language Models to securely interact with HubSpot CRM data through natural conversation, without requiring users to understand complex API structures. It provides read-only access to standard CRM objects (contacts, companies, deals, tickets, products, invoices, and more) and their associations, secured via OAuth 2.0, allowing AI agents to perform tasks like summarizing deals, fetching company updates, and looking up record changes.
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
