Read a note; it ends with the version to pass as write_file base. On an attachment: images inline; PDF, Office, iWork, RTF and text as text; spreadsheets as CSV; video as frames; else a signed URL (1 h). Long PDFs: the reply says which pages to ask next.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| pages | No | PDF only, e.g. "12-30" | |
| workspace | No | Usually omit; else brain id (as in search hits), 'mine', or owner name/email. |
Changes observed during successful MCP inspections.
Input schema / properties / pages / descriptionPrevious value: -"PDF attachments only: pages to read, e.g. \"12\" or \"12-30\""New value: +"PDF only, e.g. \"12-30\""Input schema / properties / workspace / descriptionPrevious value: -"Brain to act on: its id, «mio» (yours), or the owner's name/email as shown by search. Usually OMIT it: a path that already lives in one brain is found there, for reads and writes alike. Pass it only when the tool tells you to (a NEW branch, or one that exists in several brains) — with the brain the user named; when they were not explicit ASK THEM. A brain where the branch does not exist is refused even if you name it."New value: +"Usually omit; else brain id (as in search hits), 'mine', or owner name/email."Input schema / properties / pagesAdded value: +{
+ "description": "PDF attachments only: pages to read, e.g. \"12\" or \"12-30\"",
+ "type": "string"
+}Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly=true, destructive=false, openWorld=false), and the description goes well beyond them, disclosing return-format behavior per attachment type (images inline, Office/iWork/RTF as text, spreadsheets as CSV, video as frames, otherwise a 1-hour signed URL) and the pagination behavior for long PDFs. This is exactly the behavioral context that annotations cannot convey.
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?
Front-loads the core purpose in the first clause, then appends the base-version contract and the attachment-format matrix. Dense but every clause carries distinct information; the semicolon-chained list of formats is compact if slightly breathless.
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?
With no output schema, the description correctly shoulders the burden of describing return shapes, and it does so per attachment type plus the PDF pagination follow-up. It stops short of noting any size limits or failure modes, but for a read tool it is otherwise complete.
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 67%, with `path` and `pages` documented in-schema; the description adds workflow meaning to `pages` by explaining that the reply tells the agent which page range to request next on long PDFs. Only `workspace` is left entirely to the schema, which is a minor gap given its "usually omit" default.
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 a note") and immediately distinguishes the read path from the write path by explaining the version token that feeds write_file `base`. It reads clearly as the file-content reader among siblings, though it never explicitly contrasts itself with list_files, fetch, or find_notes.
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?
The description implies the read→write workflow by naming write_file `base`, which is useful cross-tool guidance. However it offers no explicit when-to-use or when-not-to-use guidance relative to the other read-oriented siblings (list_files, fetch, find_notes), leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.