Create calendar note

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

Annotations already declare destructiveHint=false and openWorldHint=false, and the description adds material context beyond them: the 90-day maximum range, workspace-wide visibility, and the retry contract via idempotency_key. The distinction between a fresh key per action and reusing a key on retry is genuinely useful operational detail. Minor tension with idempotentHint=false is resolved by the text itself, since idempotency only holds when the key is reused, so this is not a contradiction.

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?

Front-loaded with the concrete action and examples, then constraints, then retry behavior — a sensible order. It is slightly wordy in the idempotency sentence and repeats the single-day rule that the `to` schema field already states, but no sentence is 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?

Six parameters, no output schema, and the description covers duration limits, visibility, parameter defaults, and retry semantics — everything an agent needs to call it correctly and safely retry. The only gap, what identifier comes back, is minor for a note-creation tool with a companion list_calendar_notes.

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, but the description adds a cross-parameter constraint not encoded in the schema ("a note covers at most 90 days") and restates the single-day default for `to` in prose. The idempotency_key retry semantics also get more explanation than the schema's own field description 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 names the specific action (put a note on a calendar) and its scope (one day or a range, visible to everyone in the workspace), with concrete examples like "Black Friday" and "Studio closed". It explicitly separates itself from content-publishing siblings by stating "nothing is posted or sent," so an agent can distinguish it from schedule_post or create_draft without opening a schema.

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 explains the shape of use ("Leave out to for one day") and rules out the obvious wrong expectation by clarifying the note is not published. It does not explicitly point to update_calendar_note, delete_calendar_note, or list_calendar_notes for the nearby operations, so sibling routing is left to the tool name alone.

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