---
name: scholarcal
description: Plan, schedule, reschedule, and undo calendar work in a user's private ScholarCal account. Use when a user asks an agent to find sensible open times, arrange several tasks around deadlines, create single- or multi-day events, inspect urgent work, or operate ScholarCal through its REST API or MCP server.
---

# ScholarCal

Use ScholarCal as the user's private planning system. Relational calendar and
task data is authoritative. Semantic memories are preferences for ranking
valid options, never permission to ignore a deadline, conflict, or explicit
instruction.

## Connect

- Production REST base: `https://scholarcal.com`
- Remote MCP: `https://scholarcal.com/api/mcp`
- OpenAPI: `https://scholarcal.com/openapi.yaml`
- Auth: `Authorization: Bearer sc-<api-key>`
- Read operations require `agent:read`; mutations require `agent:write`.
- The user creates/revokes keys in ScholarCal Settings → API Keys. Treat the
  plaintext key like a password and send it only to the ScholarCal origin.

Prefer typed ScholarCal MCP tools when they are connected. Otherwise use the
REST workflow below. Read [references/api.md](references/api.md) when exact
payloads, statuses, or response semantics are needed.

## Plan before choosing a time

When a user provides a complete date and time, honor it and schedule directly.
When they say “whenever works,” list several tasks without times, or ask you to
plan around their life:

1. Call `get_planning_context` (or `GET /api/public/v1/context`) for the relevant
   date range and include the original request as `query`.
2. Treat `free_windows` as candidates, `urgent_tasks` and stated deadlines as
   constraints, and `preferences` only as ranking hints.
3. Put deadline-dependent work before its deadline. For example, pack before a
   Tuesday trip and prioritize homework due tonight.
4. Use these defaults only when the user did not specify a duration: paperwork
   30 minutes, focused homework 90 minutes, ordinary tasks 60 minutes.
5. If no valid window is available, explain the constraint and ask whether to
   shorten, move, or double-book. Never silently pass a force override.

Do not ask “what time?” merely because a time was omitted if context exposes a
safe answer. Ask only for a decision the calendar cannot infer, such as which
of two equally important deadlines may move.

## Schedule natural-language requests

Use `schedule_with_assistant` (or
`POST /api/public/v1/assistant/schedule`) for compound requests, date language,
trips, and planning. Generate one UUID `idempotency_key` per user instruction
and reuse it for retries of that same instruction.

Examples:

- “My trip to Jamaica is from the 21st of this month through the 20th of next
  month.” Create one inclusive multi-day, all-day trip—not a single-day event.
- “While I’m there, research and schedule X, Y, and Z.” First inspect context;
  research each item with bounded, cited sources when web access is available;
  then schedule only feasible actions.
- “Schedule pressure washing, grill cleaning, and screen repair with Yaniv
  Sunday around 10:30.” Keep the three requested appointments distinct unless
  the user clearly describes one combined block.

Interpret responses carefully:

- `stage: confirmed` or `status: completed` with receipts means the write
  happened. Name the scheduled items and times naturally.
- `stage: batch_proposal` means nothing has been written yet; present the plan
  and ask for the one confirmation requested by the response.
- `status: running` means work is still executing. Do not say “done.” Poll with
  `get_workflow`.
- `stage: conflict`, `awaiting_*`, or any 4xx/5xx means the request is not fully
  scheduled. Surface the constraint without inventing success.

Prefer a human reply such as “Done—your three appointments with Yaniv are set
for Sunday. Would you like a reminder?” Include warnings when receipts contain
them. Never expose internal workflow jargon to the user unless diagnosing an
integration.

## Use direct event tools for exact writes

Use `create_event` only when title and exact ISO start/end instants are already
known. Check `list_availability` first unless the user explicitly authorized a
conflict. Report the returned event id. Use the assistant scheduling tool for
all-day or multi-day natural-language requests because it owns inclusive date
semantics.

## Undo safely

Completed assistant workflows expose a seven-day undo window. If the user asks
to undo, call `undo_workflow` with the returned workflow id. Report which event
ids were canceled and any partial-failure warnings. Never represent undo as
available after its expiry.

## Privacy and safety

- Request only the smallest context range needed, never more than 31 days.
- Do not reveal event titles, tasks, memories, contacts, or shared-calendar
  membership to anyone other than the authenticated owner.
- Never turn an email field into a registration-enumeration tool.
- Never claim provider invitations, email delivery, research, or calendar
  writes happened without a successful receipt from the relevant operation.
- Keep API keys out of chat output, logs, URLs, and generated files.