Click on "Install 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., "@Donetick MCP Server show my chores for today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for Donetick chores management. Enables Claude and other MCP-compatible AI assistants to interact with your Donetick instance through a rate-limited API.
16 MCP Tools: Complete chore management (list, get, create, complete, update, delete, skip), label organization (list, create, update, delete), circle member information, user management (list circle users, get user profile)
Full API Integration: Uses Donetick Full API (/api/v1/) with all endpoints properly configured with trailing slashes
Complete Field Support: All 26+ chore creation fields working including frequency metadata, rolling schedules, multiple assignees, assignment strategies, notifications, labels, priority, points, sub-tasks, and more
Consistent Field Casing: camelCase fields throughout (name, description, dueDate, createdBy, etc.)
Specialized Update Tools: Update chore details, priority, and assignee with dedicated endpoints
JWT Authentication: Automatic token management with transparent refresh
Smart Caching: Intelligent caching for get_chore operations (60s TTL by default)
Rate Limiting: Token bucket algorithm prevents API overload
Retry Logic: Exponential backoff with jitter for resilient operations
Async/Await: Non-blocking operations using httpx
Input Validation: Pydantic field validators with sanitization
Security Hardened: HTTPS enforcement, sanitized logging, secure error messages, JWT token security
Docker Support: Containerized deployment with security best practices
Comprehensive Testing: Mocked unit/integration tests + live API test framework with pytest
Type Safety: Pydantic models for request/response validation
Related MCP server: donetick-mcp
Easiest installation (Claude Code CLI):
claude mcp add donetick uvx donetick-mcp-server@latestThen configure your Donetick credentials when prompted.
Or install manually with uvx:
# Install uv (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Add to Claude Desktop config
# ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"donetick": {
"command": "uvx",
"args": ["--refresh", "donetick-mcp-server"],
"env": {
"DONETICK_BASE_URL": "https://your-instance.com",
"DONETICK_USERNAME": "your_username",
"DONETICK_PASSWORD": "your_password"
}
}
}
}Benefits:
✅ No installation required - runs directly from PyPI
✅ Auto-updates with --refresh flag
✅ Isolated environment - no conflicts
✅ Works on Windows, macOS, Linux
Donetick instance (self-hosted or cloud)
Donetick account credentials (username and password)
For uvx method: uv installed (see Quick Start)
For other methods: Python 3.11 or higher
See Quick Start above.
The --refresh flag ensures you always get the latest version when Claude Desktop restarts.
Clone the repository:
git clone https://github.com/jason1365/donetick-mcp-server.git
cd donetick-mcp-serverCreate .env file:
cp .env.example .env
# Edit .env with your configurationConfigure environment variables:
DONETICK_BASE_URL=https://your-instance.com
DONETICK_USERNAME=your_username
DONETICK_PASSWORD=your_password
LOG_LEVEL=INFOBuild and run:
docker-compose build
docker-compose up -dIf you want to install globally or in a virtual environment:
# Install from PyPI
pip install donetick-mcp-server
# Or install for development
git clone https://github.com/jason1365/donetick-mcp-server.git
cd donetick-mcp-server
pip install -e .
# Run the server
donetick-mcp-server
# Or: python -m donetick_mcp.serverThen configure Claude Desktop to use the installed command:
{
"mcpServers": {
"donetick": {
"command": "donetick-mcp-server",
"env": {
"DONETICK_BASE_URL": "https://your-instance.com",
"DONETICK_USERNAME": "your_username",
"DONETICK_PASSWORD": "your_password"
}
}
}
}The MCP server uses JWT-based authentication with your Donetick credentials.
What You Need:
Your Donetick username (same as web login)
Your Donetick password (same as web login)
How It Works:
Server logs in with your credentials on startup
JWT token received and stored in memory
Token automatically refreshed before expiration
No manual token management required
Security:
Credentials stored only in environment variables or .env file
JWT tokens kept in memory only (never persisted to disk)
Automatic token refresh prevents session expiration
HTTPS required for all connections
Easiest Method - Claude Code CLI:
claude mcp add donetick uvx donetick-mcp-server@latestOr manually edit the configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"donetick": {
"command": "uvx",
"args": ["--refresh", "donetick-mcp-server"],
"env": {
"DONETICK_BASE_URL": "https://your-instance.com",
"DONETICK_USERNAME": "your_username",
"DONETICK_PASSWORD": "your_password"
}
}
}
}Note: The --refresh flag automatically updates to the latest version.
{
"mcpServers": {
"donetick": {
"command": "docker",
"args": [
"exec",
"-i",
"donetick-mcp-server",
"python",
"-m",
"donetick_mcp.server"
]
}
}
}{
"mcpServers": {
"donetick": {
"command": "donetick-mcp-server",
"env": {
"DONETICK_BASE_URL": "https://your-instance.com",
"DONETICK_USERNAME": "your_username",
"DONETICK_PASSWORD": "your_password"
}
}
}
}After updating the configuration, restart Claude Desktop.
List all chores with optional filtering.
Parameters:
filter_active (boolean, optional): Filter by active status
assigned_to_user_id (integer, optional): Filter by assigned user ID
Example:
List all active chores assigned to meGet details of a specific chore by ID.
Parameters:
chore_id (integer, required): The chore ID
Example:
Show me details of chore 123Create a new chore with full configuration support.
Basic Parameters:
name (string, required): Chore name (1-200 characters)
description (string, optional): Chore description (max 5000 characters)
due_date (string, optional): Due date in YYYY-MM-DD or RFC3339 format
created_by (integer, optional): Creator user ID
Recurrence/Frequency Parameters:
frequency_type (string, optional): How often chore repeats - "once", "daily", "weekly", "monthly", "yearly", "interval_based" (default: "once")
frequency (integer, optional): Frequency multiplier, e.g., 1=weekly, 2=biweekly (default: 1)
frequency_metadata (object, optional): Additional frequency config like {"days": [1,3,5], "time": "09:00"}
is_rolling (boolean, optional): Rolling schedule (next due based on completion) vs fixed (default: false)
User Assignment Parameters:
assigned_to (integer, optional): Primary assigned user ID
assignees (array, optional): Multiple assignees as [{"userId": 1}, {"userId": 2}]
assign_strategy (string, optional): Assignment strategy - "least_completed", "round_robin", "random" (default: "least_completed")
Notification Parameters:
notification (boolean, optional): Enable notifications (default: false)
nagging (boolean, optional): Enable nagging/reminder notifications (default: false)
predue (boolean, optional): Enable pre-due date notifications (default: false)
Organization Parameters:
priority (integer, optional): Priority level 1-5 (1=lowest, 5=highest)
labels (array, optional): Label tags like ["cleaning", "outdoor"]
Status Parameters:
is_active (boolean, optional): Active status - inactive chores are hidden (default: true)
is_private (boolean, optional): Private chore visible only to creator (default: false)
Gamification Parameters:
points (integer, optional): Points awarded for completion
Advanced Parameters:
sub_tasks (array, optional): Sub-tasks/checklist items
Examples:
Create a simple one-time chore:
Create a chore called "Take out trash" due on 2025-11-10
Create a recurring chore with notifications:
Create a weekly chore "Clean kitchen" every Monday at 9am with priority 4,
enable nagging notifications, and assign it to user 1
Create an advanced chore:
Create a chore "Grocery shopping" that repeats weekly on Mondays and Wednesdays,
assign to users 1 and 2 using round robin strategy, with priority 3,
labels "shopping" and "outdoor", and award 10 pointsMark a chore as complete.
Parameters:
chore_id (integer, required): The chore ID
completed_by (integer, optional): User ID who completed it
Example:
Mark chore 123 as completeDelete a chore permanently. Only the creator can delete.
Parameters:
chore_id (integer, required): The chore ID
Example:
Delete chore 123Get all members in your circle (household/team). Shows who you can assign chores to.
Parameters: None
Returns:
User ID
Username
Display name
Role (admin/member)
Active status
Points and redeemed points
Example:
Show me who's in my household
Who can I assign chores to?
List all circle membersVariable | Required | Default | Description |
| Yes | - | Your Donetick instance URL (must use HTTPS) |
| Yes | - | Your Donetick username |
| Yes | - | Your Donetick password |
| No | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
| No | 10.0 | Requests per second limit |
| No | 10 | Maximum burst size |
The server implements a token bucket rate limiter to prevent API overload:
Default: 10 requests per second with burst capacity of 10
Conservative: Starts conservative and can be increased based on your Donetick instance
Respects 429: Automatically backs off when rate limited by the API
Exponential backoff with jitter for transient failures
Maximum 3 retries for most operations
Smart retry: Only retries on 5xx errors and 429 (rate limit)
No retry on 4xx: Client errors fail immediately (except 429)
Mocked Tests (fast, no Donetick instance required):
# Install dev dependencies
pip install -e ".[dev]"
# Run all tests (unit + integration with mocks)
pytest
# Run with coverage
pytest --cov=donetick_mcp --cov-report=html
# Run specific test file
pytest tests/test_client.py
pytest tests/test_server.py
# Run with verbose output
pytest -vLive API Tests (requires Donetick instance):
# Create .env file with credentials (see Configuration section)
# Then run live API integration tests
pytest tests/integration/test_live_api.py -v
# Skip live tests
pytest -m "not live_api"
# Run only live tests
pytest -m live_apiTest Coverage Details:
Mocked tests validate logic, retry behavior, rate limiting, error handling
Live API tests verify endpoint routing, field casing compatibility, response formats
Full coverage ensures both API client reliability and MCP tool correctness
donetick-mcp-server/
├── src/donetick_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server implementation
│ ├── client.py # Donetick API client
│ ├── models.py # Pydantic data models
│ └── config.py # Configuration management
├── tests/
│ ├── test_client.py # API client tests
│ └── test_server.py # MCP server tests
├── tmp/ # Temporary files (gitignored)
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.mdNote: The tmp/ directory is used for temporary test scripts and analysis files during development. It's gitignored and not included in releases.
This server uses the Donetick Full API (/api/v1/) with JWT authentication.
Donetick Docs: https://docs.donetick.com/
Donetick GitHub: https://github.com/donetick/donetick
Endpoints Used:
List Chores: GET /api/v1/chores/ (requires trailing slash)
Get Chore: GET /api/v1/chores/{id} (includes sub-tasks)
Create Chore: POST /api/v1/chores/
Update Chore: PUT /api/v1/chores/{id} (name, description, nextDueDate)
Update Priority: PUT /api/v1/chores/{id}/priority
Update Assignee: PUT /api/v1/chores/{id}/assignee
Skip Chore: PUT /api/v1/chores/{id}/skip
Complete Chore: POST /api/v1/chores/{id}/do
Delete Chore: DELETE /api/v1/chores/{id}
Get Members: GET /api/v1/circles/members/ (requires trailing slash)
Important: List endpoints require trailing slashes (/api/v1/chores/, /api/v1/circles/members/). This is handled automatically by the client.
Full API Used: Not the external API (eAPI) - uses internal Full API
Field Casing: Consistent camelCase throughout (name, description, dueDate, createdBy)
Trailing Slashes: List endpoints include trailing slashes for proper routing
Authentication: JWT Bearer tokens with automatic management
Complete Feature Support: All 26+ chore creation fields available
Automatic Token Refresh: JWT tokens refreshed transparently
Circle Scoped: All operations scoped to your circle (household/team)
No Premium Restrictions: All features available through full API
"DONETICK_BASE_URL environment variable is required"
Make sure your .env file exists and is properly formatted
For Docker: ensure environment variables are passed in docker-compose.yml
"Rate limited, waiting..."
The server is respecting API rate limits
Consider reducing RATE_LIMIT_PER_SECOND if this happens frequently
"Connection refused" or timeout errors
Verify your Donetick instance URL is correct
Check that your Donetick instance is accessible
Ensure firewall rules allow outbound connections
"401 Unauthorized" or "Invalid credentials"
Verify your username and password are correct
Check that your account is not locked or disabled
Ensure you can login to Donetick web interface with the same credentials
Check for typos in environment variables
Tools not showing in Claude
Restart Claude Desktop after configuration changes
Check Claude Desktop logs for errors
Verify the configuration file path is correct
Enable debug logging:
export LOG_LEVEL=DEBUGOr in Docker:
environment:
- LOG_LEVEL=DEBUGView Docker logs:
docker-compose logs -f donetick-mcpCredentials: Never commit credentials to version control (use .env file)
JWT Tokens: Stored in memory only, never persisted to disk
Automatic Token Refresh: Prevents session expiration without user intervention
Docker Isolation: Runs as non-root user in container
Resource Limits: Memory and CPU limits prevent resource exhaustion
Input Validation: Pydantic models validate all inputs
HTTPS Required: Server enforces HTTPS for all Donetick connections
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request
MIT License - see LICENSE file for details
Donetick - Open source chores management
Model Context Protocol - MCP specification
Anthropic - MCP SDK and Claude
Issues: https://github.com/jason1365/donetick-mcp-server/issues
Donetick Docs: https://docs.donetick.com
MCP Docs: https://modelcontextprotocol.io
Built with ❤️ for the Donetick and MCP communities
Mark a chore as complete. Optionally specify which user completed the chore. Returns the updated chore with completion timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| chore_id | Yes | The ID of the chore to mark complete | |
| completed_by | No | User ID who completed the chore (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the return value (updated chore with timestamp) and optional user specification, but does not mention potential side effects, reversibility, or error conditions (e.g., invalid chore_id). Adequate but could be more thorough.
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 clear sentences with no wasted words. Front-loaded with the core action and includes optional details efficiently.
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 no output schema and no annotations, the description covers the basic functionality and return value. However, it omits error handling, non-idempotency note, or confirmation of success. Moderately complete for a simple mutation.
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 minimal extra meaning: 'Optionally specify which user completed the chore' for 'completed_by', but does not elaborate on constraints or behavior beyond what 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 clearly states the tool's purpose: 'Mark a chore as complete.' It also specifies optional user input and return value, distinguishing it from sibling tools like 'skip_chore' or 'update_chore'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when you want to mark a chore complete) but lacks explicit context about when not to use or alternatives (e.g., 'skip_chore' for skipping). No exclusions or usage guidance beyond the basic action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new chore in Donetick with easy natural language inputs. Use simple parameters like usernames, days_of_week, and time_of_day - they're automatically transformed to the correct API format.
EXAMPLES:
Simple recurring chore: {name: 'Take out trash', days_of_week: ['Mon', 'Thu'], time_of_day: '19:00', usernames: ['Alice']}
Weekly chore with reminders: {name: 'Team meeting', days_of_week: ['Tue'], time_of_day: '14:00', remind_minutes_before: 15, usernames: ['Alice', 'Bob']}
With subtasks and labels: {name: 'Weekly review', days_of_week: ['Fri'], time_of_day: '17:00', subtask_names: ['Check email', 'Update notes'], label_names: ['work', 'weekly']}
Daily chore with points: {name: 'Exercise', frequency_type: 'daily', time_of_day: '07:00', points: 10, usernames: ['Bob']}
One-time chore: {name: 'Fix leaky faucet', due_date: '2025-11-10', priority: 5, usernames: ['Alice']}
Returns the created chore with its assigned ID and all metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Chore name (required, 1-200 characters) | |
| description | No | Chore description (optional, max 5000 characters) | |
| due_date | No | Due date in YYYY-MM-DD or RFC3339 format (optional) | |
| created_by | No | User ID of the creator (optional) | |
| frequency_type | No | How often the chore repeats (default: once). FREQUENCY TYPES: • once / no_repeat: One-time chore, no recurrence • daily: Repeats every day at specified time • weekly: Repeats every week (use with frequency for bi-weekly: frequency=2) • days_of_the_week: Specific days (Mon, Wed, Fri) - BEST for multiple days/week → Use with days_of_week parameter: ['Mon', 'Wed', 'Fri'] • monthly: Repeats every month • yearly: Repeats every year • day_of_the_month: Specific day of month (e.g., 15th of each month) • interval_based / interval: Custom interval (e.g., every N days) • adaptive: Smart scheduling based on completion patterns • trigger: Triggered by events or conditions TIP: For chores on specific days (Mon/Wed/Fri), use frequency_type='days_of_the_week' with days_of_week=['Mon', 'Wed', 'Fri'] instead of frequency_type='weekly' | |
| frequency | No | Frequency multiplier (e.g., 1=weekly, 2=biweekly, default: 1) | |
| frequency_metadata | No | Additional frequency config (e.g., {"days": [1,3,5], "time": "09:00"}) | |
| is_rolling | No | Rolling schedule (next due based on completion) vs fixed (default: false) | |
| assigned_to | No | Primary assigned user ID (optional) | |
| assignees | No | Multiple assignees as array of {"userId": int} objects | |
| assign_strategy | No | Assignment strategy: least_completed, least_assigned, round_robin, random, keep_last_assigned, random_except_last_assigned, no_assignee (default: least_completed) | |
| notification | No | Enable notifications for this chore (default: false) | |
| nagging | No | Enable nagging/reminder notifications (default: false) | |
| predue | No | Enable pre-due date notifications (default: false) | |
| priority | No | Priority level: 0=unset, 1=lowest, 2=low, 3=medium, 4=highest (optional) | |
| labels | No | Label tags for categorization (e.g., ["cleaning", "outdoor"]) | |
| is_active | No | Active status - inactive chores are hidden (default: true) | |
| is_private | No | Private chore visible only to creator (default: false) | |
| points | No | Points awarded for completion (optional) | |
| sub_tasks | No | Sub-tasks/checklist items (optional) | |
| usernames | No | EASY: Assign by usernames instead of IDs (e.g., ['Alice', 'Bob']). First user becomes primary assignee. | |
| label_names | No | EASY: Label by names instead of IDs (e.g., ['cleaning', 'urgent']) | |
| days_of_week | No | EASY: Days as short names (e.g., ['Mon', 'Wed', 'Fri'] or ['monday', 'wednesday']). Auto-sets frequency_type to days_of_the_week. REQUIRED when frequency_type='days_of_the_week'. Valid values: Mon/Monday, Tue/Tuesday, Wed/Wednesday, Thu/Thursday, Fri/Friday, Sat/Saturday, Sun/Sunday | |
| time_of_day | No | EASY: Time in HH:MM format (e.g., '16:00' for 4pm) | |
| timezone | No | Timezone name (default: America/New_York). Used with days_of_week and time_of_day. | |
| remind_minutes_before | No | EASY: Remind X minutes before due time (e.g., 15 for 15 minutes before) | |
| remind_at_due_time | No | EASY: Also remind exactly at due time (default: false) | |
| enable_nagging | No | EASY: Enable nagging notifications - repeated reminders if not completed (default: false) | |
| enable_predue | No | EASY: Enable pre-due notifications - reminders before due date arrives (default: false) | |
| subtask_names | No | EASY: Subtask names as simple strings (e.g., ['Do homework', 'Check work']) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses automatic transformation of parameters and mentions return type, though it could discuss error handling or authorization requirements.
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 front-loaded with purpose and key concepts, followed by clear examples. Every sentence adds value, and the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 30 parameters and no output schema, the description covers core behavior and return format well. However, it could be more complete by mentioning validation or prerequisites.
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%, but the description adds significant value by grouping 'EASY' parameters, explaining automatic transformations, and providing tips for frequency_type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new chore' and provides examples. It distinguishes from sibling tools like update_chore and delete_chore by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains usage through examples and parameter explanations, but does not explicitly state when not to use this tool or recommend alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new label for organizing chores. Labels help categorize and filter chores by type, location, or any custom criteria. Optionally specify a color in hex format (e.g., '#FF5733').
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Label name (required) | |
| color | No | Label color in hex format (e.g., '#80d8ff'), optional |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should fully disclose behavior. It states creation but omits details like duplicate handling, validation, error scenarios, or idempotency. The description is too brief for a create 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?
Two concise sentences: first states purpose, second adds usage context and optional parameter. No redundant or unnecessary 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?
Suitable for a simple tool with two parameters and no output schema. However, it could briefly mention return behavior (e.g., whether it returns the created label). Currently omits success outcomes.
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 both parameters. The description adds 'Optionally specify a color in hex format' which aligns with the schema, providing no additional value beyond what the schema already conveys.
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 the verb 'Create' and the resource 'a new label for organizing chores'. Differentiates from siblings like 'update_label' and 'delete_label'.
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?
Explains that labels help categorize and filter chores, providing context for when to create a label. Does not explicitly mention when not to use or alternatives, but the purpose is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a chore permanently. Note: Only the chore creator can delete a chore. Returns confirmation of deletion.
| Name | Required | Description | Default |
|---|---|---|---|
| chore_id | Yes | The ID of the chore to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the destructive nature ('permanently'), authorization requirement ('only chore creator'), and return value ('confirmation of deletion'). This is sufficient for a simple delete 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?
Two sentences, no unnecessary words, critical information front-loaded. Perfectly concise.
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 description covers all core aspects: action, permanence, authorization, and return. While it could mention error cases (e.g., chore not found), it is adequate for a simple tool without output schema or annotations.
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 'chore_id' is fully described in the schema. The description adds no further semantic meaning beyond what the schema already provides, which meets the baseline for 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'a chore', and specifies 'permanently' to indicate irreversibility. It effectively distinguishes from sibling tools like complete_chore (mark complete) or update_chore (modify fields).
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 note 'Only the chore creator can delete a chore' provides a key usage constraint. However, it lacks explicit comparison to alternatives like skip_chore or update_chore to explain when deletion is appropriate versus other modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a label permanently. This will remove the label from all chores that use it. Use with caution as this action cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| label_id | Yes | The ID of the label to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: permanent deletion, removal from all chores, and that it cannot be undone. With no annotations, this adequately conveys the destructive nature.
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, no unnecessary words, efficiently communicates the essential 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 single-parameter deletion tool with no output schema, the description covers all necessary aspects: action, consequence, and caution.
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 schema already describes the only parameter (label_id) as 'The ID of the label to delete' with 100% coverage; the description adds no further semantic value.
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 the action (delete), resource (label), and effect (permanent, removes from all chores). Distinguishes from sibling tools like update_label or create_label.
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?
Includes a caution about irreversibility but does not provide explicit guidance on when to use this tool over alternatives like update_label.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get completion history for all chores with pagination support. Returns completion records across all chores in the circle, showing who completed what and when. Use limit and offset for pagination through large result sets.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of history entries to return (default: 50, max: 200) | |
| offset | No | Number of entries to skip for pagination (default: 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description explains what is returned (who, what, when) implying read-only operation, but lacks details on edge cases, rate limits, or authentication needs.
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 efficient sentences with no redundancy; first states purpose and pagination, second explains return content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated history tool with no output schema, the description adequately explains return format, but could mention sorting or absence of filters.
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 clear parameter descriptions in the schema; description adds minimal value ('use limit and offset for pagination'), matching baseline for high 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?
Clearly states verb 'Get' and resource 'completion history for all chores', distinguishing it from sibling 'get_chore_history' which targets a single chore.
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 context for when to use (to get history for all chores) and explains pagination, but does not explicitly state when not to use or mention alternatives like 'get_chore_history'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific chore by its ID. Returns complete chore information including all metadata, assignees, labels, and scheduling details.
| Name | Required | Description | Default |
|---|---|---|---|
| chore_id | Yes | The ID of the chore to retrieve |
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 it returns information but does not disclose any behavioral traits such as authentication requirements, rate limits, 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?
Short and to the point, with one sentence. Could be slightly more structured but is not verbose.
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?
Adequate for a simple retrieval tool with one parameter and no output schema. However, missing usage context and differentiation from similar tools reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'chore_id' already described in the schema. The description adds 'by its ID', which is redundant but not harmful. No additional semantic value 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?
Clearly states the verb 'Get details' and the resource 'chore by its ID', and lists what is returned. However, there is a sibling tool 'get_chore_details' with a very similar name, and the description does not differentiate between them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'get_chore_details' or 'get_chore_history'. The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed chore information including completion statistics and analytics. Returns extended details not available in standard get_chore: total completion count, last completion date and user, average duration, and recent completion history. Useful for performance analysis and chore optimization.
| Name | Required | Description | Default |
|---|---|---|---|
| chore_id | Yes | The ID of the chore to fetch detailed statistics for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It does not explicitly state the operation is read-only, but the name and description imply reads. No disclosure of authorization, rate limits, or side effects. Adequate but 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?
Two sentences, front-loaded with key action, no fluff. Efficiently conveys purpose, content, and typical use case.
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 retrieval tool with one parameter and no output schema, the description adequately explains what it returns (specific statistics like total completion count, last date, etc.). Lacks coverage on error handling or prerequisites, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema's 'The ID of the chore to fetch detailed statistics for.' No format or constraints elaborated.
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 'Get detailed chore information including completion statistics and analytics.' Distinguishes from sibling 'get_chore' by specifying it returns extended details not available in the standard version, listing specific fields like total completion count, last completion date, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides usage context: 'Useful for performance analysis and chore optimization.' Implicitly contrasts with 'get_chore' for when basic info suffices, but lacks explicit 'when not to use' or alternative tool names beyond the sibling mention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get completion history for a specific chore. Returns all completion records including when the chore was completed, by whom, completion notes, and points awarded. Useful for tracking chore completion patterns and accountability.
| Name | Required | Description | Default |
|---|---|---|---|
| chore_id | Yes | The ID of the chore to fetch history for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior. It states the tool returns completion records with specific fields, which is basic. However, it omits details about error handling, authentication requirements, rate limits, or what happens for invalid chore IDs. The description is 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?
The description is two sentences long with no unnecessary words. The first sentence front-loads the core purpose, and the second sentence adds value by listing return fields and usage context. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain return values, which it does (records include time, person, notes, points). However, it does not mention result ordering, pagination, or limits. For a history tool with 18 siblings, additional context (e.g., 'returns newest first') would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'chore_id', is already well-described in the schema ('The ID of the chore to fetch history for'). With 100% schema coverage, the description adds no additional meaning beyond emphasizing 'specific chore', which is marginal. 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?
Description starts with a specific verb ('Get completion history for a specific chore') and clearly distinguishes the tool from siblings like 'get_all_chores_history' by specifying 'specific chore'. It lists key return fields (when completed, by whom, notes, points), providing strong purpose clarity.
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 notes the tool is 'useful for tracking chore completion patterns and accountability,' which implies usage context but does not explicitly state when to use this tool over alternatives (e.g., 'get_chore' or 'get_chore_details'). No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all members in the circle (household/team). Returns user information including user IDs, usernames, display names, roles (admin/member), active status, and points. Use this to see who you can assign chores to.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It describes return data but does not disclose behavioral aspects like auth requirements, ordering, or whether the list is live or cached.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Front-loaded with purpose, then output details, then usage hint.
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 no output schema, the description lists key return fields. It is adequate for a simple list retrieval, though could mention scope (current circle) more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in the input schema, so the description need not add parameter information. Baseline of 4 is appropriate as the description is not missing anything 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?
The description clearly states it returns all members in a circle with specific user information. However, it does not differentiate from the sibling tool 'list_circle_users' which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Use this to see who you can assign chores to.' No negative guidance or alternatives mentioned, but the use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current user's detailed profile information. Returns comprehensive user data including notification preferences, webhook configuration, storage usage, points, and account metadata. Use this to view or manage personal settings and statistics.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return data comprehensively (notification preferences, webhook, storage, etc.) but does not mention safety (read-only) or potential side effects. No annotations provided, so description partly compensates.
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 efficient sentences. First states purpose, second lists contents and usage. 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?
Simple tool with no params and no output schema. Description lists key return fields, providing sufficient context. Could be more complete by noting it is for the authenticated user only.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0 parameters. Description correctly adds no parameter info; baseline of 4 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?
Specific verb 'Get' and resource 'current user's detailed profile information'. Clearly distinct from sibling tools which focus on chores, labels, and circles.
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?
States 'use this to view or manage personal settings' but lacks explicit when-not or alternatives. No guidance on context where this tool is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all chores from Donetick. Optionally filter by active status or assigned user. Returns comprehensive chore details including name, description, due dates, assignees, and status. Use detail_level to control response size: 'brief' for essential fields only, 'full' for complete details (default).
| Name | Required | Description | Default |
|---|---|---|---|
| filter_active | No | Filter by active status (true=active only, false=inactive only, null=all) | |
| assigned_to_user_id | No | Filter by assigned user ID (null=all users) | |
| detail_level | No | Response format: 'brief' (id, name, status, assignee, dueDate) or 'full' (all fields). Default: 'full' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context about return fields and detail_level behavior beyond schema. However, with no annotations, it omits authorization needs and other behavioral traits. 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 concise sentences covering purpose, options, and detail_level behavior. No unnecessary 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?
Covers key aspects: listing, filters, fields returned, and detail_level. No output schema, but description plus schema together provide sufficient completeness. Missing potential details like pagination or ordering, but acceptable.
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. Description adds clarifying context: default for detail_level, purpose of filters. Enhances understanding 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?
Explicit verb 'List' and resource 'chores' with scope 'all'. Distinguishes from sibling tools like get_chore (singular) and complete_chore (action).
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 context for using filters and detail_level. Does not explicitly state when not to use or mention alternatives, but sibling names imply singular use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all users in the circle with basic information. Returns user IDs, usernames, display names, email addresses, roles, points earned, and active status. Similar to get_circle_members but may include additional user details.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries burden. It states it lists users and returns fields, but omits permission requirements or side effects. Adequate for a read-only list.
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 action, lists fields, efficient comparison. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main purpose and return fields well. Lacks details like pagination, ordering, or access requirements, but acceptable for simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema; per rules baseline is 4. Description adds no param info, which is acceptable.
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 'List' with specific resource 'circle users' and enumerates returned fields. Explicitly differentiates from sibling 'get_circle_members'.
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 sibling comparison to help choose between tools, but lacks explicit when-not-to-use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all labels in the circle. Returns all available labels with their IDs, names, and colors. Use these labels to organize and categorize chores.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It accurately describes the tool as a read operation with no side effects, listing returned fields. This is sufficient for a simple list tool with no parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences efficiently convey action, output, and purpose with no redundancy or 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 tool with zero parameters and no output schema, the description is complete: it specifies the resource (labels in the circle), the fields returned (IDs, names, colors), and the intended use. No missing information is apparent.
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 are no parameters, so the baseline is 4. The description does not need to add parameter details; it correctly implies no inputs are needed to retrieve the list.
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 all labels'), the scope ('in the circle'), and what is returned (IDs, names, colors). The verb matches the tool name, and it is distinct from siblings which involve creation, update, or deletion.
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 suggests when to use this tool ('to organize and categorize chores') but does not explicitly state when not to use it or mention alternatives. For a simple read tool, this is adequate but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Skip a chore without marking it complete. For recurring chores, this schedules the next occurrence without completing the current one. Useful for chores that aren't needed this cycle. One-time chores will be marked as inactive. Returns the updated chore with the new due date.
| Name | Required | Description | Default |
|---|---|---|---|
| chore_id | Yes | The ID of the chore to skip |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses behavior for recurring (schedules next occurrence) and one-time chores (marks inactive) without claiming destructive effects. Adds value beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each providing essential information: main action, recurring behavior, one-time behavior, and return note. No redundancy or waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers core behavior adequately, including edge cases (recurring vs one-time). Could mention return format but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (chore_id) with 100% schema coverage. Description does not add additional meaning beyond the schema's description. 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?
Clearly states 'Skip a chore without marking it complete,' and distinguishes from sibling 'complete_chore' by explaining behavior for recurring chores (schedules next occurrence without completing) vs one-time chores (marks inactive).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Useful for chores that aren't needed this cycle,' providing context for when to use. Does not list alternatives or when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing chore with new values. Can modify any chore property including name, description, schedule, assignees, priority, points, labels, privacy settings, and more. Only provide fields you want to change - other fields remain unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| chore_id | Yes | The ID of the chore to update | |
| name | No | New chore name | |
| description | No | New chore description | |
| nextDueDate | No | New due date (ISO 8601 format, e.g., '2025-11-17') | |
| priority | No | Priority level (0=unset, 1=lowest, 4=highest) | |
| points | No | Points awarded for completion | |
| isActive | No | Enable/disable chore | |
| isPrivate | No | Hide from other circle members | |
| requireApproval | No | Requires approval to mark complete | |
| frequencyType | No | Frequency type (once, daily, weekly, monthly, yearly, days_of_the_week) | |
| frequency | No | Frequency value (e.g., 2 for every 2 weeks) | |
| frequencyMetadata | No | Frequency metadata with days, time, timezone, weekPattern | |
| isRolling | No | Rolling schedule (based on completion) vs fixed schedule | |
| assignStrategy | No | Assignment rotation strategy | |
| notification | No | Enable notifications | |
| notificationMetadata | No | Notification settings (templates, nagging, predue) | |
| completionWindow | No | SECONDS before due time when early completion is allowed | |
| deadlineOffset | No | SECONDS after due time for grace period |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It confirms the tool mutates data and preserves untracked fields, but lacks details on authorization, rate limits, error handling, or outcomes when the chore does not exist. Minimal transparency for a mutation tool with many parameters.
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 just two sentences: a clear purpose statement followed by a concise usage note. No unnecessary words, front-loaded with the primary action.
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 18 parameters (including nested objects) and no output schema, the description is somewhat brief. It covers the basic idea of partial updates, but does not explain return values, validation rules, or error scenarios. Lacks completeness for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description's contribution is limited. It lists example properties (name, description, schedule, etc.) but adds no new semantic meaning beyond the schema. The partial update guideline is more about usage than parameters. 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?
The description clearly states the tool's purpose: 'Update an existing chore with new values.' It specifies the verb 'update' and the resource 'chore,' and distinguishes this from sibling tools like create_chore or delete_chore by focusing on modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises partial updates ('Only provide fields you want to change'), which is helpful, but it does not guide when to use this tool versus more specific update tools like update_chore_assignee or update_chore_priority. No explicit when-not-to-use or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reassign a chore to a different circle member. Use this to dynamically change who is responsible for a chore. Get member IDs from list_circle_members or get_circle_members. Returns the updated chore.
| Name | Required | Description | Default |
|---|---|---|---|
| chore_id | Yes | The ID of the chore to update | |
| user_id | Yes | User ID of the new assignee (from list_circle_members) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states the return value ('Returns the updated chore') but does not disclose potential side effects (e.g., notifications), permissions needed, or whether other fields are affected. This is 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?
The description is very concise with four short sentences, each providing distinct and necessary information: action, usage, prerequisite, and return. No redundant or extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (2 parameters, no output schema), the description covers purpose, prerequisite for user_id, and return value. It does not mention error handling or validation, but this is acceptable for a straightforward update action.
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?
Both parameters have schema descriptions, achieving 100% coverage. The description adds value by specifying where to get user_id ('from list_circle_members or get_circle_members'), enhancing the schema's default explanation.
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 ('Reassign a chore to a different circle member') and the resource (chore). It effectively distinguishes from sibling tools like 'update_chore' by specifying the exact purpose of changing assignee.
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 tells when to use the tool ('dynamically change who is responsible') and provides a prerequisite ('Get member IDs from list_circle_members or get_circle_members'). It does not explicitly state when not to use it or contrast with alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a chore's priority level (0-4). Use this to adjust how urgent a chore is without editing other details. 0=unset, 1=lowest, 2=low, 3=medium, 4=highest. Returns the updated chore.
| Name | Required | Description | Default |
|---|---|---|---|
| chore_id | Yes | The ID of the chore to update | |
| priority | Yes | New priority level (0=unset, 1=lowest, 4=highest) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the priority scale meanings and that the tool returns the updated chore. However, it omits details like whether the action is destructive, reversible, or requires permissions. For a simple update, it is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: action, usage guidance, and parameter details. No filler, front-loaded with the core purpose. Every sentence serves a distinct function.
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 simplicity (2 params, no output schema, no annotations), the description covers the core functionality and return value. It lacks error conditions or authentication notes, but is sufficient for a targeted update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are described in the schema (100% coverage), but the tool description adds value by fully defining the priority scale (0=unset, 1=lowest, 2=low, 3=medium, 4=highest), which the schema only partially covers. This helps the agent select the correct value.
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 verb 'Update' and the resource 'a chore's priority level (0-4)', distinguishing it from sibling tools like 'update_chore' and 'complete_chore' by specifying the exact parameter adjusted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to adjust how urgent a chore is without editing other details', providing clear when-to-use guidance. It implies when not to use (if other fields need editing), but does not explicitly state alternatives, though the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing label's name and/or color. Use this to rename labels or change their colors for better organization.
| Name | Required | Description | Default |
|---|---|---|---|
| label_id | Yes | The ID of the label to update | |
| name | Yes | New label name | |
| color | No | New label color in hex format (e.g., '#80d8ff'), optional |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It indicates mutation but does not disclose side effects (e.g., overwriting, error handling) or prerequisites. Adequate but could be more 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?
Two sentences, direct and front-loaded with the action. No extraneous information. Very concise.
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; description does not specify return value or error behavior. While the update action is simple, completeness could be improved by noting response type.
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 baseline is 3. Description mentions name and color but adds no new meaning beyond the schema. Does not elaborate on label_id or optionality details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool updates an existing label's name and/or color, with verb 'update' and specific fields. It distinguishes from sibling tools like create_label and delete_label.
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 says 'Use this to rename labels or change their colors for better organization,' providing clear usage context. It does not explicitly exclude other uses but is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a subtask as complete or incomplete within a chore. This allows tracking progress on chores with multiple steps without completing the entire chore. Useful for checklists and multi-step tasks. Returns the updated chore with subtask progress.
| Name | Required | Description | Default |
|---|---|---|---|
| chore_id | Yes | The ID of the chore containing the subtask | |
| subtask_id | Yes | The ID of the subtask to update | |
| completed | Yes | True to mark complete, False to mark incomplete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It discloses the action (mark complete/incomplete), that it does not complete the entire chore, and the return value (updated chore). However, it does not mention authorization, rate limits, or failure conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding essential value: purpose, use case, and return value. No wasted words. Front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, no output schema, no annotations), the description covers the key aspects: what it updates, why it's useful, and what it returns. It could mention potential errors or prerequisites but is sufficient 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 covers 100% of parameters with descriptions. The description adds context by explaining the progression functionality and tying the boolean parameter to the mark action. This goes beyond basic schema definitions.
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 ('Mark') and resource ('subtask'), clearly states updating completion status, and distinguishes from sibling 'complete_chore' which likely completes the entire chore. The phrase 'within a chore' clarifies the hierarchy.
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 says 'Useful for checklists and multi-step tasks' indicating when to use. However, it does not explicitly exclude use cases or mention when to prefer alternatives like 'complete_chore'.
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. Dates show when Glama detected each change.
v0.3.13complete_chorecreate_chorecreate_labeldelete_choredelete_labelget_all_chores_historyget_choreget_chore_detailsget_chore_historyget_circle_membersget_user_profilelist_choreslist_circle_userslist_labelsskip_choreupdate_choreupdate_chore_assigneeupdate_chore_priorityupdate_labelupdate_subtask_completionSignificant overlap exists: update_chore_assignee and update_chore_priority are redundant with the general update_chore tool, which can modify any property. Additionally, list_circle_users and get_circle_members have nearly identical purposes with only minor differences, causing ambiguity.
Tool names consistently follow a verb_noun snake_case pattern (e.g., create_chore, delete_label). The only minor inconsistency is mixing 'get' and 'list' prefixes for similar operations (get_circle_members vs list_circle_users), but overall the naming is predictable.
20 tools is well-scoped for a chore management system, covering all core operations without being excessive. Each tool serves a distinct function in the domain, and the count feels appropriate.
The tool set covers CRUD for chores and labels, completion tracking, history, and user management. Minor gaps include lack of a tool to update user profile settings or retrieve a single label by ID, but the core workflows are well-supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jason1365/donetick-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
