samsung-notes-mcp

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

Annotations only declare readOnly and closed-world; the description adds what annotations cannot: the return shape (images for photos, text for PDFs, images only for pages lacking a text layer) and the critical behavioral trait that tall photos/pages arrive in overlapping parts that must be read in full before extracting figures. That is exactly the 'beyond annotation' context an agent needs.

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?

Three short sentences, front-loaded with purpose followed by output shape then the pagination caveat. Every sentence carries actionable information; nothing is padded.

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 does the necessary work of describing what comes back and how large documents are chunked. It is nearly complete for a read tool whose annotations already cover safety, though it omits error behavior (missing file, page out of range) and whether multiple attachments can be fetched at once.

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 100%, so the schema already documents id, file, part, pages and as_images in detail. The description reinforces the 'overlapping parts' semantics of `part` and hints at page-by-page reading, but adds no format or constraint detail beyond what the schema provides, so baseline 3 applies.

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 ('Open a photo or PDF attached to a note') and gives concrete examples (invoice, receipt, scan). It does not explicitly distinguish itself from the sibling get_page_image, which likely overlaps on 'image of a page', so it falls short of full sibling differentiation.

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 is clear contextually: this is how you pull an attachment referenced by a note. It even gives tactical guidance ('read them all before taking figures, and count a repeated line once'), but it never says when to prefer get_page_image or read_note instead, and does not state prerequisites such as where the id/file values come from.

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 openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavior: very tall pages arrive as overlapping parts, all parts must be read, and the repeated boundary line should be counted once — information found nowhere in the schema. It stops short of describing image format or resolution, hence a 4 rather than 5.

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?

Three short sentences, front-loaded with the core action, then the selection rule, then the multi-part caveat. Every sentence carries distinct, needed information; no filler.

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 safety covered by annotations, all three params documented in schema, and no output schema, the description supplies the remaining missing pieces: that the return is an image and how multi-part results should be reassembled. Nothing an agent needs to call this correctly is absent.

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 100%, so baseline is 3. The description earns above baseline by explaining why 'part' exists and how parts relate (overlapping, with a shared repeated line), which the schema's terse 'which part to show' does not convey.

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 ('See one page as an image') and immediately distinguishes itself from the sibling read_note by naming what that tool omits. An agent can tell exactly what this returns without opening the schema.

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?

Explicitly names the use case (handwriting, drawings, layout) and the alternative it supersedes for that content (read_note's text). The condition selecting this tool over read_note is stated, not implied.

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 cover the read-only, non-open-world safety profile, so the description's value is in disclosing the default sort ('newest first') and the pagination contract ('next_offset while more remain'). That tells the agent how to loop and when results are exhausted, context nothing in the schema or annotations provides.

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 sentences, no filler, with the most important facts — result set scope, ordering, and return contract — front-loaded. Every clause carries information an agent needs before calling.

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 an 8-parameter, zero-required search tool with no output schema, the definition supplies the essentials: what comes back (ids), pagination behavior, and default ordering. It could say more about the default/maximum limit and what an empty result means, but nothing critical is missing.

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 75%, and most filter parameters carry their own descriptions (query, folder, modified_after/before, has_attachments, has_handwriting). The description mirrors those filter categories ('words, folder, modified dates, attachments or handwriting') but adds no format or boundary semantics, and limit/offset are only obliquely referenced via 'next_offset'.

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+resource ('Find notes') plus the filter dimensions and the fixed ordering ('newest first'). It also distinguishes itself from siblings by declaring that it returns note ids consumed by the other tools, so an agent knows this is the discovery entry point rather than a content reader.

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?

'Returns note ids for the other tools' establishes the intended search-then-read workflow, which is the key usage signal here. It doesn't name explicit alternatives or exclusions (e.g., use notes_overview to discover folder names, or read_note once you have an id), so it falls short of a 5.

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?

The annotations already establish that this is a read-only, non-open-world operation. The description adds useful behavioral context by stating that it reports folder locations, note counts, totals, and problem conditions such as locked or unreadable notes.

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 two short sentences and front-loads the most important instruction, "Start here." Every sentence adds value with no repetition or filler.

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 zero-parameter read-only overview with no output schema, the description is nearly complete: it explains the starting-point role, the returned scope, and the diagnostics it surfaces. A little more detail about the exact response structure could help, but it is not strictly necessary.

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 tool has no input parameters, so there is no parameter semantics burden. The schema is empty and fully described, and the description appropriately focuses on what the tool returns rather than invocation arguments.

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 uses a specific verb and resource: it shows note sources, folder note counts, totals, and problems such as locked or unreadable notes. It clearly distinguishes this overview tool from sibling tools like list_notes and read_note by focusing on aggregate structure and diagnostics rather than listing or reading individual 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?

"Start here" gives clear guidance that this is the entry point before using note-specific tools. It does not explicitly name alternatives or exclusions, but the intended usage context is unambiguous.

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 openWorldHint=false, so safety is covered; the description adds real value by disclosing the shape of the return payload in the absence of an output schema. It does not cover behavior for an invalid or missing id, nor any pagination or size limits on large notes with many pages.

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?

A single front-loaded sentence with a colon-led payload list; every clause carries information and nothing is repeated from the schema or annotations.

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 a one-parameter schema, read-only annotations, and no output schema, the description carries the full burden of describing the return value — and it does so concretely, including the hint that page-level handwriting/drawing markers exist (implying get_page_image as the follow-up). No material gap remains for a correct call.

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?

Only one parameter, and schema description coverage is 100% — the schema already says 'Note id from list_notes.' The description adds no further semantics about the id format or lookup failure behavior, so the baseline 3 applies.

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 one note') and then enumerates exactly what comes back: title, folder, dates, pages, attachment list, typed text with tables, handwriting/drawing page markers. The payload enumeration implicitly distinguishes it from get_attachment (which fetches the file itself) and get_page_image (which renders a page), but no sibling is named explicitly.

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 is only implied: 'Read one note' plus the schema hint that the id comes 'from list_notes' suggests the list-then-read flow. There is no explicit statement of when to prefer this over get_page_image or notes_overview, and no exclusions or prerequisites are 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?

Goes well beyond the annotations: notes are never mutated, existing files are never overwritten, name collisions get a " (2)" suffix, and files whose contents already exist are skipped — explaining *how* idempotentHint=true is achieved rather than restating it. It also documents the dry-run semantics of check_only, which no annotation covers.

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?

Three tightly packed sentences: what it does first, when to use it second, safety/overwrite/check_only behavior third. Every clause carries distinct information and nothing is repeated.

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 write tool with no output schema, the description covers safety, deduplication, collision handling and the dry-run mode, which is most of what an agent needs. It is slightly thin on what a call actually reports back (especially for check_only) beyond "it says which files are already there".

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 100%, so all three parameters (including nested id/file/name) are already documented with examples, defaults and constraints. The description's contribution — "under names you choose" and the continued-job rationale for check_only — largely echoes what the schema already says, so the baseline 3 applies.

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 (save copies), a specific resource (photos and PDFs attached to notes, with examples like invoices and receipts), and a specific destination (a folder inside the user's Save folder, under caller-chosen names). This is clearly distinguishable from the read-oriented siblings (get_attachment, read_note) which fetch content rather than copying it into a folder.

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?

"Use it only when the user asks to save, collect or organise files" gives an explicit trigger and an implicit exclusion, plus a described workflow for the check_only pre-pass. It does not name a sibling alternative (e.g. get_attachment for merely reading an attachment), so it stops short of a full routing rule.

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