Aller au contenu principal
Was this helpful?

MCP Event Listing Best Practices

Use primecal_calendars_events_list as a bounded retrieval tool, not as a full calendar export.

Compact planner context​

Use the default compact response:

{
  "from": "2032-04-16T00:00:00.000Z",
  "to": "2032-04-17T00:00:00.000Z"
}

This keeps payloads small while still exposing timing, calendar identity, organizer summary, and attendee counts.

Follow-up detail expansion​

Request richer fields only when needed:

{
  "from": "2032-04-16T00:00:00.000Z",
  "to": "2032-04-17T00:00:00.000Z",
  "fields": ["id", "title", "description", "meetingUrl", "attendees"],
  "includeFullDescription": false
}

Multi-calendar scheduling​

Scope to a known subset when the agent already knows which calendars matter:

{
  "calendarIds": [14, 15],
  "from": "2032-04-16T00:00:00.000Z",
  "to": "2032-04-23T00:00:00.000Z"
}
  • Fast planning view:
    • default fields only
  • Meeting follow-up:
    • ["id", "title", "startsAt", "endsAt", "meetingUrl", "organizer", "attendees"]
  • Sync/debug view:
    • ["id", "title", "sourceId", "externalId", "calendarId", "calendarName"]
  • Body-aware reasoning:
    • ["id", "title", "description", "meetingUrl"]

Pagination Patterns​

  • Start with limit: 50.
  • If truncated is true, keep calling with the returned nextCursor.
  • Do not rebuild or modify the cursor client-side.
  • Keep from, to, calendarIds, fields, and expandRecurrences stable across pages.

Recurrence Patterns​

  • Use expandRecurrences: true for day-by-day planning or agenda generation.
  • Use expandRecurrences: false for series management, recurrence audits, or “show me the source rule” workflows.

Description Handling​

  • Avoid requesting description unless the task actually needs it.
  • Prefer truncated descriptions first.
  • Use includeFullDescription: true only for second-pass reads or summarization tasks that genuinely need the full body.

Timezone Guidance​

  • Always send UTC from / to.
  • Set userTimezone when the agent is reasoning in a non-default zone.
  • Treat timezone as the rendering context for all-day date-only fields.