Skip to main content
Glama
vgnshiyer

apple-books-mcp

by vgnshiyer
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Annotations by date range

get_annotations_by_date_range
Read-only

Retrieve Apple Books annotations within a date range, newest first by default, to review highlights and notes from a specific reading period.

Instructions

Annotations created within a date range, newest first by default. Flat rows with the creation time and book name inline. Dates and times are in the Mac's local time zone, named in the header.

Row format::

YYYY-MM-DD HH:MM [id] text — chapter · Book Title

Args: after: Only include annotations created on or after this date (YYYY-MM-DD, or YYYY-MM-DDTHH:MM). before: Only include annotations created on or before this date (YYYY-MM-DD covers the whole day, or YYYY-MM-DDTHH:MM). limit: Max annotations to return (1–500, default 50). offset: Annotations to skip, for paging. order_by: newest (default) or oldest first.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
afterNo
limitNo
beforeNo
offsetNo
order_byNonewest

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.9.0
    • addedInput schema / properties / after / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • removedInput schema / properties / after / type
      Removed value: -"string"
    • addedInput schema / properties / before / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • removedInput schema / properties / before / type
      Removed value: -"string"
    • addedInput schema / properties / order_by / enum
      Added value: +[
+  "newest",
+  "oldest"
+]
  2. First observedv0.8.4

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering safety. The description adds genuinely non-obvious behavior: timestamps are in the Mac's local time zone, 'newest' is the default order, and the exact row rendering (date, id, text, chapter, book title). No pagination limits or error behavior for malformed dates are disclosed.

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?

Front-loaded with the one-line purpose, then the return format, then a compact Args block — a sensible order for an agent. Slightly verbose in the repeated 'Only include annotations created on or after/before this date' phrasing, but nothing is wasted.

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

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly compensates by documenting the row format and time zone, and it covers all five optional parameters. It is complete enough to call correctly; the missing pieces are sibling routing and what happens on invalid or inverted date ranges.

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

Parameters5/5

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

Schema description coverage is 0%, so the description carries the full burden and does so: it documents accepted formats for after/before (YYYY-MM-DD vs YYYY-MM-DDTHH:MM, including the whole-day rule for before), the limit range 1–500 with default 50, offset as a paging skip, and the order_by semantics. Every parameter is meaningfully specified beyond its bare schema type.

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

Purpose4/5

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

States a specific verb+resource with scope: annotations filtered by creation date range, ordered newest first. That scope distinguishes it from unfiltered siblings like list_all_annotations, but the description never names an alternative, so the agent must infer the split from sibling names alone.

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

Usage Guidelines2/5

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

No when-to-use or when-not-to-use guidance is given, and no alternative is named despite several overlapping siblings (search_annotations, recent_annotations, list_all_annotations, list_annotations). The date-range framing implies a use case but the agent is left to infer routing entirely.

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

Deploy Server

Other Tools