Read plain body text from Apple Pages documents with character pagination, excluding rich formatting and text boxes.
Read Pages plain text with character pagination. Pages supports word-processing body text only; rich formatting and text boxes are not returned.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | ||
| maxChars | No | ||
| documentName | Yes | Exact name returned by list_documents; ambiguous duplicate names are rejected. |
Changes observed during successful MCP inspections.
v3.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnly, idempotent, non-destructive, non-openWorld), so the description's real contribution is the scope caveat: only word-processing body text is returned, with rich formatting and text boxes excluded. That is genuine behavioral information an agent cannot infer from structured fields, though return shape and truncation semantics for large documents remain unstated.
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 compact sentences, the capability front-loaded and the limitation immediately after. Nothing is redundant and no sentence fails to earn 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?
For a read-only text extraction tool with annotations covering safety and no output schema to explain, the description supplies the essential scope limitation and pagination model. The remaining gap is workflow context (open-first requirement, empty-document behavior), which is minor but not trivial for an agent operating a document app.
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 only 33%: documentName is well documented in the schema, but offset and maxChars have only type/default/bounds and no prose meaning. The phrase 'character pagination' partially compensates by explaining what offset/maxChars are for, but the units relationship and behavior at the 50000-char cap are left to inference.
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?
States a specific verb and resource (read Pages plain text) plus the delivery mechanism (character pagination), which clearly separates it from sibling mutators like apple_pages_set_text and apple_pages_export. It stops short of differentiating from the cross-app sibling apple_files_read_text or apple_textedit_read_text, which an agent could plausibly confuse it with.
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?
Usage context is implied — you read text when you need document content — but there is no explicit statement of when to prefer this over apple_pages_export or apple_files_read_text, and no mention of prerequisites such as whether the document must first be opened via apple_pages_open or discovered via apple_pages_list_documents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.