Rename a custom section in a Wanderlog trip

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

Annotations already declare readOnly=false, idempotent=true and destructive=false, so the safety profile is covered. The description adds real context beyond that: the operation returns a confirmation with old and new headings, the current heading must resolve to exactly one section, and the new heading must not collide with another undated section. Only the effect of a failed uniqueness match is left unstated.

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 core action is stated in the first line and the operational hints follow in short, scannable sentences. A small amount of wording duplicates the schema (empty-string clearing is stated twice across description and parameter docs), but nothing is padded.

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 no output schema, the description correctly discloses that a confirmation with old and new headings is returned, and it surfaces both preconditions an agent needs to succeed. It is nearly complete for this complexity; only the behavior on validation failure and the effect on contained places is unaddressed.

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 100%, so all three parameters are already documented, including the empty-string clear behavior and the lookup hint for 'section'. The description restates this rather than adding new semantics such as case sensitivity or whether headings are trimmed, so baseline 3 applies.

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 opens with a precise verb+resource: renaming the heading of a custom section in a Wanderlog trip. The word 'custom' and 'heading' distinguish it from the sibling wanderlog_rename_day and from wanderlog_add_section/delete_section without requiring schema inspection.

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 gives clear operating guidance: identify the section by its current heading, consult wanderlog_get_trip when unsure, and pass an empty string to clear the title. It does not explicitly name alternatives such as wanderlog_rename_day or wanderlog_delete_section, so it stops short of a full when/when-not routing statement.

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