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

No annotations are present, so the description carries full burden. It discloses key behavioral traits: HTML content with newline constraint, disk snapshot before modification, failure without altering note when zero/multiple matches, and the resolved scope behavior with folder. This is exceptionally transparent for a mutation tool.

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 dense sentences, each earning its place. The core action leads, followed by constraints, failure semantics, and a practical recommendation. No fluff 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?

The tool is moderately complex with failure modes and an optional folder scope. The description covers the operation, content constraints, failure conditions, scope resolution, and a usage recommendation. Output schema exists, so return values don't need elaboration. Complete for an agent to select and 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?

Schema coverage is 0%, so the description must compensate. It explains `title` requires exact match, `content` must be HTML without newlines, and `folder` acts as a scope limiter (whole app if omitted, otherwise a specific folder). This adds significant meaning beyond the bare schema, though a bit more on content format could push it to 5.

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 ('Append') and resource ('body of an existing Apple Note') with a clear matching criterion ('exact title'). It clearly distinguishes from sibling tools like create-note and 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 explicitly advises passing `folder` when known and explains the failure mode when zero or multiple notes match. While it doesn't name alternatives directly, the scoping and disambiguation guidance are clear. It could be stronger by explicitly contrasting with create-note or update-note, but the usage context is well 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?

No annotations are provided, so the description must convey behavior. It discloses side effects (writes to disk, returns file path), failure modes (zero or multiple title matches), and scoping behavior via folder. It stops short of explicitly stating that the note is not modified, but 'snapshot' strongly implies non-destructiveness.

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 sentences, with the core action front-loaded. No redundant phrases. Every clause adds value, from the action to the failure conditions to the parameter guidance.

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 a 2-parameter tool with an output schema, the description covers purpose, usage timing, error behavior, and parameter semantics. It also notes the folder scoping option. The output schema supplies return type, so the description need not repeat it.

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%, but the description fully compensates: 'matched by exact title' explains the title parameter, and 'Pass `folder` to scope the lookup to a single folder' explains the folder parameter. Both parameter meanings are clarified beyond the bare schema.

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 verb 'Snapshot', the resource 'HTML body of a note', and the action 'to disk and return the file path'. It also specifies exact-title matching, which 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?

Provides explicit usage context: 'Useful before risky multi-step edits.' It also explains failure conditions and folder scoping. However, it does not explicitly mention when NOT to use it or name alternative tools, so it lacks full 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds one important constraint ('Content must be HTML without newlines') but does not describe other behavioral aspects like whether the note is created in a default folder, what the response or output contains, or any side effects or permissions required.

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 extremely concise: two short sentences that immediately state the core purpose and the key constraint. Every word adds value, and the critical content rule is front-loaded, making it efficient for an agent to parse.

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 create-note tool, the description covers the essential operation and the one critical input constraint. However, it lacks context about how this tool differs from 'create-note-in-folder' and does not mention output behavior. Since an output schema exists, return values need not be described, but the sibling differentiation gap makes it incomplete.

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 does add semantics for the 'content' parameter by specifying the HTML and newline constraints, but it provides no additional meaning for the 'title' parameter, leaving it only as a string type in the schema.

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 and resource: 'Create a new Apple Note.' It is specific enough to indicate the tool creates a note, but it does not explicitly differentiate from the sibling 'create-note-in-folder' by noting the default location or absence of folder selection.

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?

No guidance is provided on when to use this tool versus alternatives such as 'create-note-in-folder' or 'append-note'. The description lacks any contextual or conditional information that would help an agent choose this tool over its siblings.

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. It discloses two key behaviors: the HTML-without-newlines constraint and the failure when the folder doesn't exist. However, it omits other relevant context such as authentication requirements, idempotency, or response shape, but those partially covered by output schema. Overall, moderate transparency.

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 with no fluff. The purpose is front-loaded, and each sentence contributes: purpose, content constraint, and failure mode with mitigation.

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 3-param create tool with an output schema, the description is adequately complete. It covers the core purpose, key input constraints, and a common error condition. It doesn't explain folder format or return value, but the output schema likely covers the latter. Slight gap in folder parameter semantics.

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 has 0% coverage, so the description must compensate. It adds meaning for 'content' (must be HTML without newlines) and 'folder' (must exist). It does not clarify whether folder expects a name or ID, and gives no detail on 'title'. Partial compensation, but gaps remain.

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 'Create a new Apple Note inside a specific folder,' using a specific verb and resource that distinguishes it from siblings like create-note. The scope ('specific folder') is explicit.

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 clear usage context: use this tool to create a note in a specific folder, and indicates a prerequisite: check list-folders first to avoid failure. It does not explicitly name alternatives like create-note, but the guidance is helpful.

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 burden. It discloses a key behavioral trait: without a folder, homonyms in other folders/accounts may shadow the target note. This goes beyond the generic 'get' operation and adds valuable context, though it doesn't mention read-only nature or error handling, which are less critical given the output 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 two sentences, front-loaded with the core action, and efficiently communicates the primary purpose and the optional parameter's rationale. Every word earns its place with no fluff.

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 2-parameter tool with an output schema, this description covers the essential purpose and behavioral nuance. The folder scoping warning is especially valuable for avoiding pitfalls. No additional context seems 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?

With 0% schema description coverage, the description fully compensates. It explains that 'title' is an exact match and that 'folder' scopes the lookup, including the shadowing caveat. This provides meaningful semantics beyond the raw schema field names and types.

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 'Get a note's full content and details by exact title' with a specific verb ('Get'), resource ('note'), and qualifier ('full content and details', 'exact title'). This clearly differentiates from siblings like search-notes (searching) and list-notes (listing), as it focuses on retrieval by exact title.

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 the tool: when you need full content by exact title. It also provides guidance for the optional folder parameter, advising to pass it to avoid homonym shadowing. However, it does not explicitly compare to alternatives or state when not to use it, which would earn 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?

No annotations are provided, so the description must disclose behavioral traits itself. It mentions that indexing can take from seconds to minutes and instructs to inform the user, which is useful. However, it does not disclose side effects, permissions, or whether the operation is read-only or destructive, leaving some transparency 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 two sentences, front-loaded with the action and purpose, and includes a practical user-facing instruction. Every sentence adds value with no 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?

Given the tool's simplicity, zero parameters, and presence of an output schema, the description adequately covers the core purpose and a key user experience note. It could mention side effects or return behavior, but the essential information is present.

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 and the schema is empty, so the baseline per instructions is 4. The description adds no parameter-specific detail, but none is needed.

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 indexes all Apple Notes for semantic search, using a specific verb and resource. It is distinct from sibling tools like list-notes or search-notes, which perform different operations.

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 explains that indexing is done for semantic search and instructs the user to tell the user about potential duration, implying when to use it. However, it does not explicitly mention alternative tools or when not to use it, though the context is clear.

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 full responsibility for behavioral disclosure. It only states the action without addressing read-only nature, error behavior (e.g., folder not found), or any side effects. This is a significant gap for a tool with zero annotation coverage.

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 with front-loaded information. Every word is purposeful and there is no redundancy or unnecessary 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 simple one-parameter list tool with an output schema, the description covers the core purpose and return scope (titles in a folder). However, it lacks context about folder validation, empty results, or edge cases. Without annotations, more behavioral context would improve completeness.

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%, and the description only mentions 'named' Apple Notes folder, implying the 'folder' parameter is a folder name. It does not clarify whether it should be the exact name, ID, or path, nor does it specify case sensitivity or existence requirements. The description adds minimal meaning beyond the schema.

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 ('List') and resource ('titles of all notes inside a named Apple Notes folder'), clearly distinguishing it from siblings like list-notes (which likely lists all notes) and list-folders. The scope 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 no guidance on when to use this tool versus alternatives such as list-notes or search-notes. It implies usage via 'inside a named Apple Notes folder' but does not explicitly state when this is preferred or when other tools should be used.

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 carries the full burden. It states this is a read-only operation ('Return the names'), but does not disclose potential edge cases (e.g., empty folders, ordering, hidden folders) or any other behavioral traits. It is minimally transparent but not rich.

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, front-loaded with the key action and resource. 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?

For a simple list tool with no parameters and an output schema available, the description is sufficiently complete. It unambiguously states what the tool returns, and the output schema likely covers any return format details.

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 fully covered. No parameter explanation is needed, and the description aligns with this. Baseline for 0 params is 4.

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 verb 'Return' and the resource 'names of all Apple Notes folders'. This distinguishes it from sibling tools like list-notes, which lists notes, and list-folder-notes, which lists notes within 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?

The description gives no explicit guidance on when to use this tool versus alternatives. It implies usage for retrieving all folder names, but does not mention exclusion criteria or compare it to related folder 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?

With no annotations, the description carries the full burden of behavioral disclosure. It clarifies that the count is of the local index, but it does not indicate the return format (count vs. list), which conflicts with the tool name, nor does it mention side effects, freshness, or performance characteristics.

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, front-loaded sentence with no redundant words. It efficiently states the core function and scope, earning full marks for conciseness.

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 is simple with no parameters and has an output schema, so a brief description might be sufficient. However, the mismatch between the tool name and description, combined with the lack of usage guidance, leaves gaps in completeness that prevent a higher score.

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, and the schema coverage is 100% (empty schema). With no parameters to document, the description need not add parameter details, so the baseline score of 4 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 states a specific action ('Count the notes') and scope ('currently in the local index'), which clearly differentiates it from sibling tools like get-note or search-notes. However, the tool name 'list-notes' implies enumeration rather than counting, creating some ambiguity about the actual return value.

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?

No guidance is provided about when to use this tool versus alternatives such as search-notes or index-notes. There are no mentions of exclusions or conditions that would help an agent decide between 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?

With no annotations, the description carries the full burden. It discloses key behaviors: exact title matching, folder scoping, and failure conditions (missing, ambiguous, destination nonexistent). It doesn't state outcomes like whether the note is removed from the source folder, but the act of moving is clear and the output schema likely covers return values.

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 primary action, then the optional parameter caveat, then failure conditions. Every sentence adds value with no redundancy or filler, making it efficient and easy to parse.

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, no annotations, and an output schema present, the description covers the main behavioral contract: what it does, how to disambiguate, and when it fails. It doesn't elaborate on return values, but the output schema can address that. The main gap is absence of details about how 'folder' names are resolved (e.g., exact match vs. case-insensitive), but this is a minor 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 coverage is 0%, so the description must explain parameters. It does: 'title' is the exact title to match, 'folder' is the destination, and 'source_folder' scopes the lookup to avoid homonym ambiguity. This gives meaning beyond the bare schema properties, though it doesn't detail edge cases like case sensitivity or folder naming formats.

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 moves an existing Apple Note by exact title into a destination folder. The verb 'Move' and resource 'Apple Note' specify the action and target, and details like 'matched by exact title' and failure conditions distinguish this from sibling tools like update-note or get-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 the tool (moving notes between folders) and explains the optional source_folder for disambiguation. It doesn't explicitly name alternatives but implies that moving is distinct from other note operations, and the context is sufficient to infer the intended use.

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 full burden. It discloses the hybrid vector + full-text search behavior, which is valuable, but does not mention any other behavioral aspects (e.g., read-only, result limits). The disclosure of the hybrid method adds meaningful context beyond the tool name.

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, well-front-loaded sentence with zero waste. It states the primary action, the target, and the key behavioral nuance (hybrid search) in a compact form.

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 has one parameter and an output schema exists, the description covers the essential context: what the tool does and its unique search method. It does not detail output format, but that is not required when an output schema is present.

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 only one parameter with no description, but the tool description explains that the query is used for searching 'by meaning and by text', giving purpose to the parameter. This compensates for the 0% schema description 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 uses a specific verb 'Search' with a clear resource 'notes' and distinguishes the tool by specifying the hybrid method ('by meaning and by text (hybrid vector + full-text search)'). This clearly sets it apart from siblings like list-notes or get-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 when to use the tool: when you need to find notes by meaning or text. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide between search and other note-related 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 critical behaviors: content must be HTML without newlines, the current body is snapshotted to disk before overwrite, and the operation fails atomically ('leaves the note untouched') on ambiguity. This exceeds expected transparency.

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 information-dense with no fluff, but the final sentence about eliminating spurious errors could be seen as slightly redundant given the earlier failure explanation. Still, it earns its place by providing reasoning. Overall well-organized with purpose first, then constraints, then usage tip.

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 mutation tool with no annotations, the description covers all necessary context: what it does, input constraints (HTML, no newlines), side effects (snapshot), failure modes and conditions, and scope resolution. The output schema exists, so return values need no explanation. This is a fully specified 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 description must compensate. It does so thoroughly: 'title' is exact title match, 'content' is HTML without newlines, and 'folder' is optional scope with clear default behavior (whole Notes app vs a specific folder) and concrete rationale for passing it.

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 verb+resource: 'Replace the body of an existing Apple Note matched by exact title.' This distinguishes it from siblings like append-note (append) and create-note (create). The exact-title matching criterion adds specificity.

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 instructs when to use the tool and how to avoid errors: 'Pass folder whenever you know which folder the target note lives in.' It also explains failure conditions ('Fails if zero or multiple notes share the title') and the resolved scope behavior, which serves as 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.