create_note

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

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

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

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

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

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

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

For a tool with 3 parameters, 0% schema coverage, no enums, and complex behavior, the description is remarkably complete. It covers attachment syntax variants, formatting preservation details, exact markdown conversion rules, folder ambiguity handling, and return value. The output schema presumably documents the returned ID, and the description confirms what's returned.

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

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

Schema coverage is 0%, so the description carries the full burden for all three parameters. It thoroughly explains title (bold first line shown in list, fallback extraction from first heading/line, never image), markdown (don't repeat title, use ## and ###, # renders as Title style), and folder (optional, name or full path, check list_folders, ambiguous rejected). Each parameter gets meaningful semantic guidance beyond just its string type.

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

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

The description clearly states the tool creates an Apple Note from markdown with real formatting preservation. It goes beyond a simple verb+resource by distinguishing from AppleScript-based alternatives and detailing specific behaviors (headings, lists, tables, bold/italic survive as real objects). This is specific and clearly differentiates from siblings like edit_note and create_folder.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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