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

With no annotations, the description carries the transparency burden. It discloses that the fragment is pasted at the caret, the rest of the note is untouched, and styles/attachments are preserved. It also hints at the true_styles behavior by contrasting with an alternative rewrite path, adding valuable behavioral context beyond a basic 'append' statement.

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 sentences, front-loaded with the core purpose and immediately clarifying scope. No redundant wording; every clause adds meaning (Markdown format, preservation, caret behavior). It is appropriately sized for a moderately 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?

Given the tool's complexity (5 params, no annotations, no output schema), the description covers the key usage context and behavioral nuances. The schema fills in parameter details, and the description clarifies the core append semantics and preservation guarantees. It could mention return values or error handling, but the lack of an output schema makes that less critical.

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 adds minimal semantic value beyond the schema, only noting that the text is Markdown 'like create_note's body,' which helps clarify the text parameter but doesn't significantly compensate for the other parameters. The schema itself already provides detailed descriptions, especially for true_styles.

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 action (append to the end of an existing note) with a specific verb and resource. It also distinguishes from siblings by emphasizing that the rest of the note is untouched and that the text is Markdown like create_note's body, which differentiates it from update_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 gives clear context for when to use this tool (appending to an existing note while preserving existing content) but does not explicitly name alternatives or state when not to use it. The mention of 'like create_note's body' implies consistency with create_note, but explicit exclusions are absent.

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?

With no annotations, the description carries the burden of behavioral disclosure. It does add useful context about title handling and Markdown conversion, but it omits other behavioral traits like potential side effects (e.g., driving the Notes app, creating folders) or permission requirements, which are only in the schema.

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 only two short sentences, front-loaded with the primary purpose. Every word adds value, and there is no 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?

While the description is minimal, the rich schema descriptions for all six parameters fill in necessary details like attachment handling, folder behavior, and automation side effects. The description itself covers the core creation and formatting behavior, so combined with the schema it is largely complete, though it lacks high-level context about when this tool is appropriate.

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 goes further by describing how 'title' becomes the first line and detailing the Markdown features supported in 'body', adding meaning beyond the schema's parameter 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 clearly states 'Create a new note' with specific behaviors (title becomes first line, body as Markdown). It clearly identifies the action and resource, though it does not explicitly contrast with siblings like append_note or import_note, so it misses a point on 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?

The description provides no guidance on when to use this tool versus alternatives such as append_note, update_note, or import_note. It only states what it does, not the circumstances that make it the right choice.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly states that the tool rewrites only files it previously wrote, refuses any other existing file rather than overwriting it, and stamps files for `pull` to keep them updated. These are crucial behavioral traits that inform the agent about safety and idempotency.

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 long, with the core action front-loaded in the first sentence. Each subsequent sentence adds meaningful detail about attachment handling, overwrite safety, and the pull stamp, with 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?

The description covers the essential aspects: purpose, attachment persistence, overwrite behavior, and the update stamp. The only missing piece is a description of return values or error handling, but since no output schema is provided, this is a minor gap for a tool of this 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?

The schema covers 100% of the parameters with descriptions, so the tool description does not need to add much parameter-specific meaning. The description does not delve into how id/name/dir/file interact, but the schema descriptions already provide sufficient semantics for each field. Thus, the baseline of 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?

The description uses a specific verb ('Write' a note to 'a new Markdown file') and names the resource directly, making the tool's purpose unambiguous. It also distinguishes itself from siblings by claiming to be 'the one way attachment bytes reach disk,' which highlights its unique niche.

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 phrase 'The one way attachment bytes reach disk' explicitly tells the agent when to use this tool—any time attachments must be persisted to disk, there is no alternative. 'Later passes keep it up to date' also indicates that this tool is suitable for ongoing export/sync workflows. Although it doesn't name sibling tools, it provides a clear when-to-use directive.

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?

With no annotations, the description carries the burden of behavior. It discloses that bytes are returned exactly as Notes holds them, with original name/type, and explains how drawings are rendered. This goes beyond a generic 'fetch' but stops short of detailing error behavior or response wrapping.

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 sentences, front-loaded with the main action and context, and the second sentence adds an important edge-case behavior. Every sentence contributes value 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 fetch tool with no output schema or annotations, it covers the core return semantics (bytes, name/type, drawing behavior) and references the prerequisite list_attachments. Missing details include how errors are surfaced and whether bytes are encoded, but the description is reasonably complete for its scope.

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 the baseline is 3. The description reinforces that 'index' is a position in list_attachments, which is already in the schema, and adds little new parameter-level meaning. It does not clarify id/name/folder roles beyond what the schema states.

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 ('Fetch') and resource ('attachment of a note') with a clear scope ('by its index in list_attachments'). It distinguishes itself from siblings like list_attachments and get_note by focusing on fetching one attachment's byte content.

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 intended workflow: first call list_attachments to obtain the index, then call get_attachment with that index. It does not explicitly list alternatives or exclusions, but the mention of list_attachments provides clear context on when this tool 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?

With no annotations, the description reveals critical behavior: Markdown body never repeats the title, rich:false indicates degraded format, attachments appear as placeholders never bytes, and format=html switches to raw HTML. This is thorough and goes well beyond a simple 'read' statement.

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 compact but information-dense. Every sentence serves a purpose: identification, return format, degraded behavior, attachment handling, and export alternative. No redundant phrases.

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 tool with four optional parameters and no output schema, the description covers identification methods, body format, failure mode (rich:false), attachment limitations, and a relevant alternative. It is entirely self-sufficient for an agent to invoke correctly.

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?

Although schema covers all four parameters, the description adds meaning: clarifies id over name, mentions 'ambiguity returns candidates' for name, and explains format options (markdown full-fidelity store read vs html exported body). This significantly enhances understanding of how parameters affect output.

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?

Clearly states 'Read one note by id (preferred) or by title' – a specific verb and resource. It distinguishes from siblings by focusing on reading a single note and explicitly names export_note for copying, avoiding overlap.

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 explicit preference ('by id (preferred)'), notes ambiguity handling ('ambiguity returns candidates'), and directs users to export_note for copying attachments to disk/vault. This constitutes clear when-to-use and an explicit alternative.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It discloses two important behaviors: image links become real attachments, and an existing name is refused (no overwrite). It omits details about source file handling or return values, but the core safety profile is well covered.

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 concise sentences, front-loaded with the core action. Each sentence adds meaningful information without 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?

For a mutating import tool with no annotations, the description covers purpose, key transformations, and safety constraints. It avoids explaining return values (no output schema) and relies on the schema for parameter details, which is acceptable. The sibling context clarifies the tool's place among other note operations.

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 provides descriptions for all four parameters, so the description does not need to repeat them. The description adds no parameter-specific meaning beyond the schema, so a baseline score of 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 tool's function with a specific verb ('Create') and resource ('a new note'), and adds the source material ('Markdown file'). It also highlights unique features (image links become attachments, refusal on existing names) that distinguish it from sibling tools like 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 implies usage for importing a Markdown file into a note, but it does not explicitly state when to prefer this over alternatives like create_note or append_note. No exclusions or alternative tool references are provided.

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?

With no annotations provided, the description takes on the full transparency burden. It discloses ordering semantics (entry n corresponds to mark n), the table exclusion, and implies a one-to-one mapping. It does not explicitly state read-only behavior or error handling, but the core behavioral traits are conveyed.

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 concise sentences: definition, ordering rule, and exclusion/alternative. Every sentence contributes meaningful information 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 list operation with no output schema or annotations, the description covers the essential context: what is listed, how entries map to marks, what is excluded, and a pointer to get_attachment. It lacks an explicit return shape but is sufficient for an agent to select and invoke the tool correctly.

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%: all three parameters (id, name, folder) are already well-described, including priority and disambiguation. The description adds no parameter-specific semantics, so the baseline of 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?

The description clearly states the tool's function: enumerating a note's non-text attachments (images, scans, drawings, files). It differentiates from siblings by explaining the per-mark correspondence and explicitly pointing to get_attachment for individual access, making the purpose specific and distinct.

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 gives explicit usage context, including an important exclusion (tables are not listed because their mark becomes pipe rows) and names get_attachment as the alternative for examining one attachment. This tells the agent when to use this tool vs. the sibling 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?

With no annotations, the description must carry the behavioral transparency burden. It does disclose the output scope ('every folder') and includes return details ('path and note count'), which is helpful. However, it does not explicitly state that the operation is read-only, has no side effects, or what happens with empty folders or errors, leaving some gaps.

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 a single concise sentence that communicates the core purpose and key output fields. It is front-loaded and free of filler, making it easy for an agent to parse quickly.

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 simplicity (no parameters, no output schema), the description provides sufficient context: it enumerates folders and specifies the returned fields. It could enhance completeness by noting whether folders are nested or whether the count includes subfolders, but for a basic listing tool it is largely 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?

The tool has zero parameters, so the schema is trivially complete. The description does not need to explain parameters, and the baseline for no-parameter tools is 4. It appropriately focuses on the return value instead, adding meaning about what the result contains.

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's function: 'List every Apple Notes folder with its path and note count.' It uses a specific verb (List) and resource (Apple Notes folder), and the inclusion of 'path' and 'note count' distinguishes it from sibling tools like list_notes, which lists notes rather than folders.

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 usage: an agent would call this when needing to enumerate folders. However, it does not explicitly mention alternatives or when not to use it, such as if only a specific folder is needed. This falls short of the explicit guidance seen in higher-scoring tools.

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?

No annotations provided, so description carries full burden. It discloses ordering and trash exclusion, adding useful behavior beyond a bare 'list notes.' However, it doesn't describe return format or pagination behavior beyond limit parameter in schema.

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, each adds distinct information: action+ordering, optional scoping, trash exclusion. No filler or repetition.

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 list tool with two optional params and no output schema, the description covers the core behavior well. Missing details like returned fields, but the sibling get_note implies list returns summaries; still, the description is fairly complete for typical 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?

Input schema provides complete descriptions for both parameters (limit: max rows/default 25; folder: from list_folders), giving 100% schema coverage. The description's mention of folder scoping adds only slight emphasis but no new parameter-specific 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?

Description uses specific verb 'List' with resource 'notes', states ordering ('newest first') and scope ('Optionally scoped to one folder'). This clearly distinguishes from siblings like get_note (single note) and search_notes (search).

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?

Conveys clear context: lists notes with optional folder scoping and trash excluded. However, it does not explicitly name alternatives or state when not to use (e.g., for full-text search use search_notes).

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?

With no annotations, the description carries the transparency burden. It discloses that body search is slower, refers to a 'capped scope', and clarifies the output fields (total and notes). This adds useful behavioral context beyond a simple 'search' statement.

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 concise sentences that front-load the purpose and then clarify the output shape. No redundant information; every clause serves a purpose.

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 is largely complete for a search tool: it explains the two modes, output structure, and performance implications. However, the phrase 'capped scope' is ambiguous, and since there's no output schema, the return format is only briefly described, leaving minor gaps.

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 covers all four parameters with descriptions, but the description adds meaning by explaining the effect of search_body (slower, capped scope) and how limit relates to the returned notes array. This goes beyond the schema's raw parameter 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 clearly states the tool searches notes by title, with an optional body mode. It distinguishes from siblings by specifying search semantics (title vs body) and output structure, making its purpose 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 implies the tool is for searching notes when you need to find specific content, but it does not explicitly compare with list_notes or other alternatives. It provides a condition (search_body=true) and performance caveat, but no when-not-to-use 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?

With no annotations provided, the description fully covers behavioral details: opt-in via frontmatter, name matching requirement, consequences of renaming, folder mirroring behavior, attachment handling, and a clear statement that 'Deletions never propagate.' This goes beyond typical tool descriptions.

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 concise yet comprehensive, opening with a succinct high-level summary ('One pass over a folder of .md files, one direction per file') and then adding necessary detail without redundancy. Every sentence contributes essential information about sync behavior, edge cases, or options.

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 moderate complexity (3 parameters, no output schema), the description covers all critical aspects: sync direction, frontmatter control, name matching, failure reporting, folder mirroring, and deletion policy. It leaves no major behavioral gaps for an AI agent to infer.

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%, with each parameter already well-described. The tool description adds process context but not additional per-parameter details beyond what the schema provides. For example, the description explains the folder parameter's behavior, but the schema already states that notes without a file are created as pull files.

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's primary function: 'One pass over a folder of .md files, one direction per file.' It specifies the resource (folder of .md files) and verb (sync) with operational detail, and the frontmatter-driven direction distinguishes it from siblings like get_note or update_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 clear context for when to use this tool (e.g., to sync markdown files with Notes) and even explains the folder mirroring use case. However, it does not explicitly contrast with sibling tools like sync_status, which might be the alternative for checking sync state.

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?

No annotations are provided, so the description carries the full burden. It discloses the key non-destructive behavior ('without writing anything'), which is critical. However, it doesn't mention whether the dry-run still makes remote reads, requires authentication, or how the report is structured, leaving some behavioral gaps.

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 a single, efficient sentence. The key qualifier 'Dry-run' is front-loaded, and every word adds value 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 tool with two optional parameters and no output schema, the description adequately conveys the purpose and the critical no-write guarantee. It could benefit from a small note on the report format, but the phrase 'reports what would be pushed, pulled or created' provides sufficient context.

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 both parameters ('dir' and 'folder') are already fully documented in the input schema. The description adds no additional parameter semantics, which is acceptable given the baseline of 3.

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 ('reports') with a clear resource ('what would be pushed, pulled or created') and explicitly identifies as a dry-run of sync_now, clearly distinguishing it from the execution sibling.

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 phrase 'Dry-run of sync_now' signals this is a preview companion to sync_now, implying it should be used to check effects before executing. It doesn't explicitly state exclusions or name alternatives, but the relationship 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?

With no annotations, the description carries the burden. It explicitly discloses that the old body is overwritten (destructive) and that the title is preserved unless a new one is provided. It does not mention the behavioral caveats of the attach and true_styles parameters, but those are well-documented in the schema.

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 concise and front-loaded: it states the core action and key side effects in four short sentences. There is no redundant or filler content.

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 gives a solid high-level overview covering the destructive nature and title behavior, but it omits mention of optional behaviors like attachments or true paragraph styles. However, the schema provides those details, so the description is sufficiently complete for an agent that reads the schema.

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 parameters are fully described. The description only reiterates that the body is Markdown, which the schema already states. It adds no additional semantic value beyond what the schema already provides.

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 ('Replace') with a clear resource ('a note's body'), immediately distinguishing it from append_note or create_note. It also states the destructive side effect, which gives a unique purpose signature.

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 clearly conveys when to use this tool: to overwrite a note's body while optionally changing the title. It mentions Markdown compatibility with create_note, but does not explicitly contrast with append_note or list exclusions, so it falls just 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.