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., "@YearAtAGlance MCP Server Show me my 2025 events and generate a density heatmap"
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.
MCP (Model Context Protocol) server for integrating YearAtAGlance calendar with Claude Code and other MCP-compatible AI assistants.
npm install -g @yearataglance/mcp-serverOr use directly with npx:
npx @yearataglance/mcp-serverRelated MCP server: MCP Calendar Assistant
Go to YearAtAGlance
Navigate to Profile > API Keys
Create a new API key with the permissions you need
Copy the key (it's only shown once!)
Add to your ~/.claude/claude_desktop_config.json:
{
"mcpServers": {
"yearataglance": {
"command": "npx",
"args": ["@yearataglance/mcp-server"],
"env": {
"YAAG_API_KEY": "your-api-key-here",
"YAAG_API_URL": "https://yearataglance-backend-production.up.railway.app/api/v1"
}
}
}
}Tool | Description |
| List all events, optionally filtered by year and category |
| Get details of a specific event |
| Create a new event |
| Update an existing event |
| Delete an event |
| Get event density heatmap for a year |
Tool | Description |
| List all categories |
| Get details of a specific category |
| Create a new category |
| Update an existing category |
| Delete a category |
Tool | Description |
| Check AI service status |
| Create event from natural language |
| Get AI analysis of a year's events |
| Chat with AI about your calendar |
Once configured, you can use natural language in Claude Code:
"Show me all my events for 2025"
"Create an event called 'Team Offsite' from March 10-12"
"What categories do I have?"
"Create a new category called 'Health' with green color"
"Delete the event with ID xyz123"Variable | Required | Default | Description |
| Yes | - | Your YearAtAGlance API key |
| No | Production URL | API base URL |
API keys can have different permissions:
read: List and view events/categories
write: Create, update, delete events/categories
ai: Use AI features (milestone creation, analysis, chat)
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run devMIT
Get AI-powered analysis and insights for a specific year's events
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | The year to analyze (e.g., 2025) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not explain what 'AI-powered analysis' entails (e.g., costs, latency, required permissions), nor does it specify what happens if no events exist for the given year. This is a significant gap for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly conveys the purpose with no wasted words. It is front-loaded with the action and 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?
Given the simple input (one parameter, no enums, no output schema), the description is minimally adequate. However, it lacks details about the nature of the insights, the output format, and any side effects. It is complete enough for basic use but leaves room for ambiguity.
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%, and the description adds no extra meaning beyond the schema's parameter description. The parameter 'year' is adequately documented in the schema, so the description provides no additional 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 tool provides AI-powered analysis and insights for a specific year's events. It uses a specific verb ('Get'), resource ('AI-powered analysis and insights'), and scope ('for a specific year's events'), distinguishing it from siblings like yaag_get_event or yaag_list_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need AI insights for a year's events, but it provides no explicit guidance on when to use this tool versus alternatives (e.g., yaag_ai_chat or individual event retrieval). There are no exclusions or context on prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Chat with the AI assistant about your calendar, events, and schedule
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | Your message or question for the AI assistant | |
| conversationId | No | Optional conversation ID to continue a previous conversation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes the tool as a chat, but does not disclose whether it is read-only, can create/modify data, or any constraints like rate limits. The behavior is vague.
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 is concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a chat assistant with two parameters and no output schema, the description is adequate but lacks details on what the chat can actually do (e.g., answer questions vs. trigger actions) and does not explain the conversationId parameter's role in maintaining context.
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 well. The description adds context about the domain (calendar, events, schedule) but does not add new meaning beyond what the schema provides for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'chat', the resource 'AI assistant', and the scope 'about your calendar, events, and schedule'. It distinguishes the tool from sibling tools which are specific CRUD operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for conversational interactions about calendar, events, and schedule, but does not explicitly state when to use it versus alternatives like direct CRUD tools. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use AI to create an event from natural language input. Example: 'My birthday on March 15th' or 'Team offsite next week'
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Natural language description of the event to create (e.g., 'Vacation in Italy from July 10 to July 20') | |
| year | No | Target year for the event (defaults to current year if not specified) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It states the tool uses AI to create an event, but does not disclose behaviors such as handling of ambiguous input, required permissions, side effects, or whether it actually creates a 'milestone' versus 'event' (name vs. description inconsistency). The description is insufficient for an agent to anticipate behavioral nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loading the purpose. Every word is valuable; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no nested objects), the description covers core functionality. However, it lacks explanation of return values (no output schema) and has a naming inconsistency ('milestone' vs 'event'). It meets minimum viability but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds natural language examples, which are helpful but do not significantly extend beyond the schema's definitions. 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 uses AI to create an event from natural language input, with specific verb 'create event' and resource 'natural language input'. It distinguishes from sibling tools like yaag_create_event (manual creation) and yaag_ai_analyze_year, and provides illustrative examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives examples and implies usage for converting natural language to events, but lacks explicit guidance on when not to use this tool versus alternatives such as yaag_create_event or yaag_ai_analyze_year. No exclusion criteria or context-dependent recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the status of the AI service in YearAtAGlance
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description only says 'Check the status', revealing minimal behavior. It does not explain what the status entails or that it is a read 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?
Single sentence with zero waste, perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, yet the description only states the operation without explaining the return format or any edge cases, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description adds no extra meaning but also does not need to.
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 'Check' and the resource 'status of the AI service', distinguishing it from sibling tools that analyze, chat, or create milestones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives, but the purpose is implied well by the naming and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new category for organizing events
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Category name (e.g., Work, Personal, Health) | |
| color | Yes | Category color in hex format (e.g., #FF5733) | |
| description | No | Category description (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full burden but only states the surface action. It does not disclose effects like duplicate handling, idempotency, required authentication, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence (6 words), front-loaded with the verb and object. It could include more use context without losing conciseness, but it 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?
Despite simple parameters and no output schema, the description omits what happens on success (e.g., returns the created category) and lacks behavioral details. It is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameter meanings are already clear from the schema. The tool description adds no additional parameter context, thus meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new category for organizing events' clearly states the action (create) and resource (category), and the purpose aligns with the tool's role in event management, distinguishing it from siblings like yaag_create_event.
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 yaag_update_category or yaag_delete_category. It does not mention prerequisites or typical usage flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new event in the YearAtAGlance calendar. Dates should be in ISO 8601 format.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Event title | |
| startDate | Yes | Start date in ISO 8601 format (e.g., 2025-01-15) | |
| endDate | Yes | End date in ISO 8601 format (e.g., 2025-01-15) | |
| description | No | Event description (optional) | |
| categoryId | No | Category ID to assign the event to (optional) | |
| allDay | No | Whether this is an all-day event (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description only states 'Create a new event' which implies a write operation, but gives no details on side effects, authentication needs, or what happens on failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no fluff. The essential purpose and a key format requirement are stated upfront, though more detail could be added without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 6 parameters and no output schema, the description omits important context such as return value, validation behavior, and whether optional fields have constraints (e.g., categoryId must exist).
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 baseline is 3. The description adds the ISO 8601 format note, which is already present in the schema descriptions, so no significant additional meaning 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?
The description clearly states the verb 'Create' and the resource 'event in the YearAtAGlance calendar,' distinguishing it from sibling tools like yaag_update_event or yaag_delete_event.
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 only guideline is the ISO 8601 format hint for dates. There is no guidance on when to use vs. other tools, nor any mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a category. Events in this category will become uncategorized.
| Name | Required | Description | Default |
|---|---|---|---|
| categoryId | Yes | The ID of the category to delete |
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 usefully discloses that events in the category become uncategorized, a key side effect. However, it does not mention reversibility or other behavioral implications.
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 concise sentences with no fluff, front-loading the core action and adding a critical side effect. 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?
Given the simple parameter set and no output schema, the description adequately covers the purpose and a key behavioral side effect. It is complete for the tool's complexity.
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 coverage is 100% and the description adds no additional meaning to the parameter beyond what the schema already provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a category' with a specific verb and resource, and also distinguishes it from siblings by noting the effect on events. This provides a clear and specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deleting a category, but lacks explicit when-to-use or when-not-to-use guidance, and does not mention alternatives. Some context is provided but not structured as guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an event from the calendar
| Name | Required | Description | Default |
|---|---|---|---|
| eventId | Yes | The ID of the event to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It only states 'Delete' without revealing if the action is reversible, if it cascades to related data, or any permission requirements. The minimal description leaves the agent unaware of consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. Optimally concise for the tool's simplicity.
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 delete operation with one parameter and no output schema, the description is adequate. However, it lacks context about the permanence of deletion or any confirmation steps, which would be helpful but not strictly required given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter eventId. The description adds no additional meaning beyond the schema's 'The ID of the event to delete'. Baseline score 3 is appropriate as the schema is sufficient.
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 ('Delete') and the resource ('an event from the calendar'). It distinguishes well from sibling tools like yaag_create_event and yaag_update_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, such as ensuring the event exists, or when deletion might be inappropriate.
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 category by its ID
| Name | Required | Description | Default |
|---|---|---|---|
| categoryId | Yes | The ID of the category to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description merely restates the name without disclosing any behavioral traits such as authentication requirements, error handling, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is front-loaded, concise, and contains no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get operation with one parameter, the description is adequate but lacks details on output structure or potential errors. No output schema provided.
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 a clear description for categoryId. Description adds no new meaning beyond that, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'get', resource 'category', and identifier 'by its ID'. Distinguishes from siblings like create, delete, update, and list.
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 over alternatives like yaag_list_categories. Usage context is implied but not explicit.
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 event by its ID
| Name | Required | Description | Default |
|---|---|---|---|
| eventId | Yes | The ID of the event to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only implies a read operation ('get details') but does not specify behavior on missing event, return format, or any side effects. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no superfluous words. Every part contributes to explaining the function. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given tool simplicity (one param, no output schema), description is mostly complete. Could mention error handling (e.g., if ID not found), but not essential for basic usage.
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 the parameter (eventId). Description adds no additional meaning beyond what the schema provides. Baseline score 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?
Description clearly states the verb 'get', resource 'details of a specific event', and method 'by its ID'. It distinctly separates from sibling tools like create, delete, update, and list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., yaag_list_events vs get_event). No mention of prerequisites, exclusions, or recommended contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get heatmap data showing event density for each day of a year
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | The year to get heatmap data for (e.g., 2025) |
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 does not mention what 'heatmap data' includes, any side effects (likely none), or the nature of the output (e.g., array of day-density pairs). Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the core action and result. No unnecessary words or repetition.
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 is adequate but could benefit from clarifying what the heatmap data contains (e.g., day, count). Lacks completeness regarding output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds an example value (2025) but no additional semantic meaning beyond the schema's description of 'year'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves heatmap data showing event density per day for a given year. It distinctly separates from sibling tools like get_event or list_events, which operate on individual events or lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as yaag_ai_analyze_year. The usage context (getting heatmap for a year) is implied but lacks when-not or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all categories in the YearAtAGlance calendar
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description only states 'list all categories' without mentioning behavioral traits like whether it is read-only, requires authentication, handles pagination, or returns an empty array. The read-only nature is implied but not explicit.
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, direct sentence that efficiently communicates the tool's purpose. It contains no unnecessary words and is front-loaded with the key action and 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?
With no output schema, the description should explain what the tool returns (e.g., a list of category names and IDs). It only says 'list all categories,' leaving the return structure unstated. For a simple tool, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description adds no parameter information, but none is needed because there are no parameters to describe.
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') and the resource ('all categories in the YearAtAGlance calendar'), making it unambiguous. It distinguishes itself from singular retrieval tools like yaag_get_category and creation tools like yaag_create_category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly provide when-to-use or when-not-to-use guidance. For a simple listing tool, the purpose is self-evident, but it could mention that it returns all categories without filtering, unlike yaag_get_category which returns a single category.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all events from YearAtAGlance calendar. Optionally filter by year and/or category.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Filter events by year (e.g., 2025) | |
| categoryId | No | Filter events by category ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states listing and optional filters, omitting details like sorting, pagination, or side effects. Carries full burden but insufficient.
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, front-loaded with core purpose, no wasted 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?
No output schema, so missing return format. Adequate for a simple list, but lacks info on pagination or ordering for 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?
100% schema coverage with descriptions for both parameters; description adds no extra meaning beyond restating 'optionally filter by year and/or category'.
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' and resource 'events' with optional filters. Distinct from siblings like yaag_get_event (single) and yaag_create_event.
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 vs alternatives such as yaag_list_categories or yaag_get_heatmap. No explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing category
| Name | Required | Description | Default |
|---|---|---|---|
| categoryId | Yes | The ID of the category to update | |
| name | No | New category name | |
| color | No | New category color in hex format | |
| description | No | New category description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It only states 'update', implying mutation, but lacks details on side effects, permissions, or partial update behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no wasted words. It is front-loaded and efficient, though it could be slightly more informative without becoming 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?
For a mutation tool with no output schema and no annotations, the description is too brief. It does not explain what happens on success, error handling, or whether updates are partial or full.
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 schema already documents each parameter. The description adds no additional meaning or context beyond what is in 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?
The description clearly states the action ('update') and the resource ('category'). It distinguishes from sibling tools like create, delete, get, and list, though it could be more specific about which fields can be updated.
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 create_category or delete_category. No context on prerequisites or typical scenarios is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing event
| Name | Required | Description | Default |
|---|---|---|---|
| eventId | Yes | The ID of the event to update | |
| title | No | New event title | |
| startDate | No | New start date in ISO 8601 format | |
| endDate | No | New end date in ISO 8601 format | |
| description | No | New event description | |
| categoryId | No | New category ID | |
| allDay | No | Whether this is an all-day event |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must convey behavioral traits. It does not state whether the update is partial or full, what happens if the eventId is invalid, or any side effects. This is insufficient 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?
The description is a single sentence, making it concise, but it sacrifices necessary detail. It is not front-loaded with key information beyond the basic purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is too sparse. It does not explain update behavior (e.g., only specified fields updated), return value, or error conditions.
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 fully describes all parameters. The description adds no additional meaning beyond what is in the schema, meeting the baseline.
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 'Update an existing event' specifies the action and resource, distinguishing it from create and delete siblings. However, it lacks detail on what fields can be updated, making it only moderately helpful.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., create_event for new events). The description provides no explicit context or exclusions.
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.1yaag_ai_analyze_yearyaag_ai_chatyaag_ai_create_milestoneyaag_ai_statusyaag_create_categoryyaag_create_eventyaag_delete_categoryyaag_delete_eventyaag_get_categoryyaag_get_eventyaag_get_heatmapyaag_list_categoriesyaag_list_eventsyaag_update_categoryyaag_update_eventScored across 15 tools
Tools are clearly grouped into AI operations, category CRUD, and event CRUD, with no overlapping purposes. Each tool has a distinct function that is easy to differentiate.
All tools share the 'yaag_' prefix, but the AI tools (e.g., 'yaag_ai_chat') have a slightly different naming pattern compared to the CRUD tools (e.g., 'yaag_create_category'). Overall consistent but with minor deviation.
15 tools is appropriate for a calendar management server with AI features, covering creation, retrieval, updating, deletion, listing, and analysis without being excessive.
Full CRUD operations for events and categories are provided, along with AI analysis and heatmap visualization. Missing advanced features like bulk operations or search, but core workflows are well-covered.
GDPR-compliant calendar access for AI assistants: read, create, edit, RSVP. Google, MS 365, Apple.
Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.
Connects ChatGPT to your Apple Calendar via a local Mac agent + Vercel relay
Gives your AI assistant persistent memory and intelligence about your work patterns.
