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

With no annotations, the description bears full responsibility for behavioral traits. It covers duplication detection, validation rules (128 chars, no special chars), nesting depth limit, and error handling when parent path doesn't exist, leaving no ambiguity.

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, well-structured with bullet points, and front-loaded with the core purpose. Each sentence adds necessary information without redundancy, making it efficient for agent parsing.

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 two parameters, no annotations, and an output schema (which presumably describes return structure), the description fully covers creation behavior, constraints, validation, and error scenarios, leaving no gaps for an agent.

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 schema already documents both parameters. The description adds value by explaining the nesting behavior (e.g., 'Optional nested path... Max 5 levels deep') and repeating key validation, which aids understanding beyond the schema alone.

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 folder in Apple Notes' and lists features that differentiate it from sibling tools like move_folder, rename_folder, etc. It specifies root-level and nested path creation, which is 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 explains when to use the tool (create folders at root or nested) and includes validation rules and error conditions. While it doesn't explicitly state when not to use or cite alternatives, the context is clear enough for an agent to decide.

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 cover behavioral traits. It discloses supported HTML tags, folder depth limits, and name character restrictions, but does not mention idempotency, overwrite behavior, or error handling. The output schema exists, so return values are not required in the description.

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 structured with headings and contains useful examples, but it is somewhat lengthy. While every part adds value, it could be more concise without losing clarity.

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 (3 parameters, output schema present), the description covers creation details, HTML formatting, folder paths, and limitations. It lacks clarity on duplicate behavior and permissions, but overall is fairly 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 100%, providing clear parameter meanings. The description adds value by elaborating on HTML support, example usage, folder path default and nesting limits, which goes beyond the schema's baseline.

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 explicitly states 'Create a new note with specified name and content,' clearly distinguishing it from sibling tools like update_note (update) and create_folder (create a folder, not a note). It also provides specifics about HTML support and folder structure.

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 offers best practices (e.g., using semantic HTML, adding <br> for spacing, avoiding CSS) and explains folder path limitations. While it doesn't explicitly list when not to use, the context from sibling tools and the clear purpose make usage guidelines adequate.

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

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

The description discloses several behavioral traits: verification of folder existence and name matching, use of AppleScript, and detailed error messages. However, it does not specify whether deletion is permanent or moves to trash, what happens if the folder is not empty, or potential platform dependencies (AppleScript). With no annotations, this leaves 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 moderately concise but includes redundant bullet points (e.g., AppleScript verification mentioned twice). It could be more streamlined while retaining key information.

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 states the output includes folder name, ID, deletion status, and method info, which is adequate for a simple mutation tool. However, missing details about edge cases (e.g., non-existent folder, non-empty folder) and platform constraints limit 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?

The description adds meaning beyond the input schema by explaining that folder_name is used for verification and folder_id for precise identification. This contextualizes both parameters beyond the schema's basic 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 deletes a folder in Apple Notes by ID, using AppleScript verification. It specifies the verb 'delete' and the resource 'folder in Apple Notes', and distinguishes from siblings like rename_folder or move_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 implies usage for deleting a folder but does not provide explicit guidance on when to use this tool versus alternatives (e.g., delete_note). It lacks context on prerequisites or situations where deletion might be inappropriate, such as non-empty folders.

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 security features like existence and name verification, AppleScript handling, and error messages. This adds transparency beyond the basic 'delete' operation.

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 moderately concise with structured sections for security features and output. It front-loads the primary action. Some redundancy exists in listing security features twice, but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (delete with verification) and the presence of an output schema (not shown but indicated), the description covers the main behavior, parameters, safety checks, and output details. Minor gaps like edge cases or prerequisites are absent but not 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% with descriptions like 'Primary key ID of the note to delete (e.g., 'p1308')' and 'Name of the note to verify and delete'. The description adds context about verification but does not significantly extend parameter 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?

The description clearly states the action 'Delete a note by its primary key ID' and specifies the resource (note) and method (AppleScript verification). It distinguishes from siblings like 'delete_folder' and 'update_note' by focusing on deletion with verification.

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 (when you need to delete a note) but does not explicitly state when not to use or provide alternatives from the sibling list. No guidance on prerequisites or context like ownership or permissions.

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 burden. It discloses inclusion of 'Recently Deleted folder' but does not mention whether the operation is read-only, requires authentication, or has performance implications. Basic behavioral details are present but incomplete.

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 separate sections for features, output format, and returns. It is concise but has minor redundancy (e.g., 'List all notes across all folders' appears twice).

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, output schema exists), the description is complete. It explains behavior, scope, and return format, covering all necessary context for a listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters with 100% schema coverage (vacuously). Baseline for no parameters is 4, and the description adds no parameter information because none exist.

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 all notes across all folders with their names and IDs', using a specific verb ('list') and resource ('notes across all folders'). It distinguishes from sibling tools like 'list_notes_with_structure' and 'search_notes' by emphasizing comprehensive scope including 'Recently Deleted 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 implies use for a 'comprehensive system overview' but does not explicitly state when to use this tool versus alternatives. No exclusions or when-not-to-use guidance is 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?

No annotations are provided, so the description must convey behavior. It describes output format (tree with ├── and └──), nesting levels, and that it works with root and nested structures. This adds meaningful behavioral context beyond a simple 'list folders'.

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 sections for features, output format, and returns. It is somewhat verbose (repeats 'tree structure'), but the organization aids readability. Could be trimmed slightly.

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 an output schema exists, the description explains the output format in detail. It covers what the tool does and key features. For a read-only listing tool, it is sufficiently 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?

There are zero parameters, and schema coverage is 100%. The baseline for 0 parameters is 4. The description adds value by explaining the tool's behavior, which is not parameter-dependent.

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 lists the complete folder structure in a hierarchical tree format. The name itself is descriptive, and the description emphasizes the tree visualisation, distinguishing it from sibling tools like 'read_folder' which likely shows a single 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 describes features but does not explicitly state when to use this tool over alternatives. It implies usage for viewing hierarchy, but lacks explicit guidance on when not to use it (e.g., for individual folder details).

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 transparency burden. It explains the output format and that it lists all folders and notes, but does not mention if it's read-only, performance implications, or any limitations.

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 well-structured: a clear purpose, bullet features, output format, and return statement. Every sentence is useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and an output schema available, the description is fairly complete. It covers purpose and output format, but could mention read-only nature or any constraints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the baseline is 4. The description does not need to explain parameters, and it adds value by describing the output format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists the complete folder structure with notes in a hierarchical tree format, distinguishing it from siblings like list_all_notes (flat list) and list_folder_with_structure (single 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 outlines features but does not explicitly state when to use this tool versus alternatives like list_all_notes or list_folder_with_structure. Usage context is implied but not directly given.

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

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

Given no annotations, the description fully discloses behavioral traits including AppleScript verification, validation, duplicate detection, Unicode support, and nesting depth limit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with headings and bullet points, front-loaded main action. Slight redundancy between features and validation lists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, features, validation rules, and compatibility details. Output schema handles return values, so no 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?

Schema coverage is 100%, so baseline is 3. Description adds verification context but does not significantly enhance parameter understanding beyond 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 tool moves a folder by ID with AppleScript verification, distinguishing it from sibling tools like rename_folder or move_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 clear context for moving folders with specific features, but lacks explicit when-not-to-use or alternative comparisons.

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 AppleScript verification, validation, and maintenance of note content/metadata. It also mentions support for nested paths and error handling. However, it does not explicitly confirm if the operation is a move vs. copy+delete, though 'maintains content and metadata' implies non-destructive behavior.

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 structured with bullet points and a clear first sentence, but it is longer than necessary (10 lines). Some information, like 'AppleScript verifies ID and name match before moving,' is repeated in both features and requirements. It could be more concise while retaining key points.

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 presence of an output schema, the description adequately covers the tool's purpose, requirements, and verification process. It lists essential requirements (note existence, target folder existence). It does not cover failure scenarios or edge cases, but overall it provides sufficient context for an agent to use the tool effectively.

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 covers all parameters with descriptions, achieving 100% coverage. The description adds value by explaining that note_id and note_name are used for verification, and target_folder_path supports nested folders up to 5 levels deep. This goes beyond the schema's basic 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 'Move a note from one folder to another in Apple Notes by ID with AppleScript verification.' It specifies the verb (move), resource (note), and key method (by ID). This directly distinguishes it from sibling tools like move_folder, which operates on a different resource.

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 does not explicitly state when to use this tool over alternatives. It implies usage for moving notes with verification but lacks exclusions or references to siblings. The context signals and sibling list suggest differentiation by resource, but no direct guidance is provided in the description.

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?

Describes verification process and output structure in detail, but lacks explicit statement that it is read-only (no side effects). Given no annotations, this is strong but not perfect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured into sections, every sentence adds value, no unnecessary 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?

Covers purpose, security, output structure; could mention relation to siblings like list_folder_with_structure, but adequate for a simple read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3; description adds purpose for both parameters (verification, precise ID) and why both are required.

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 the verb (read) and resource (folder), specifies use of primary key ID and verification, distinct from siblings like list_folder_with_structure.

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?

Implies usage for reading a specific folder with verification, but no explicit when-to-use vs alternatives or 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?

No annotations are provided, so the description bears full responsibility. It discloses verification via AppleScript and outlines the return fields, adding value beyond the schema. However, it does not specify error behavior, permissions, or side effects from the verification step, leaving gaps in 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 well-structured with headings and a concise bullet list, making it easy to scan. It avoids unnecessary fluff, though the bullet list could be integrated into prose for even more brevity.

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 low complexity (2 required params, no enums), the description covers the core functionality and output fields. It lists relevant metadata and content. However, it does not elaborate on the 'AppleScript verification' process, which could affect understanding of reliability or platform constraints.

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 100% schema coverage, the input schema already documents both parameters. The description reinforces the verification role of 'note_name' and the primary key usage of 'note_id', but adds minimal additional semantic value beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the verb 'Read' and resource 'note', with distinguishing details like 'primary key ID' and 'AppleScript verification'. It differentiates from sibling tools such as 'read_folder' or 'search_notes' by emphasizing ID-based access and verification.

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 lacks guidance on when to use this tool versus alternatives like 'search_notes' or 'list_all_notes'. It does not mention when not to use it or provide context on prerequisites, such as needing to know the note ID beforehand.

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 disclosing behavioral traits. It covers validation rules, double verification, and Unicode support but omits mutation effects, success/failure responses, or security implications. The disclosure is partial.

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 sections and bullet points, front-loading the main purpose. Each sentence adds value, though there is minor redundancy (e.g., 'double name verification' appears twice). Overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given three required parameters and an output schema, the description covers validation rules, verification steps, and constraints. It explains how rename differs from siblings, but could mention output or error handling for 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?

Input schema has 100% description coverage, so the baseline is 3. The description adds context (e.g., double verification) but mostly repeats schema details like character constraints for new_name. It provides marginal extra 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?

The description clearly states 'Rename a folder in Apple Notes by ID with enhanced name verification,' specifying the verb 'rename' and the resource 'folder' with a distinct scope. It distinguishes from sibling tools like move_folder and delete_folder by focusing on renaming with verification.

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 through validation rules and features but does not explicitly state when to use this tool versus alternatives like create_folder or move_folder. It lacks guidance on preconditions or exclusions, leaving the agent to infer context.

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?

Discloses case-insensitive search, searches all notes, returns names, IDs, folders, and matched keywords. No annotations provided, so description carries burden; it is fairly transparent but could mention performance or scope limits.

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?

Concise with clear bullet points and sections for features and output format. No unnecessary words, well front-loaded with 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?

Covers purpose, features, output format sufficiently for a simple search tool. Does not mention result limits or whether trashed notes are excluded, but given output schema exists for return values, completeness is adequate.

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 covers 100% of parameters. Description adds that keywords are comma-separated and explains how they are used to search content, enhancing understanding beyond 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?

Clearly states it searches for notes by keywords, with specific verb 'search' and resource 'notes'. Distinguishes from sibling CRUD and listing tools by focusing on content 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?

Describes when to use (searching notes by keywords) and features like case-insensitivity. Does not explicitly state when not to use or compare with alternatives like list_all_notes, but implied usage 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?

With no annotations, the description adds behavioral context: AppleScript verifies ID and name match before updating. However, it lacks details on error handling, idempotency, or side effects, which are important 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?

The description is well-structured with a clear first sentence, then grouped information on requirements, HTML support, best practices, security, and an example. While slightly verbose, it front-loads key info.

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 existence of an output schema, the description covers the tool's purpose, input constraints, HTML formatting, and security verification. For a tool with 4 parameters and specific formatting needs, this is sufficiently 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 100%, but the description adds value beyond the schema by specifying requirements (required), providing an example with concrete values, and explaining HTML formatting rules. This helps the agent understand correct parameter usage.

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 'Update an existing note by its primary key ID with AppleScript verification', specifying the verb (update), resource (note), and distinctive verification step. It distinguishes from sibling tools like create_note and delete_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 lists required parameters and provides an example, making the usage context clear. It implicitly differentiates from siblings by focusing on updating, but does not explicitly state when not to use this tool.

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