Update Entry

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

Annotations already declare the non-read-only, non-destructive profile, so the description only needs to add context — and it does: the markdown-preservation contract and the "pass null to clear a metadata field" rule are genuine behavioral semantics an agent could not get from the annotations. It omits anything about concurrency (the expected_version parameter), failure modes, or why idempotentHint is false despite this being an update-by-id 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?

Four sentences, front-loaded with the verb and resource, and no filler. The markdown-preservation sentence largely duplicates the content parameter's own schema description, which is a small waste, but nothing is padded or buried.

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 an output schema present, return values need no explanation, and the annotations cover safety. What is missing for a 24-parameter mutation tool is how to identify the target entry and how expected_version protects against lost updates — an agent could call this correctly on the happy path but not safely under concurrency.

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 only 25% across 24 parameters, so the description has to compensate, and it partially does by naming the field categories (content, type, tags, 11 metadata fields) and the null-clearing convention. But it is silent on the highest-risk parameters — entry_id (how to specify the target), expected_version (optimistic concurrency), is_archived, is_personal — leaving more than half the surface undocumented in both places.

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?

States a specific verb+resource ("Update an existing journal entry") and enumerates the updatable surface: content, type, tags, and 11 metadata fields with examples (significance, project, issue, PR, workflow). This clearly separates it from create_entry, but it never names the obvious siblings it competes with (batch_update_entries, team_update_entry), so an agent must infer the boundary itself.

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?

Usage is only implied by "existing" — i.e., use this rather than create_entry when the entry already exists. The rest of the text is formatting policy (preserve ## headers, don't restructure) rather than when-to-use guidance. No guidance on when to prefer batch_update_entries or team_update_entry, and no preconditions for requiring entry_id.

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