Skip to main content
Glama

Diff the daily plan against the calendar (idempotent projection)

project_day

Compares desired task blocks with existing assistant calendar events to determine which events to create, update, or mark stale, aligning the calendar with the day's plan.

Instructions

Compute which calendar writes make the user's calendar match the day's plan (calendar-as-projection). FIRST gather: (1) desired — the task blocks from rank_day's DailyPlan (each recordId = the Todoist task id, plus summary/start/end); (2) existing — the assistant's already-placed events from list-events, filtered to those tagged extendedProperties.private.source="assistant" (pass each event's id as eventId, its extendedProperties.private.recordId, summary, start, end). This returns {toCreate, toUpdate, stale, unchanged} (idempotent by recordId). THEN execute it: for each toCreate call create-event passing its extendedProperties verbatim (so the tag round-trips); for each toUpdate call update-event with its eventId + new fields. Do NOT delete stale events — report them to the user; their removal is confirmation-gated (PR-010). This is auto+notify: proceed without confirmation, then tell the user what changed.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "desired": "<desired>",
      "existing": "<existing>"
    },
    "name": "project_day"
  }
}

Input Schema

NameRequiredDescriptionDefault
desiredYesDesired task blocks from rank_day.
existingYesAssistant-tagged events currently on the calendar (from list-events).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.1

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations supplied, the description carries the full burden and does so: it discloses idempotency keyed on recordId, the exact return shape `{toCreate, toUpdate, stale, unchanged}`, the requirement that extendedProperties round-trip so the assistant tag survives, and the auto+notify policy (proceed without confirmation, then report). The gating of destructive removal is spelled out rather than left implicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the core purpose leads, then the FIRST/THEN sequencing, then the destructive-action caveat, then the autonomy policy. Nearly every clause carries operational information, though the parenthetical field enumerations and repeated tool names make it longer than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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 must explain return values — and it enumerates all four buckets. For a two-parameter diff/planning step, the combination of input prerequisites, output shape, idempotency semantics, and execution policy leaves nothing an agent needs in order to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `recordId` is the Todoist task id acting as the idempotency key, `existing` must be pre-filtered to events tagged `extendedProperties.private.source="assistant"`, and `eventId`/`recordId` are to be copied from list-events. This filtering precondition is not derivable from the schema itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: "Compute which calendar writes make the user's calendar match the day's plan", with the parenthetical "calendar-as-projection" framing the concept. It distinguishes itself from siblings by naming rank_day as the source of `desired` and list-events as the source of `existing`, so an agent knows exactly where this sits in the pipeline.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit ordered workflow (FIRST gather desired/existing, THEN execute) and names the downstream tools to call for each output bucket (create-event for toCreate, update-event for toUpdate). It also states a clear prohibition: "Do NOT delete `stale` events — report them to the user", with the reason (confirmation-gated, PR-010).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.