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

Annotations declare destructiveHint=true and idempotentHint=true, and the description earns its credit by explaining exactly what is destroyed: a route/timing/transport change 'replaces ALL existing legs' rather than merging. It also discloses non-obvious state behavior — omitted status stays unchanged even after date edits, and notes/status-only updates leave legs untouched — which the annotations alone could not convey.

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 operation modes and the most consequential constraint (legs[] replacement) before the domain guidance. It is dense but mostly earns its length; the airside-connection and day-count rules are useful for constructing valid legs but push the description toward the long side for a single update call.

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?

No output schema exists, and the description still covers the return-side contract sufficiently ('Journey output leg times are departureAt/arrivalAt') plus the get_journey prerequisite. For a 5-parameter mutation tool with destructive and replacement semantics, it supplies the preconditions, mutation scope, and domain rules an agent needs to call it correctly.

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?

With schema coverage at 60%, the description compensates well: it defines legs as an ordered replace-all route, explains why get_journey precedes it, and resolves the naming trap between read-side departureAt/arrivalAt and write-side departureDate/arrivalDate. It leaves a gap on notes null semantics (whether null clears the field) and does not discuss participantIds beyond what the schema already documents.

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?

Opens with a specific verb plus resource and enumerates the three modes of operation (status, notes, route replacement by id), which lets an agent distinguish it from log_journey, get_journey, and delete_journey immediately. The scope statement 'Status/notes-only updates leave every leg unchanged' further sharpens what the tool does and does not touch.

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 explicit when-to guidance and prerequisites: 'Prefer get_journey first so per-leg details are preserved' and 'If unfamiliar with TripLedger semantics, call get_tripledger_guide first'. It also states a domain condition that gates a value ('Set status completed only after the user confirms travel happened') and the condition that forces the full legs[] array, so an agent knows which path to take rather than inferring it.

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