Add a ferry, bus, or train leg

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

With no annotations supplied, the description does carry real behavioral weight: it discloses that from/to strings are fuzzy-matched against Google Places near the trip's destination, that the shared 'Transit' section is auto-created if missing, and that the response confirms the resolved route and departure time. Gaps remain around failure modes (what happens when a place cannot be resolved) and whether duplicates are created.

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 tight sentences with zero filler, front-loaded with the action and scope, then resolution behavior, then return value. The final sentence earns its place because no output schema exists to communicate what comes back.

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 11-parameter mutation tool with no annotations and no output schema, the description covers what is created, where it lands, how places are resolved, and what is returned. It stops short of failure/permission behavior and duplicate handling, which an agent would still want before invoking a write.

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 already 100%, so baseline is 3, but the description adds genuine meaning beyond the schema by explaining that 'from'/'to' are strings resolved via Google Places near the trip's destination rather than exact terminal IDs. It adds nothing about carrier or confirmation_number semantics, which the schema already covers.

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 ('Adds a ferry, bus, or train leg to a Wanderlog trip') and names the exact transit modes handled. It does not distinguish itself from the sibling wanderlog_add_car_rental, which is another transport-block creation tool, so an agent must infer the boundary.

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: an agent can infer this is the tool for creating transit blocks, but there is no explicit when-to-use / when-not-to-use statement, no mention of the car-rental or add_place siblings, and no prerequisite guidance (e.g. trip_key must exist, dates must be set on the trip).

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