Edit a journal stop or summary in a Wanderlog trip

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

With no annotations present the description carries the full burden, and it does real work: it discloses that a no-match produces an error, an ambiguous match returns a numbered list and changes nothing, and that only supplied fields are modified while place, media, and unknown fields are preserved. It omits what a successful response looks like and any auth or permission expectations.

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 core action, then the stop workflow, then the failure modes, in three tight paragraphs with no filler. The only redundancy is repeating the case-insensitive substring rule that already appears in the title parameter's schema description.

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 an eight-parameter mutation tool with no annotations and no output schema, the description covers the hard parts an agent needs: selector resolution, ambiguity handling, partial-update semantics, and the summary special case. The remaining gap is return-value shape on success, which matters somewhat without an output schema.

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 the baseline is 3 and the schema already explains each field including the optional/omit semantics. The description adds a little beyond it — the relationship between title and new_summary (summary mode needs no title) and the substring matching rule — but it largely restates matching behavior the schema itself documents, so the added meaning is modest.

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 and resource ("Edits a Wanderlog trip's journal") and immediately splits the operation into its two distinct modes: editing a single stop selected by title, or setting the trip-level summary via new_summary. That framing cleanly separates it from siblings such as wanderlog_add_journal, wanderlog_remove_journal, and wanderlog_list_journal.

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?

Gives concrete usage context: locate the stop by a case-insensitive substring of its title, optionally narrow with date, and use new_summary when you want the trip overview rather than a stop. It does not name an alternative tool for the cases where this one is wrong (e.g. adding vs editing a journal entry), so it falls short of full when/when-not routing.

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