Change a journal entry

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

Annotations already mark destructiveHint=true and idempotentHint=true, and the description adds substantial detail: the CalDAV server keeps no version history, previous text is permanently lost once the update succeeds, and an ETag guard prevents silently overwriting concurrent changes. This explains exactly what gets destroyed and how consistency is protected.

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 focused sentences: the core behavior first, then the destructive consequence, then the concurrency guard. No filler and each sentence covers a distinct, essential point.

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 destructive partial-update tool, the description covers the key operational facts: which fields are replaced, how to clear a field, the permanence of the change, and the ETag-based concurrency protection. An output schema exists and the parameter schema fully documents each field, so no critical information is missing.

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 provides 100% description coverage for all six parameters, so the baseline is 3. The description adds a useful general rule—partial updates, null clears—that applies across parameters and complements the schema without repeating it. It does not add syntax details 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 opening phrase 'Replaces the fields named' states a specific action and resource, clearly conveying this updates an existing journal entry rather than creating or deleting one. The title 'Change a journal entry' reinforces this and distinguishes it from sibling tools like create_journal, update_event, and update_task.

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 practical parameter guidance ('pass only the fields to change, and pass null to clear one') but does not explicitly state when to choose this tool over alternatives such as create_journal, delete_journal, or get_journal. The intended usage is implied by context rather than clearly spelled out.

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