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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the auto-redirect to remarkable_read for document paths, the list of result fields (names, types, paths, dates), and the root-path scoping. It does not describe edge cases like empty folders or permission errors, but the core behavior is transparent.

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?

The description is well-organized with sections (usecase, instructions, parameters, examples) and uses clear formatting. It is not overly verbose and every sentence adds value. It could be slightly tighter (e.g., merging the root path note into the path guidance), but the structure is effective and front-loads the core action.

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?

Given the output schema exists, the description need not explain return structure, and it does mention result fields anyway. It covers the primary path parameter and the auto-redirect behavior, which is important. However, the compact_output parameter is undocumented, and there is no mention of pagination or large-folder behavior. For a read-only browsing tool with two parameters, the missing parameter is a notable completeness gap.

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?

The schema has two parameters: path and compact_output, but the description only documents path. The schema description coverage is 0% per context signals, so the description carries the full burden. It explains path usage with examples and defaults, but compact_output is completely omitted—an agent would not know it exists or what it does. This is a significant gap for one of two parameters.

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?

The description opens with a clear usecase: 'Browse your reMarkable library folders' and explicitly states 'List contents of a folder on your reMarkable tablet.' It distinguishes itself from siblings by noting that browsing to a document path redirects to remarkable_read, and it names remarkable_search as the alternative for name/content search. The verb-resource pairing is specific and unambiguous.

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 provides explicit usage instructions: how to use path for root and subfolders, the behavior of document paths (auto-redirect to read), and the REMARKABLE_ROOT_PATH constraint. It also directly points to remarkable_search() when searching is needed, giving clear when-to-use vs. when-not-to-use guidance. No alternative is left ambiguous.

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

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

Annotations are minimal (no idempotent, no destructive hints), so the description carries burden. It discloses the parent-existence requirement and the one-level-at-a-time limitation. It does not state behavior on duplicate folder names or parent missing (e.g., error handling). It also omits the compact_output parameter's effect. This is a moderate gap.

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?

The description is well-structured with usecase, instructions, parameters, and examples. It is front-loaded with the purpose, and every sentence adds value. The examples are practical. No unnecessary fluff. Concise and efficient.

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?

The tool has an output schema (not shown), so return format is presumably covered. However, the description misses the optional 'compact_output' parameter entirely, which affects how results are presented. It also does not mention failure conditions (e.g., if parent doesn't exist or folder already exists). For a simple tool, these are notable omissions.

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 description coverage is 0%, so the description must fully explain parameters. It explains 'path' well with format and examples (full path or top-level name). However, it entirely ignores 'compact_output', which is present in the schema. Thus, one parameter is well-documented but the other is absent, leaving the agent without guidance on output format.

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?

The description states a specific action ('Create a new empty folder') with a clear resource ('on your reMarkable'). It distinguishes from siblings (browse, rename, move, etc.) through the verb 'create' and the folder-specific context. Examples clarify usage. This is unambiguous.

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 provides a clear prerequisite: the parent folder must already exist, and it limits creation to one level at a time. It implies when to use (to create a folder) and the constraints. However, it does not explicitly contrast with sibling tools, but no sibling is for creation, so the guidance is adequate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds rich context beyond them: exact response formats (PNG as ImageContent, SVG as EmbeddedResource), the compatibility flag for clients without embedded-resource support, OCR behavior and the REMARKABLE_OCR_BACKEND=sampling path, and PDF/EPUB annotation-layer rendering. No contradiction with annotations.

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?

Well-structured with usecase/instructions/parameters/examples tags, front-loaded with the purpose, and examples add real value. Slightly long, but the dense instructions are organized in scannable subsections (Response Formats, OCR, PDF behavior) so every sentence earns 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?

With no output schema and 0% schema coverage, the description carries a heavy burden and mostly delivers: it explains return formats, defaults, OCR, PDF caveats, and includes 7 illustrative examples. The sole completeness gap is the undocumented compact_output parameter, which an agent could not know how to use.

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 description coverage is 0%, so the description must compensate — and it does thoroughly: document (with browse pointer), page (1-indexed default), background (hex format, default, env override, transparent), output_format, compatibility, and include_ocr all get meaningful semantics. However, the input schema's compact_output parameter is not mentioned anywhere in the description, leaving one of seven parameters undocumented in both schema and description.

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?

The usecase tag states a specific verb+resource ('Get an image of a specific page from a reMarkable document') that clearly distinguishes it from siblings like remarkable_read (text extraction) and remarkable_browse (document tree). The instruction that it provides 'visual context that text extraction might miss' further disambiguates it from remarkable_read.

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 lists concrete use cases (viewing diagrams, sketches, mockups, wireframes) and a clear when-not: 'works best with notebooks... For PDFs/EPUBs, the annotations layer is rendered (not the underlying PDF content)'. It also routes to remarkable_browse for finding documents. However, it never explicitly names remarkable_read as the alternative for text-only extraction, leaving that exclusion implicit.

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

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

Annotations mark this as a non-read, non-destructive operation. The description adds value by stating the item keeps its name and contents and explaining the '/' syntax, which goes beyond what annotations reveal. It does not cover error cases or permission requirements, but the core behavior is disclosed.

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?

The description is well-organized with usecase, instructions, parameters, and examples. Every section serves a purpose, and the examples are especially useful for an agent to pattern-match calls. No filler or redundancy.

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?

An output schema exists, so return values are covered. The description addresses the main behavior, the top-level special case, and parameter formats. It omits the compact_output parameter and error handling, but for a straightforward move tool this is largely sufficient.

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?

With 0% schema coverage, the description must compensate. It explains 'item' as a name or full path and 'destination' as a folder path or '/' for top level, adding real meaning to the bare string types. However, the third parameter 'compact_output' is entirely unmentioned, leaving a gap.

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?

The description states a specific verb ('move') and resource ('document or folder'), and clearly differentiates from siblings like remarkable_rename and remarkable_create_folder by naming the action. The usecase tag reinforces the core purpose without ambiguity.

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?

Instructions clarify how to use the tool, including the special '/' destination for top-level moves and the preservation of name/contents. It does not explicitly list when not to use it or alternative tools, but the context is clear enough for an agent to decide when this is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: pagination to preserve context, content type selection, multi-page specs, grep auto-redirect, and OCR behavior depending on environment. This goes well beyond what annotations provide.

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?

Well-structured with usecase, instructions, parameters, and examples. Each section is purposeful, front-loaded with the core purpose, and avoids redundancy. Appropriate length for a complex tool.

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?

Covers all major behaviors: pagination, content types, grep, OCR, and multi-page modes. The only missing detail is the compact_output parameter, which is not mentioned. Output schema exists, so return values are documented elsewhere. Overall very complete for a tool with 8 parameters.

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 description coverage is 0%, so the description's parameter section is essential. It explains document, content_type, page, pages, grep, include_ocr, and auto_ocr with clear semantics and examples. However, it omits the 'compact_output' parameter present in the schema, leaving a small gap in meaning.

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 and extract text content from a reMarkable document.' Clearly distinguishes from siblings like remarkable_browse (finding documents) and remarkable_search (searching), making it unambiguous for an agent.

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?

Provides detailed instructions on content types, reading modes, pagination, and grep behavior, plus a note to use remarkable_browse for finding documents. It does not explicitly list when NOT to use this tool versus alternatives like search, but the usecase and examples give enough context for an agent to select appropriately.

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

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

Beyond the readOnlyHint/idempotent annotations, the description adds that previews are served from the local index (no cloud download), the sorting order, the limit behavior (max 50 without preview, 10 with preview), and the REMARKABLE_ROOT_PATH constraint. This gives an agent a solid model of what happens when the tool is invoked.

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?

The description is well-structured with usecase, instructions, parameters, and examples. It is front-loaded with the core purpose and keeps each section tight. No redundant sentences.

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?

Given that an output schema exists, the description doesn't need to explain return values. It covers the main behaviors, constraints, and usage. The only gap is the undocumented compact_output parameter, but overall it's nearly complete for a read-only tool.

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?

The schema has 0% description coverage, so the description must explain all parameters. It explains limit and include_preview clearly, but omits the compact_output parameter entirely. While examples show usage, the missing parameter prevents a complete understanding.

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?

The description states the specific verb 'Get' and resource 'most recently modified documents', and clarifies sorting behavior. This clearly distinguishes it from siblings like remarkable_search or remarkable_read.

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 instruction 'Use this to quickly find what you were working on recently' provides a clear usage scenario. It also notes the REMARKABLE_ROOT_PATH condition, but does not explicitly mention alternative tools or when not to use this tool.

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

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

Annotations include readOnlyHint=false and destructiveHint=false, indicating it's a mutation but not destructive. The description adds valuable context: it explicitly states that contents, annotations, and page data are untouched, and it mentions atomicity and that the response includes the previous library state for undo. This goes beyond the annotations and provides useful behavioral transparency, warranting a 4.

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?

The description is well-structured with a usecase, instructions, parameters, and examples. It is front-loaded with the primary purpose, and every section adds value. The examples clarify usage. It is concise and efficient with no unnecessary filler, earning a 5.

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?

The description covers the operation's effect, atomicity, undo capability, and the main parameters. An output schema exists, so the description need not explain return values. However, it omits the compact_output parameter and does not address error conditions or edge cases (e.g., item not found). Given the tool's moderate complexity and that most critical information is present, a 4 is justified.

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?

The schema description coverage is 0%, so the description must compensate. It does explain the two required parameters (item and new_name) with useful semantics ('Current name or full path' and 'just the name, not a path'), which is helpful. However, it does not mention the optional 'compact_output' parameter that appears in the schema. Since one parameter is undocumented, the compensation is incomplete, so a 3 is appropriate.

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?

The description clearly states the purpose: 'Rename a document or folder on your reMarkable.' This is a specific verb (rename) and resource (document/folder), which is clear. However, it does not explicitly distinguish itself from sibling tools like remarkable_move, which might involve similar operations. The name and description are clear enough, but no sibling differentiation is present, so a 4 is appropriate.

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 instructions provide context about the operation ('Changes the visible name. Contents, annotations and page data are untouched.') but do not explicitly state when to use this tool versus alternatives. There is no mention of exclusions or alternative tools. The usage is implied rather than explicit, so a 3 is given.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds significant behavioral detail beyond that: it explains the two execution modes (metadata-only without grep, content search with grep), the use of a cached FTS5 index, that reading via remarkable_read populates the index, that the response includes index_coverage, and the 10-document limit. It also notes 'no cloud downloads' in metadata mode. No contradiction with annotations.

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?

The description is well-organized with sections: usecase, instructions, parameters, examples. It is reasonably concise and front-loaded with the core purpose. There is minor redundancy (limits and parameter default repeated, 'Use grep' mentioned twice), but overall it is efficient and easy to scan. The examples are helpful.

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 tool with 5 parameters, an output schema, and read-only annotations, the description covers the main behavioral aspects: modes, indexing, limits, and examples. The output schema handles return values, so index_coverage is mentioned but not detailed. The main gap is the undocumented compact_output parameter, which prevents full completeness. Also, it doesn't mention pagination or sorting, but those are not critical for a search tool of this size. Overall, it is fairly complete with one notable omission.

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 description coverage is 0%, so the description must compensate. It explains query, grep, limit, and include_ocr with meaningful descriptions (e.g., grep is 'Optional regex pattern to search within document content'). It adds max=10 for limit, which the schema lacks. However, it completely omits compact_output, a fifth parameter, leaving the agent with no guidance on what it does. Since it covers 4 of 5 parameters but misses one entirely, it does not fully compensate for the lack of schema descriptions.

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?

The description opens with a clear use case: 'Search across multiple documents and return matching content.' It specifies the verb (search), the resource (multiple documents), and the outcome (matching content). It further distinguishes two modes (metadata-only vs. content grep), which sets it apart from sibling tools like remarkable_browse (browsing) and remarkable_read (reading). No ambiguity about what this tool does.

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 clearly implies when to use this tool: when you need to find documents by name or indexed content. It explains the relationship with remarkable_read (reading indexes content for future search), which is useful context. However, it does not explicitly state when to prefer this over alternatives like remarkable_browse or remarkable_recent, nor does it mention exclusions. It provides clear context but not explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it includes 'index statistics when available' and mentions diagnostic info, which is useful extra context beyond the annotations, but it does not detail the exact output or behavior further.

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?

The description is well-structured with usecase, instructions, and examples. It is front-loaded with purpose and each section earns its place without redundancy.

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 simple diagnostic tool with an output schema present, the description covers the purpose, when to use, and a usage example. It does not explain return values, but that is covered by the output schema. Slightly more detail on the 'index statistics' could help, but it is not essential.

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?

The schema has no description for compact_output (coverage 0%), but the example 'compact_output=True # Omit hints' provides some meaning, indicating it controls whether hints are shown. This is minimal but does add value beyond the schema's bare boolean type.

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?

The description clearly states the tool checks connection status and authentication with reMarkable Cloud, using specific verbs and resource. It is distinct from siblings which handle browsing, reading, renaming, etc., so an agent can easily tell them apart.

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?

It explicitly says 'Use this to verify your connection or troubleshoot issues,' giving clear context for when to use. It does not mention alternatives or when not to use, but no overlap exists with siblings, so exclusion is not critical.

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