create_note

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.