Manage Basecamp 2 projects, todos, messages, and people via the Basecamp 2 API.
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., "@Basecamp 2 MCP Show me my projects"
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 that connects Claude and other AI assistants to the Basecamp 2 API. Manage projects, todos, messages, and people directly from your AI assistant.
Node.js 18 or later
A Basecamp 2 account
OAuth 2 credentials or your username and password
Related MCP server: Basecamp MCP Server
Register your app at launchpad.37signals.com/integrations to obtain a client_id and client_secret.
Run the auth helper — it opens a browser, handles the redirect, exchanges the code for tokens, and prints your BASECAMP_ACCOUNT_ID automatically:
BASECAMP_CLIENT_ID=your_client_id \
BASECAMP_CLIENT_SECRET=your_client_secret \
npx basecamp-2-mcp-authCopy the printed env vars into your .env or MCP server config.
The MCP server will automatically refresh the access token when it expires (~2 weeks) as long as BASECAMP_REFRESH_TOKEN, BASECAMP_CLIENT_ID, and BASECAMP_CLIENT_SECRET are set.
By default
npx basecamp-2-mcp-authlistens on port3000. SetOAUTH_PORTto change it (your registered redirect URI must match).
Variable | Required | Description |
| Yes | Your account ID — printed by the auth helper, or found in the URL: |
| Yes* | OAuth 2 access token |
| No | Enables automatic token refresh when the access token expires |
| No† | Required for automatic token refresh |
| No† | Required for automatic token refresh |
| Yes* | Your Basecamp email (Basic Auth alternative) |
| Yes* | Your Basecamp password (Basic Auth alternative) |
| Yes | Identifies your integration, e.g. |
* Either BASECAMP_ACCESS_TOKEN or both BASECAMP_USERNAME + BASECAMP_PASSWORD are required.
† Required together with BASECAMP_REFRESH_TOKEN to enable automatic token refresh.
Add the following to your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"basecamp-2": {
"command": "npx",
"args": ["-y", "basecamp-2-mcp"],
"env": {
"BASECAMP_ACCOUNT_ID": "your_account_id",
"BASECAMP_ACCESS_TOKEN": "your_access_token",
"BASECAMP_REFRESH_TOKEN": "your_refresh_token",
"BASECAMP_CLIENT_ID": "your_client_id",
"BASECAMP_CLIENT_SECRET": "your_client_secret",
"USER_AGENT": "MyApp (you@example.com)"
}
}
}
}Then restart Claude Desktop.
claude mcp add basecamp-2 -- npx -y basecamp-2-mcpThen set the required environment variables in your shell or .env file.
# 1. Clone the repo and install dependencies
npm install
# 2. Copy and fill in environment variables
cp .env.example .env
# 3. Build
npm run build
# 4. Start the MCP server
npm startFor development with live reload:
npm run devTo test interactively with the MCP Inspector:
npx @modelcontextprotocol/inspector npx tsx src/index.tsTool | Description |
| List all active projects |
| Get a project by ID |
Tool | Description |
| Get the currently authenticated user |
| List all people in the account |
| Get a person by ID |
Tool | Description |
| List all todo lists in a project |
| Get a todo list with its todos |
| Create a new todo list in a project |
Tool | Description |
| List all todos in a todo list |
| Get a single todo item |
| Create a new todo (supports due date + assignee) |
| Update a todo's content, due date, or assignee |
| Mark a todo as completed |
| Delete a todo item |
Tool | Description |
| List all topics (messages, forwards, etc.) in a project |
| Get a full message by ID (use the |
| Post a new message to a project |
Basecamp 2 uses OAuth 2 via Launchpad. The authorization flow is:
User visits https://launchpad.37signals.com/authorization/new?type=web_server&client_id=…&redirect_uri=…
After approving, Basecamp redirects to your redirect_uri with a short-lived code
Your app POSTs the code to https://launchpad.37signals.com/authorization/token to receive an access token and a refresh token
Access tokens are sent as Authorization: Bearer <token>. Refresh tokens last ~2 weeks.
The npx basecamp-2-mcp-auth helper handles steps 1–3 automatically. The MCP server handles step 4 including silent refresh.
Every API request must also include a User-Agent header identifying your app and a contact email — this is a Basecamp API requirement. See Identifying your application.
MIT
Mark a todo as completed
| Name | Required | Description | Default |
|---|---|---|---|
| todo_id | Yes | The todo ID | |
| project_id | Yes | The project 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. 'Mark as completed' implies a mutation, but it doesn't disclose permissions required, whether the change is reversible, what happens to related data, or any side effects. This is a significant gap for a mutation 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?
A single, efficient sentence with no wasted words. The action is front-loaded and clear.
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 mutation tool with no annotations, no output schema, and minimal description, this is incomplete. It should at least mention side effects, required permissions, or interaction with other tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (todo_id and project_id). The description adds no additional meaning beyond the operation itself. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb (complete) and resource (todo), making the action distinct from siblings like create_todo, update_todo, and delete_todo. However, it doesn't specify scope or differentiation beyond the obvious verb difference.
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 update_todo or other status-changing alternatives. It doesn't explain prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a new message to a Basecamp 2 project
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Message body (HTML supported) | |
| private | No | Whether the message is private (default false) | |
| subject | Yes | Message subject / title | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It states that a message is posted, but does not disclose permissions, side effects, whether notifications are sent, or any other operational context.
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, front-loaded sentence with no wasted words. It immediately communicates the action and target resource.
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 create operation with full schema coverage and no output schema, the description is minimally sufficient. However, with no annotations and no usage guidance, it leaves important behavioral and routing context unaddressed.
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 all four parameters are already documented in the schema. The description adds no additional parameter meaning, which meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: posting a new message to a Basecamp 2 project. It is clearly distinct from retrieval siblings like get_message, but it does not explicitly differentiate usage from other create tools such as create_todo.
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 given about when to use this tool versus siblings or alternatives. The create intent is implied only by the word 'Post' and the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new todo item in a todo list
| Name | Required | Description | Default |
|---|---|---|---|
| due_on | No | Due date in YYYY-MM-DD format (optional) | |
| content | Yes | The text content of the todo | |
| project_id | Yes | The project ID | |
| assignee_id | No | Person ID to assign this todo to (optional) | |
| todolist_id | Yes | The todo list ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not disclose permission or auth requirements, whether the todo is appended to the end of the list, what defaults apply when optional fields are omitted, or what the response returns. Only the bare fact of creation is conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler and the purpose front-loaded. It is efficient, though the brevity is partly under-specification rather than disciplined concision.
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 5-parameter mutation tool with no annotations and no output schema, the description is thin. It never notes the three required fields (project_id, todolist_id, content), the need for an existing todolist, or any behavioral outcome, leaving the agent reliant entirely on the schema.
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 the schema already documents all five parameters including formats like YYYY-MM-DD for due_on. The description adds no parameter-level meaning beyond the schema, which matches the baseline 3 for a fully covered 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?
States a specific verb (create) and resource (todo item in a todo list), which distinguishes it from get_todo, update_todo, delete_todo, and complete_todo. However, it does not explicitly differentiate itself from create_todolist or create_message beyond the resource noun, so it stops short of a 5.
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 offers no guidance on when to use this tool versus alternatives like create_todolist (which must exist first) or update_todo. No prerequisites, no mention that a todolist must already exist, and no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new todo list in a Basecamp 2 project
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the todo list | |
| project_id | Yes | The project ID | |
| description | No | Optional description for the todo list |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, yet it only says a list is created. It does not disclose auth/permission needs, whether duplicate names are allowed, whether the new list is returned, or whether project_id must already exist. For a mutation tool with zero annotation coverage this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the purpose is immediately clear. It is efficient, though its brevity is partly under-specification rather than tight editing.
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 create/mutation tool with no annotations, no output schema, and no return-value documentation, the description should explain at minimum the permission model and result. It leaves the agent without enough context to call this confidently in an ambiguous situation.
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 all three parameters (name, project_id, description) are already documented in the schema, including which are optional. The description adds nothing beyond that, so the 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?
States a specific verb (create) and resource (todo list) plus scope (in a Basecamp 2 project), which separates it from the singular create_todo sibling. It stops short of explicitly naming that sibling or clarifying list-vs-item semantics, so it is clear but not sibling-differentiating at the top level.
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 indication of when to use this versus create_todo or update_todo, no prerequisites (e.g. that project_id must reference an existing project), and no note on behavior when a list name already exists. The agent is left to infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a todo item
| Name | Required | Description | Default |
|---|---|---|---|
| todo_id | Yes | The todo ID | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Delete' implies a mutation, but it does not disclose whether deletion is permanent, reversible, soft-delete only, what happens to associated data, or what permissions are required — all important for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. However, it is so terse that it functions more as a restatement of the tool name than as an informative definition.
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 destructive mutation tool with no annotations and no output schema, the description is incomplete. It omits consequences, prerequisites, reversibility, and any routing guidance relative to complete_todo or update_todo, leaving the agent with insufficient context to use it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents both parameters ('The todo ID', 'The project ID'). The description adds no additional meaning, syntax, or constraints beyond what the schema provides, making the baseline of 3 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 states a specific verb and resource ('Delete a todo item'), so an agent immediately knows the action is removal of a todo. It does not differentiate from siblings such as complete_todo, update_todo, or get_todo, which is the only gap.
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?
There is no guidance on when to use this tool versus alternatives. It does not mention that complete_todo exists for finishing items, nor does it state prerequisites like needing a valid project_id/todo_id or whether this should be used only after confirming the todo should be removed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the currently authenticated Basecamp 2 user
| 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 implies a read-only, zero-argument lookup with no side effects, which is correct for a 'get me' tool. However, it says nothing about authentication requirements, whether the call can fail for an unauthenticated session, or what fields the returned user includes.
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 front-loaded sentence with no filler; every word (verb, scope qualifier, resource, product version) 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?
For a trivial zero-parameter lookup this is close to adequate, but with no output schema and no annotations, the description gives no hint of the shape of the returned user object, which an agent would need to use the result.
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 takes zero parameters, so per the baseline rule there is nothing for the description to clarify beyond what the empty schema already shows. No ambiguity exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb ('Get') and resource ('the currently authenticated Basecamp 2 user'), and the 'currently authenticated' qualifier implicitly distinguishes it from sibling get_person, which requires an explicit identifier. It is not tautological and an agent can tell what it returns, though it never names a sibling outright.
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?
There is no explicit when-to-use or when-not-to-use statement, but the phrase 'currently authenticated user' strongly implies the intended case (identifying the caller) versus fetching an arbitrary person via get_person or list_people. Guidance is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single message from a Basecamp 2 project
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | The message ID | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It implies a read operation but does not disclose permissions, rate limits, error behavior, or whether it is read-only; a bare 'Get' leaves behavioral traits unstated.
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 with verb and resource, with zero wasted words. It is appropriately sized for a simple retrieval 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?
Given the low complexity and full schema coverage, the description is minimally adequate for calling the tool. However, with no output schema and no annotations, it omits return format, error handling, and read-only confirmation, leaving clear 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 description coverage is 100%, so the schema already documents both parameters. The phrase 'from a Basecamp 2 project' faintly reinforces project_id but adds no syntax, format, or meaning beyond the schema, so 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?
States a specific verb (Get) and resource (a single message) scoped to Basecamp 2 projects. It does not explicitly distinguish from sibling create_message or list_topics, but the get vs create/list distinction is clear 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?
No when-to-use guidance, no alternatives, no prerequisites. The description does not tell the agent when to choose get_message over list_topics or other retrieval siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single person in the Basecamp 2 account by ID
| Name | Required | Description | Default |
|---|---|---|---|
| person_id | Yes | The person ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. The verb 'Get' reasonably implies a non-mutating read, but the description does not confirm read-only semantics, state what happens when the ID is not found, or describe auth requirements or the return shape.
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 front-loaded sentence with no redundant or filler content. Every element (verb, resource, cardinality, scope, lookup key) 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?
For a simple single-record fetch the definition is serviceable, but with no annotations and no output schema the description should at minimum confirm the read-only nature and note not-found behavior. The scope detail ('Basecamp 2 account') is the main compensating element.
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% for the single person_id parameter, so the schema already documents it fully. The description's 'by ID' adds no format, range, or sourcing detail beyond what the schema provides, matching the baseline for a fully covered single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (get), resource (person), and scope (single record in the Basecamp 2 account, by ID), which clearly separates it from list_people. It does not explicitly distinguish itself from get_me, which also returns a person-like resource, so it stops short of full sibling 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 phrase 'by ID' implies the tool is used when the caller already has a person identifier, which is useful context. However, no alternative is named and no condition for choosing get_person over list_people or get_me is given, leaving usage to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Basecamp 2 project by ID
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It conveys only that this is a read of one project; it says nothing about authentication requirements, behavior when the ID is invalid or inaccessible, or what the returned project object contains.
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?
One short, front-loaded sentence with zero filler. 'Basecamp 2' is a meaning-bearing qualifier given the API version differences, so every word 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?
For a single-parameter read with no output schema, the description is minimally adequate: it identifies the platform version and retrieval mode. It stops short of describing the response shape or failure behavior, which with no output schema and no annotations would add real value.
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?
There is a single required parameter documented at 100% schema coverage, so the schema already carries the semantics. The description adds only that the ID refers to a Basecamp 2 project, which is context but not parameter-detail beyond the schema. 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?
States a specific verb (Get) and resource (project) and the 'single ... by ID' phrasing implicitly contrasts with the sibling list_projects. It does not name the sibling explicitly, but the singular scope is unambiguous.
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?
There is no when-to-use guidance, no mention of when to prefer this over list_projects, and no prerequisites or error conditions. Usage is only implied by the tool name and the ID-based retrieval semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single todo item
| Name | Required | Description | Default |
|---|---|---|---|
| todo_id | Yes | The todo ID | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. The verb 'Get' implies a read operation, but the description does not disclose permissions, error handling (e.g., not found), or return behavior. It adds little beyond the tool name.
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, front-loaded sentence with no wasted words. It conveys the core purpose immediately.
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 single-item retrieval tool with a fully specified input schema, the description is minimally adequate. However, with no output schema and no annotations, it does not describe what the returned todo item contains or any error/edge-case behavior.
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 both parameters (todo_id and project_id) are already documented in the schema. The description adds no additional parameter meaning, syntax, or constraints beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get a single todo item.' It clearly distinguishes the tool from list_todos by specifying a single item, but it does not explicitly name or differentiate from other siblings like create_todo or update_todo beyond the operation type.
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?
There is no guidance on when to use this tool versus alternatives, nor any prerequisites or conditions. The description only states what it does, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single todo list with its todos
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID | |
| todolist_id | Yes | The todo list ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It usefully reveals that the response embeds the list's todos (a behavioral trait beyond the input schema), but says nothing about permission requirements, not-found/error behavior, or what happens with an invalid project_id.
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 front-loaded sentence with zero filler; the scope qualifier is placed where it is immediately visible.
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 two-parameter read with fully documented inputs and no output schema, the description covers the essentials and hints at the return payload. However, with no annotations an agent still lacks error, auth, and pagination context for this read operation.
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% — both project_id and todolist_id are documented in the schema as required numbers. The description adds no format, range, or relationship details beyond what the schema already supplies, so the 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?
States a specific verb (get) and resource (todo list) and adds scope detail — 'a single todo list with its todos' — which distinguishes it from list_todolists. It does not explicitly contrast with the sibling get_todo, but the resource is unambiguous.
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 when-to-use guidance, no prerequisites, and no mention of alternatives such as list_todolists or get_todo. The agent must infer usage purely from the name and resource scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all people in the Basecamp 2 account
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the burden. 'List all' implies a read-only enumeration scoped to the entire account, which is useful context, but it says nothing about pagination, result caps, or whether it is safe/non-mutating — expected for a lister but not disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single eight-word sentence with the scope front-loaded and no filler. Nothing is wasted, nothing extraneous to trim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only enumeration with no output schema or nested objects, the description covers the essential scope. The only meaningful omission is enumerating return shape or pagination expectations, a minor gap at this 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?
The tool takes zero parameters, so per the rubric this is a baseline 4. There is nothing for the description to disambiguate, and it correctly implies no filtering input is required.
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?
Clear verb+resource: 'List all people in the Basecamp 2 account.' An agent immediately knows this returns people records. It doesn't explicitly contrast with the sibling get_person (single-person retrieval), though the verb 'list' vs 'get' makes the distinction reasonably inferable.
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 versus get_person or list_projects. There are no parameters or filters to explain, but the description also does not state whether this is the entry point for enumerating users before calling get_person.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all active Basecamp 2 projects
| 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 full burden. It does disclose a meaningful behavioral constraint, that only active Basecamp 2 projects are returned, which is useful signal. However it says nothing about pagination, result size, ordering, or auth requirements for a list endpoint.
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 front-loaded sentence with no filler. Every word (list, active, Basecamp 2, projects) carries 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 zero-parameter list tool with no output schema, the description covers the essential scope but omits pagination/return-volume behavior, which matters for a list endpoint. Adequate but not 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?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The scoping words 'active' and 'Basecamp 2' are behavior filters, not 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?
States a specific verb and resource ('List ... projects') plus two useful scoping qualifiers: 'active' and 'Basecamp 2'. It contrasts implicitly with the sibling get_project (single project), though it never names that sibling explicitly.
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?
Usage is implied by the name and the 'list all active' phrasing, but there is no guidance on when to prefer this over get_project or how it relates to the other list_* tools. No exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all todo lists in a Basecamp 2 project
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It implies a read-only list operation but discloses nothing about pagination, permissions, result ordering, or what happens for an invalid project_id — significant gaps for a tool with zero annotation coverage.
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 compact sentence with the resource and scope front-loaded and no wasted words. It is slightly under-specified rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with full schema coverage and no output schema, the description is minimally complete but omits return-shape expectations and pagination behavior. Adequate, with clear 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 description coverage is 100% and only one parameter exists, so the schema already documents project_id. The description adds no extra meaning about the parameter (e.g., where to obtain the ID), so the 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?
States a specific verb ('List') and resource ('todo lists') scoped to 'a Basecamp 2 project'. It is distinguishable from siblings like list_todos, get_todolist, and create_todolist, though it does not explicitly call out the list-vs-item distinction.
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?
There is no guidance on when to use this tool versus alternatives such as list_todos or get_todolist, no prerequisites, and no exclusions. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all todos in a todo list
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID | |
| todolist_id | Yes | The todo list 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. "List all" implies a read operation and unbounded results, but it never states read-only semantics, pagination behavior, or that results are scoped to the given list — significant gaps for a tool with zero annotation coverage.
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 short sentence with no filler and the resource front-loaded. It is efficient, though its brevity contributes to the missing guidance rather than being purely economical.
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 two-parameter list tool with fully documented schema, the description is minimally sufficient. However, with no output schema it gives no hint about return shape, and it omits any usage context, so it is only 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 description coverage is 100%, so both project_id and todolist_id are already documented in the schema. The description's mention of "a todo list" loosely maps to todolist_id but adds no format or scoping detail beyond the schema, so the baseline of 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?
The description names a clear verb and resource ("List all todos in a todo list"), but it largely restates the tool name and adds little scope detail. It does not distinguish itself from siblings like get_todo or list_todolists, leaving the agent to infer the boundary.
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?
There is no guidance on when to use this versus get_todo, list_todolists, or other retrieval tools. The agent gets no conditions, prerequisites, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all topics (messages, forwards, etc.) in a Basecamp 2 project
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavior burden, and it does add real domain semantics by clarifying that 'topics' encompasses messages and forwards (not just messages). However it says nothing about result volume, pagination, ordering, or permissions, which matters for a list endpoint over an entire project.
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?
One short, front-loaded sentence with the scope constraint at the end and no wasted words. It is arguably terse, but nothing extraneous is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter list tool with no output schema, the definition covers what the agent needs to invoke it. Minor gaps remain around pagination/result handling and whether archived topics are included.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter is fully documented in the schema (100% coverage), so the baseline is 3. The description only loosely ties project_id to 'a Basecamp 2 project' and adds no format or ID-sourcing guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (List) plus resource (topics) scoped to a Basecamp 2 project, with a parenthetical that defines what a 'topic' actually is (messages, forwards, etc.). This clearly separates it from siblings like get_message or list_todos, though it doesn't explicitly name a competing tool.
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?
Usage is only implied by the scoping phrase 'in a Basecamp 2 project' — the agent can infer it needs a project_id and that this is the project-wide topic feed. There is no explicit when-to-use, when-not-to-use, or alternative tool named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing todo item
| Name | Required | Description | Default |
|---|---|---|---|
| due_on | No | New due date in YYYY-MM-DD format | |
| content | No | New text content | |
| todo_id | Yes | The todo ID | |
| project_id | Yes | The project ID | |
| assignee_id | No | New assignee person ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It says only 'Update an existing todo item,' omitting whether updates are partial or full, which permissions are required, whether omitted fields are preserved, or what is returned. For a mutation tool with no annotations, this is effectively no behavioral disclosure.
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 single sentence is front-loaded and free of filler, but for a five-parameter mutation tool with no annotations the extreme brevity is under-specification rather than conciseness. It does not provide enough information to be appropriately sized.
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?
There is no output schema and no annotations, and the description does not explain partial-update semantics or return behavior. Although the input schema documents parameters, the definition leaves key operational context missing for an update operation.
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%, with each of the five parameters documented in the input schema. The description adds no parameter-level meaning, but the baseline score of 3 applies because the schema already carries the semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (update) and resource (todo item) and notes the item must already exist. However, it does not differentiate from siblings like complete_todo, delete_todo, or create_todo, so an agent cannot tell from the description alone when to choose this tool over those alternatives.
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 when-to-use guidance, no named alternatives, and no exclusions. The description implies only that it modifies an existing todo, but does not say when to use update_todo rather than complete_todo or create_todo.
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.
v1.0.4complete_todocreate_messagecreate_todocreate_todolistdelete_todoget_meget_messageget_personget_projectget_todoget_todolistlist_peoplelist_projectslist_todolistslist_todoslist_topicsupdate_todoScored across 17 tools
Most tools target distinct resource+action pairs (todo, todolist, project, person, message). Minor overlap exists between list_topics and get_message/create_message since messages are a subset of topics, and get_me vs get_person/list_people could momentarily confuse, but overall boundaries are clear.
Every tool follows a consistent verb_noun snake_case pattern: list_x, get_x, create_x, update_x, complete_x, delete_x. Even get_me fits the convention, making the set highly predictable.
17 tools is slightly heavy but well-scoped across five resources (projects, todolists, todos, messages, people). Each tool earns its place, with no obviously redundant entries.
Todos have full lifecycle (create/get/list/update/complete/delete), but todolists lack update/delete, messages lack update/delete (and only list_topics surfaces them), and projects lack create/update/delete. These notable gaps leave dead ends for common management workflows.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
Connects AI assistants to QCDatabase.AI for everyday construction quality-control work.
Connect AI assistants to HiveClaw — manage projects, talk to AI agents, and more.
