> ## Documentation Index > Fetch the complete documentation index at: https://docs.taketime.space/llms.txt > Use this file to discover all available pages before exploring further. # Take Time MCP Tools — Full Parameter and Return Reference > Complete reference for all 9 Take Time MCP tools — parameters, types, required fields, and return shapes for every read, write, and delete tool. The Take Time MCP Server exposes 9 tools across three categories: read tools that query your schedule, write tools that create and modify data, and a delete tool. Each tool maps directly to a REST API endpoint. You do not call these tools directly — your AI assistant invokes them automatically based on what you ask for in natural language. *** ## Read Tools Read tools retrieve data from your Take Time account without making any changes. Use these when you want to review your schedule, check your progress, or look up subjects. ### `list_blocks` Retrieve study blocks from your schedule with optional filters. Use this to see what's planned for a specific date, subject, or completion status. | Name | Type | Required | Description | | ------------ | ------- | -------- | ----------------------------------------------------------------------------------- | | `date` | string | No | Filter blocks to a single date in `YYYY-MM-DD` format. | | `date_from` | string | No | Start of a date range in `YYYY-MM-DD` format. Use with `date_to` to fetch a span. | | `date_to` | string | No | End of a date range in `YYYY-MM-DD` format. | | `subject_id` | string | No | Filter results to a specific subject by its ID. | | `done` | boolean | No | Pass `true` to return only completed blocks, or `false` for incomplete blocks only. | **Returns:** An array of block objects. Each block includes `id`, `subject_id`, `subject_name`, `date`, `start`, `end`, `topic`, and `done`. *** ### `list_subjects` List all activity profiles configured in your Take Time account. Subjects define the subjects, activities, and time slots that make up your schedule. | Name | Type | Required | Description | | ------ | ------ | -------- | -------------------------------------------------------------------------- | | `type` | string | No | Filter by activity type. Accepted values: `study`, `training`, `inactive`. | **Returns:** An array of subject objects. Each subject includes `id`, `name`, `type`, `color`, and a `slots` array describing its recurring time slots. *** ### `get_stats` Fetch completion statistics, your current streak, and the per-day activity heatmap for a given period. This is the same data that powers the progress view in the Take Time app. | Name | Type | Required | Description | | -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------- | | `period` | string | No | Time window to aggregate stats over. Accepted values: `today`, `week`, `month`, `all`. Defaults to `week`. | **Returns:** A stats object with the following fields: | Field | Type | Description | | ------------------ | ------ | -------------------------------------------------------------- | | `total_blocks` | number | Total scheduled blocks in the period. | | `completed_blocks` | number | Blocks marked as done. | | `completion_rate` | number | Ratio of completed to total, between `0` and `1`. | | `streak_days` | number | Current consecutive-day completion streak. | | `total_minutes` | number | Total study time from completed blocks, in minutes. | | `heatmap` | object | Map of `YYYY-MM-DD` date strings to integer completion counts. | *** ### `get_schedule` Retrieve the full weekly schedule for any week, including all blocks organized by day. Use a `week_offset` to look at past or future weeks. | Name | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------ | | `week_offset` | number | No | Week relative to the current one. `0` = this week, `-1` = last week, `1` = next week. Defaults to `0`. | **Returns:** A weekly schedule object with `week_start`, `week_end`, and a `days` array. Each day contains its `date`, `label`, and an array of `blocks`. *** ## Write Tools Write tools create or modify data in your Take Time account. Your AI assistant will typically confirm the details with you before calling a write tool, but you can also ask it to act immediately. ### `create_block` Schedule a new study block on a specific date and time. | Name | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------------------------------- | | `subject_id` | string | **Yes** | The ID of the subject this block belongs to. Use `list_subjects` to find subject IDs. | | `date` | string | **Yes** | The date for the block in `YYYY-MM-DD` format. | | `start` | string | **Yes** | Block start time in `HH:MM` 24-hour format, e.g. `"09:00"`. | | `end` | string | **Yes** | Block end time in `HH:MM` 24-hour format, e.g. `"10:30"`. | | `topic` | string | No | An optional note describing what you plan to cover in this session. | **Returns:** The newly created block object including its assigned `id`. *** ### `update_block` Modify an existing study block. Use this to reschedule a block, update its topic, or mark it as done. | Name | Type | Required | Description | | ------------ | ------- | -------- | -------------------------------------------- | | `block_id` | string | **Yes** | The ID of the block to update. | | `subject_id` | string | No | Reassign the block to a different subject. | | `start` | string | No | New start time in `HH:MM` format. | | `end` | string | No | New end time in `HH:MM` format. | | `done` | boolean | No | Pass `true` to mark the block as completed. | | `topic` | string | No | Update or add a topic note for this session. | **Returns:** The updated block object reflecting all applied changes. *** ### `create_subject` Create a new activity profile. Subjects are the building blocks of your schedule — each one represents a subject, project, or recurring activity. | Name | Type | Required | Description | | ------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | **Yes** | Display name for the subject, e.g. `"Linear Algebra"`. | | `type` | string | **Yes** | Activity type. Accepted values: `study`, `training`, `inactive`. | | `color` | string | No | A hex color code for the subject's visual label, e.g. `"#6366f1"`. | | `slots` | array | No | An array of recurring time slot objects that define when this subject is typically scheduled. Each slot includes `day`, `start`, and `end`. | **Returns:** The newly created subject object including its assigned `id`. *** ### `suggest_schedule` Request AI-generated schedule recommendations based on your completion history, stated goal, and available time. Suggestions are not applied automatically — review them and use `create_block` or `update_block` to act on the ones you want. | Name | Type | Required | Description | | ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- | | `goal` | string | No | A natural language description of your study focus, e.g. `"study more math"` or `"front-load the week"`. | | `available_hours` | number | No | Maximum study hours you can commit to per day. If omitted, the AI infers from your history. | **Returns:** An array of schedule recommendation objects, each with a `type` (`add_block`, `move_block`, `remove_block`, or `rebalance`), the target `subject_id`, `day`, proposed `start` and `end` times, and a `reason` explaining the suggestion. *** ## Delete Tools Delete operations are permanent and cannot be undone. Make sure you have identified the correct block before asking your assistant to delete it. ### `delete_block` Permanently remove a study block from your schedule. | Name | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------ | | `block_id` | string | **Yes** | The ID of the block to delete. | **Returns:** A success confirmation object with the deleted block's `id` and a `deleted: true` flag.