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

Annotations already provide idempotentHint=true and destructiveHint=false, and the description reinforces that: 'A path that already exists is left untouched.' The description adds substantial behavioral context: how parent folders are created, addressing by id instead of name, and refusal behavior when a parent path is ambiguous. 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-organized into three focused paragraphs covering purpose, sibling differentiation, and addressing details. Every sentence adds value; the path example and design rationale are all earned. Slightly longer than strictly necessary but each point matters.

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 single-parameter tool with output schema present, the description covers everything needed: path semantics, idempotency, ambiguity refusal, addressing model, and the relationship with create_note. Output schema handles return values, so that omission is fine.

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 0% (path has no description in schema), so the description must compensate. It does: explains path format with an example, how segments are created under each other, behavior when the path already exists. The single parameter is thoroughly documented despite zero schema coverage.

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?

Specific verb (Create) + resource (folder) + location (path), with clear semantics: creates missing parent folders along the way. Distinguishes from sibling `create_note` by explicitly explaining the separation of concerns.

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?

Excellent guidance: explicitly states when to use this tool vs `create_note`, explains the design decision (create_note REFUSES unknown folders, so call this first to deliberately make the folder, then create the note). Also covers edge cases for path ambiguity and non-unique folder names.

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?

Despite having annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description goes well beyond what annotations convey. It details attachment handling behavior (local files attach, http links stay links, display sizes via pipe syntax), title extraction fallback logic, markdown flattening behavior (only ### and deeper flatten to ##), and returns the new note's ID. This is rich behavioral context that annotations alone couldn't 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?

The description is well-structured with clear sections (overall purpose, attachments, args). It front-loads the core purpose first. It's somewhat long but every sentence carries meaningful information for a tool with complex behavior. The attachment formatting section is dense but valuable given the complexity of that feature.

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 3 parameters, 0% schema coverage, no enums, and complex behavior, the description is remarkably complete. It covers attachment syntax variants, formatting preservation details, exact markdown conversion rules, folder ambiguity handling, and return value. The output schema presumably documents the returned ID, and the description confirms what's returned.

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 0%, so the description carries the full burden for all three parameters. It thoroughly explains title (bold first line shown in list, fallback extraction from first heading/line, never image), markdown (don't repeat title, use ## and ###, # renders as Title style), and folder (optional, name or full path, check list_folders, ambiguous rejected). Each parameter gets meaningful semantic guidance beyond just its string 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 creates an Apple Note from markdown with real formatting preservation. It goes beyond a simple verb+resource by distinguishing from AppleScript-based alternatives and detailing specific behaviors (headings, lists, tables, bold/italic survive as real objects). This is specific and clearly differentiates from siblings like edit_note and create_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?

Excellent guidance on when and how to use this tool. It explicitly tells users to check list_folders for existing folders, explains that ambiguous folder names are rejected not guessed, and gives detailed guidance on how to structure markdown (using ## and ### instead of #, not repeating the title). It also covers when folder is needed vs optional.

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 destructiveHint=true, but the description goes far beyond by explaining the mechanism: the note is deleted and recreated ('it gets a NEW note ID and a new creation date'), backed up first, and attachment preservation/removal behavior. This adds substantial value beyond the annotation by revealing the underlying destructive mechanism and side effects the agent must account for.

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 and appropriately sized for a complex destructive tool. It opens with a front-loaded single-sentence purpose statement, then uses a warning section for the destructive behavior, and a separate paragraph for attachment handling. Every sentence earns its place and nothing is redundant.

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 tool's complexity (destructive, backed-up, attachment-aware, new ID semantics), the description covers the essential behavioral contract comprehensively. It explains the return value ('Returns the new note's ID'), the backup path, the failure case (evicted attachment), and the standard workflow. The output schema exists, so return-format details aren't needed in the description.

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 completely carries the parameter meaning burden. The description explains 'markdown' semantics in detail: what must be preserved (attachment file:// lines) and how to remove attachments. It mentions title/folder are kept via description, and the title param exists with null default meaning 'keep as-is'. While it doesn't spell out every param's exact syntax, it compensates substantially for the 0% schema coverage.

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 what the tool does: 'Replace a note's body with new markdown, keeping its title and folder.' It uses a specific verb (replace) and identifies the resource (note body). It also distinguishes this from siblings by explicitly noting the markdown-based body replacement and title/folder preservation, contrasting with read_note and create_note.

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 guidance: 'The normal flow is to read_note, edit that markdown, and pass it back here.' It clearly explains the when (editing existing note body) and the workflow (read, edit, pass back). It also gives actionable mechanics on attachments and the exception case for iCloud-evicted attachments.

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 provide readOnlyHint=true and idempotentHint=true, so the read-only safety profile is covered. The description adds valuable context beyond those: the ambiguous-name-rejection behavior, the specific output format (tab-separated id/title/modified/snippet), sorted newest first, and the fact that subfolders come as full paths. It doesn't deeply describe depth or large-listing limits, but with strong annotations the added context is substantial, meriting 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?

Four sentences, all earning their place. Front-loaded with the core purpose, then schema-supplementing details on the parameter, output format, and sibling differentiation. Slightly dense with the tab-separated column enumeration, but every clause adds genuine value. No wasted words.

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?

There is an output schema, so return values need not be re-explained, but the description still covers the useful behavioral aspects: ordering, tab-separated field format, id reuse with read_note/edit_note, and the folder path semantics. For a single-parameter read-only listing tool with strong annotations and an output schema, this is 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 0%, so the description must fully compensate for the single folder parameter. It does: explains folder is 'a path (or a name, where unique) as shown by list_folders', notes ambiguity is rejected rather than guessed, and clarifies how subfolder values relate to descending. This adds meaning the bare schema property (title: Folder) entirely lacks. With 1 parameter and no enums, this is strong compensation.

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?

Description uses a specific verb+resource: 'List the notes and immediate subfolders inside folder'. It clearly distinguishes from siblings: list_folders (top-level listing), search_notes/search_note_text (text-based finding). The scope ('immediate subfolders', 'newest first') makes it unmistakable what this tool does and how it differs.

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 states when to use it: 'This is how to browse the library by structure, where search_notes/search_note_text find notes by their text.' This directly contrasts the structural-browsing use case against the text-search alternative, naming sibling tools. It also documents behavioral nuances (ambiguous names rejected, subfolders as full paths for re-descending).

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 openWorldHint=false, covering the safety profile. The description adds valuable behavioral detail beyond structured data: full paths output, non-unique folder names, and the rejection of ambiguous bare names rather than guessing. Strong complementary context.

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 paragraphs, each serving a distinct purpose: primary listing semantics, relational guidance with create_folder/create_note, and the ambiguity caveat. Slightly verbose but every sentence earns its place — the ambiguity explanation is genuinely important. Well-structured and front-loaded with 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?

For a 0-parameter, read-only list tool, the description is complete: it covers what's returned (paths, one per line), the non-uniqueness caveat, and downstream usage guidance. An output schema exists which likely documents the path list format further, reducing the need for the description to do more.

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 0 parameters, so the schema carries no parameter burden. Per rubric, 0 params warrants baseline 4. The description's focus on output path format adds value since there are no inputs to explain.

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 'List the folders a note can be filed into, as full paths, one per line' — a specific verb (list) plus specific resource (folders for note filing) with output format detail. It distinguishes itself from siblings like list_folder and search_note_text by its specific purpose of enumerating what create_note can target.

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 explicitly explains when to call this tool: before create_note, rather than guessing a folder name. It also names direct alternatives (create_folder for non-listed folders) and explains the ambiguity-handling behavior clearly. This is excellent guidance with explicit exclusions.

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=true annotation, the description discloses rich behavioral context: how checklists and numbered lists are preserved via protobuf reconstruction, how tables are sourced from HTML, how attachments are returned as file:// links, heading depth flattening behavior, and the degraded HTML fallback mode. It even explains the internally-consistent detail that edit_note won't rewrite from a degraded read.

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 substantial but every paragraph earns its place with concrete behavioral facts. It's front-loaded with the core purpose first ('Read a note as markdown'), then dives into specifics. Slightly dense but efficient—unusual formatting details (code backticks, em-dashes) serve clarity for an agent.

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 there is an output schema (meaning the description needn't explain return values), the description covers the key edge cases: protobuf vs HTML reconstruction, why HTML exports are inferior, heading depth flattening, attachment handling, and the fallback degradation state. For a read tool with one parameter, this is highly 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 description coverage is 0% with only one parameter (note_id). The description doesn't explicitly describe note_id's format, but for a single obvious resource identifier, the description's extensive context about behavior largely compensates. The high behavioral detail offsets the lack of explicit parameter documentation, though it could mention what note_id format is expected.

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 tool reads a note as markdown for inspecting or editing, with a specific verb+resource+format. It distinguishes itself from siblings by detailing the markdown reconstruction approach and explaining how it differs from edit_note's requirements.

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 explicitly explains when this tool is appropriate (for inspecting or editing a note) and contrasts it with edit_note, noting edit_note refuses to run when the protobuf cannot be read. It provides clear context about fallback behavior and the read-side vs write-side loss distinction.

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 readOnlyHint and idempotentHint annotations already cover the safety profile. The description adds valuable context beyond annotations: that the returned `id` is the only way to obtain a note ID needed by read_note/edit_note, and that the snippet and other fields help distinguish same-titled notes. It also discloses the sort order (most recently modified first) and output format (tab-separated with a date format).

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 efficiently written, front-loaded with the core purpose in the first sentence, followed by the return format and usage guidance. Every paragraph earns its place — the return-format detail, the id significance, and the fallback guidance are all substantive. Slightly verbose in places but no wasted 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?

This is a rich description for a search tool: it specifies the sort order, output format with column details and date format, what the id is used for (relationship to read_note/edit_note), when to fall back to the sibling tool, and the semantic meaning of 'no matches'. The presence of an output schema reduces the need to further describe returns. This is complete for this tool's complexity.

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 0%, so the description must compensate. It explains `query` semantics well ('title contains query') but does not explain `limit` beyond what the schema's default of 10 implies. The description is thorough about output columns but lighter on the limit parameter. Still, the query parameter is well-covered.

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 specifies 'Find notes whose TITLE contains query, most recently modified first' — a specific verb ('find/search'), resource ('notes'), and scope filter ('TITLE contains query'). It distinguishes from the sibling search_note_text by explicitly noting it searches titles only vs bodies.

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?

Explicit when-to-use guidance is present: 'If it returns no matches -- or you are after notes that mention something rather than are titled after it -- fall back to search_note_text.' It also warns that 'no matches' doesn't mean content is absent, clarifying a critical semantic nuance.

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, so the description need not restate safety. It adds genuinely useful behavioral context: same row format as search_notes, ordering (most recently modified first), and that matching operates on plain text so formatting doesn't affect results. A small step beyond annotation coverage, hence a strong 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 three sentences, front-loaded with the core purpose in sentence one, then formatting/ordering details, then usage guidance. Every sentence earns its place with zero redundancy 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?

The tool has an output schema (covering return format), 2 simple params, and rich annotations (readOnly, idempotent, openWorld=false). The description covers search scope, ordering, plain-text matching, and sibling distinction. Slightly short of a 5 only because limit behavior could be spelled out, but overall complete for this tool's complexity.

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 for the undocumented parameters. The description clarifies 'query' semantics (matches against title and body text, plain-text based) but does not explain the 'limit' parameter's behavior beyond the schema's default of 10. Given two params with one well-explained and the other left to its visible default, a baseline 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?

Description clearly states the tool performs full-text search over note text (title and body), with the specific verb 'find' and the resource 'notes whose TEXT'. It explicitly distinguishes from sibling search_notes by contrasting text-mention searching vs title searching, making purpose and differentiation 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?

Explicit guidance is provided: 'Use this when looking for notes that *mention* something rather than notes titled after it; use search_notes when you know the title, as it is faster.' This gives clear when-to-use AND when-not-to-use with an alternative named, which is exemplary.

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