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

With no annotations at all, the description carries the entire burden and does well: it discloses that locations are geocoded against Google Places near the trip, that a "Rental cars" section is auto-created if absent, and that the response returns the resolved pick-up and drop-off. It does not cover what happens when place matching fails, whether duplicate rentals are allowed, or whether the call is idempotent, which keeps it out of the top band.

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 short sentences, front-loaded with the action, then the location-resolution rule, then the section side effect, then the return value. Each sentence carries information; the phrasing is slightly chatty ("whatever you pick as the location") 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?

For a nine-parameter mutation tool with no annotations and no output schema, the description supplies the important missing pieces: geocoding behavior, the side effect of creating a section, and what the call returns. Only failure modes and error behavior are absent, which is a modest gap given everything else it covers.

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, but the description adds real meaning beyond the schema by clarifying the semantics of pickup_location — the company name is folded into the location string, and there is deliberately no separate firm parameter. The returned "resolved" locations also warn the agent that the input string may be normalized.

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 specific verb and resource: "Adds a rental car to a Wanderlog trip, covering a pick-up and drop-off window." That is concrete enough to separate it from wanderlog_add_place, wanderlog_add_hotel and wanderlog_add_transit, but none of those siblings are named, so the differentiation is by noun alone.

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 implied rather than stated: an agent can infer this is the tool for car rentals, and the note that "the rental firm is whatever you pick as the location — there is no separate company field" is a genuinely useful pre-call instruction. There is still no explicit when-to-use/when-not guidance, no mention of prerequisites such as an existing trip_key, and no routing to alternatives.

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

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

With no annotations supplied, the description carries the full burden and does a decent job: it discloses the initial state of items (unchecked), the precedence rule between 'section' and 'day', the default fallback container, and the shape of the confirmation. It does not cover failure behavior such as an unmatched section heading or an invalid trip key, which keeps it below a 5.

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 one-sentence purpose, then usage patterns, then parameter precedence, then return value — a sensible order. The three-bullet pattern list is longer than strictly necessary and repeats the notion of per-day checklists, but each bullet does illustrate a distinct placement decision.

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 a 5-parameter non-destructive creation tool with no annotations and no output schema, the description covers purpose, placement semantics, iteration default, and return value. Only error handling and duplicate/matching behavior for 'section' remain unexplained, a modest gap.

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 the schema already documents every parameter including accepted day formats and case-insensitive section matching. The description mostly restates those rules; its only added value is illustrating typical section/day choices through the pattern examples. Baseline 3 is appropriate.

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 first sentence names a specific verb and resource ('Adds a checklist to a Wanderlog trip') and the following sentence pins down the unit of work ('each item starts unchecked'), which distinguishes it from sibling note/place/section adders without ambiguity.

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 an explicit usage norm ('Add at least one checklist per trip') plus concrete scenario patterns (packing list, arrival-day, day-of tasks) and a routing rule for the three-way choice of day, section, or default list. An agent knows exactly when to reach for this tool and which parameter form to pick.

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

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

No annotations exist, so the description carries the full behavioral burden. It does disclose the return value ('confirmation with the expense amount and description') and the place-existence precondition, which is genuinely useful. It says nothing about permissions, whether the expense can be edited afterwards, or side effects on the trip budget total beyond the linked/unlinked distinction.

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 short paragraphs, front-loaded with purpose and mode selection before the usage example. The place-linking point is restated in both paragraph one and the closing prerequisite sentence, which is mild redundancy but functional as a constraint reminder.

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 a 7-parameter mutation tool with no annotations and no output schema, the description covers purpose, mode selection, a precondition, and the return value. The remaining gap is mutation semantics — reversibility and any permission requirements — which matters somewhat for a write operation but is partially mitigated by the existence of wanderlog_edit_expense and wanderlog_remove_expense siblings.

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 every parameter is already documented in the schema, giving a baseline of 3. The description reinforces the semantics of the 'place' parameter (linked vs standalone) but adds no new detail such as currency/category interactions or date defaulting beyond what the schema states.

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 specific verb+resource ('Adds a budget expense to a Wanderlog trip') and the second sentence clarifies the two modes of the operation (linked vs standalone). It separates it from siblings like wanderlog_edit_expense and wanderlog_remove_expense implicitly through the verb, but never names an alternative explicitly.

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?

'Use this to give the trip a cost dimension — estimated meal costs, entrance fees, transport passes' provides concrete usage context and examples. It also states a real prerequisite ('If you link a place, it must already exist in the trip'). It does not, however, route the agent to a sibling for correcting or deleting an expense.

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

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

With no annotations, the description carries the whole behavioral burden, and it does disclose two genuinely useful traits: a 'Hotels and lodging' section is auto-created when missing, and the call returns a resolved hotel name plus booking window. It says nothing about what happens when the hotel string matches multiple places, whether duplicate bookings are created on repeat calls, or failure behavior for unresolvable names.

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 short sentences, front-loaded with the action, then the side effect, then the return. No filler or redundant restatement of the tool name.

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 a four-required-parameter mutation tool with no annotations and no output schema, the description covers purpose, an important side effect, and the shape of the response, which is the main gap left by the absent output schema. Only failure/ambiguity handling is missing, and that is a modest omission.

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 four parameters are already documented in the schema, including the Google Places matching behavior and the check_out-after-check_in constraint. The description only restates 'with check-in and check-out dates' and adds no format, range, or resolution semantics beyond the schema.

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 states a concrete verb and resource ('Adds a hotel booking to a Wanderlog trip') and pins the scope with check-in/check-out dates, which clearly separates it from wanderlog_add_place or wanderlog_add_car_rental. It stops short of naming any sibling explicitly, so differentiation comes from the resource noun rather than deliberate routing.

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?

Use is implied by the resource (create a lodging booking). There is no guidance on the obvious adjacent decision: whether the agent should first run wanderlog_search_hotels to resolve a name, or just pass a free-text query here, and no when-not guidance (e.g., for existing bookings or edits).

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

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

With no annotations, the description carries the full burden and does well: it discloses that the tool will not silently create places, that it returns a prompt instead, and how to override that with allow_new_place. Gaps remain on mutation specifics such as permission requirements, what the successful return payload contains, and behavior when multiple places match.

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?

Purpose is front-loaded in the first sentence, and the second labeled paragraph ('Place handling:') covers the only non-obvious behavior. Every sentence carries information; nothing is redundant padding.

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 a mutation tool with no annotations and no output schema, the description covers the critical non-obvious behavior (place reuse and the prompt path). It does not describe the successful return value or error cases, which is a modest gap rather than a blocking one.

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, but the description adds workflow meaning beyond the schema by explaining the place-resolution sequence and the explicit re-call option with allow_new_place: true. It does not add detail on date/time defaults or title fallback 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?

The description opens with a specific verb+resource ('Adds a stop to a Wanderlog trip's journal (travelogue)') and clarifies that a stop pins a place with date/time plus optional text appearing in the journal timeline. This distinguishes it cleanly from siblings like wanderlog_add_note and wanderlog_add_place.

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 a concrete workflow: try to reuse an existing trip place, otherwise the tool prompts to use wanderlog_add_place or to re-call with allow_new_place: true. That is a clear when-to-use branch with a named alternative. It does not explicitly contrast with wanderlog_edit_journal or explain when to journal versus add a note, leaving some sibling selection to inference.

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

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

No annotations exist, so the description carries the full burden: it discloses the destination-resolution precedence ('section' wins over 'day'), the default target list, and that the call returns a confirmation of where the note landed. It omits failure modes (e.g., what happens with an unmatched section name) and any auth or rate-limit context.

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?

Placement rules are front-loaded before the example bullets, and the structure is easy to scan. The five illustrative bullets are somewhat generous in volume but each demonstrates a distinct note type, so they mostly earn their place.

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 a four-parameter mutation tool with no output schema, the description covers purpose, placement semantics, timing relative to other tools, and the shape of the return value. An agent has everything needed to invoke 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?

Schema coverage is 100% and the per-parameter descriptions already explain day formats, section matching, and precedence. The description's restatement of the day/section/default rule adds little beyond what the schema provides, so the 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?

States a specific verb and resource ('Adds a text note to a Wanderlog trip') and immediately explains where the note lands in the itinerary, which is what distinguishes it from sibling tools like wanderlog_edit_note and wanderlog_annotate_place.

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 procedural guidance ('do this after adding each place or group of places') plus concrete content categories with example text, and defines the day/section/default resolution rules. It stops short of naming alternative tools or stating when not to add a note.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the place is matched against Google Places near the trip's destination, that the top match wins, that place_id bypasses search and takes precedence, and that the response confirms the resolved name and target location. It does not cover auth, failure modes when no match is found, or mutation side effects, which keeps it from a 5.

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 and outcome, then organized into a fallback paragraph and a 'PREFERRED' usage paragraph. It is somewhat long and restates some note/place_id semantics already in the schema, but every section contributes routing or behavioral information rather than filler.

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 8-parameter mutation tool with no output schema, the description covers what the tool does, the two ways to identify a place, when to use each, how notes and times are attached, and what the confirmation contains. Nothing an agent needs in order to call it correctly is missing.

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 baseline is 3, and the description adds real meaning beyond it: the precedence rule between 'place' and 'place_id', the 'place' is required unless place_id is given' constraint, the recommendation to prefer 'note' over a separate add_note call, and the pairing of start_time with end_time.

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 place to a Wanderlog trip') plus the scope detail that distinguishes outcomes: inserted into a specific day or the general 'Places to visit' list. It also names the sibling it complements (wanderlog_search_places), so an agent can distinguish it without opening schemas.

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 an explicit fallback path when the free-text match is wrong (call wanderlog_search_places with response_format: 'detailed', then pass place_id). It also draws a clear boundary against wanderlog_add_note — use 'note' on this tool for place-attached context, standalone wanderlog_add_note only for freestanding commentary between places.

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

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

Annotations only declare the write/non-destructive/non-idempotent profile; the description adds real behavior beyond that — the section is created empty, the heading must be unique among undated sections, and duplicate or ambiguous targets are rejected without making any change. It also states what is returned (heading and position), which the annotations do not cover.

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 short paragraphs, front-loaded with the core action, then usage, then constraints and return value. No filler sentences; each one carries distinct information an agent needs.

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 a three-parameter mutation tool with no output schema, the description covers purpose, follow-on workflow, the failure/atomicity condition, and the return payload. An agent has everything needed to call it correctly and to interpret the result.

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 the baseline would be 3; the description earns more by explaining that the created heading becomes the identifier passed as the 'section' parameter to wanderlog_add_place, and by tying the uniqueness constraint to the heading argument. The after_section insertion behavior is only implied in the description, since the schema documents it directly.

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 new custom section to a Wanderlog trip itinerary') and immediately clarifies that sections are containers for places, notes and blocks, which separates it from wanderlog_add_place and wanderlog_add_note in the sibling list.

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 use cases (thematic grouping such as 'Food & Drink', 'Day Trips', or extra place lists beyond the default 'Places to visit') and routes the agent forward to wanderlog_add_place / wanderlog_add_note / wanderlog_add_checklist for filling the section. It does not contrast with wanderlog_update_section or wanderlog_delete_section, so the boundary against those siblings is left implicit.

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

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.

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

With no annotations present the description carries the full load, and it does disclose meaningful behavior: it is a mutation ('updates', 'set or replace'), and on ambiguity it returns a disambiguation list without making changes — a key safety property an agent needs. It does not mention permission/auth requirements or what happens if no place matches at all.

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 action and resource, then constraints, then edge-case behavior — a sensible order. The second sentence ('set practical context, scheduled times, or both in one call') largely restates the first and could be trimmed, but nothing is confusing.

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 a 5-parameter mutation tool with no output schema, this covers the essentials: what it changes, the field-combination rule, reference syntax, and the ambiguity return path. Remaining gaps are the not-found case and the relationship to wanderlog_add_note, which are secondary.

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 baseline is 3, but the description adds a constraint the schema does not encode: at least one of note/start_time/end_time must be supplied even though only trip_key and place are required. It also reinforces natural-language place resolution, which is the least obvious parameter behavior.

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 first sentence names a specific verb (updates), resource (an existing place in a Wanderlog trip), and the exact fields it can set (inline note, start/end time, or both). 'Use this to enrich places that were already added' implicitly separates it from wanderlog_add_place, so an agent can route correctly without opening the schema.

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 context (enrich already-added places; set context, times, or both in one call), a hard precondition ('at least one of note, start_time, or end_time must be provided'), and points to wanderlog_remove_place for the place-reference syntax. It stops short of explicit exclusions, notably how it relates to the sibling wanderlog_add_note or where to go when the place doesn't exist yet.

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

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

With no annotations, the description carries the burden and does reasonably well: it discloses that the trip is created empty, that day sections are auto-generated per day in the range, and that the new trip key is returned for subsequent calls. It omits auth/permission requirements, what happens when geo resolution picks a wrong city, and whether creation is idempotent — meaningful gaps for a mutation tool.

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 first and last sentences are well front-loaded and earn their place, but the middle is a multi-step itinerary-building tutorial for four other tools rather than guidance about this tool. It is useful behavioral shaping, yet disproportionate to a five-parameter create call and buries the return-value note at the end.

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 a create tool with no annotations and no output schema, the description covers creation semantics, resulting structure, and the return value (trip key), while the schema fully covers parameters. Remaining gaps are authorization and failure/ambiguity handling, which keep it from a 5.

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 destination, dates, title, and privacy are already fully documented including the geo-autocomplete resolution behavior. The description only restates destination and date range and adds nothing about title or privacy, so it meets the baseline without exceeding it.

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 ('Creates a new Wanderlog trip') scoped to destination and date range, and further specifies the resulting state: an empty trip with one pre-generated day section per day. That level of specificity makes it unambiguous against read-oriented siblings like wanderlog_list_trips and wanderlog_get_trip.

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?

Provides strong downstream guidance about which tools to chain after creation (add_place, add_note, add_hotel, add_checklist) and why notes matter. It does not, however, state preconditions or when-not-to-use (e.g. that an existing trip should be reused rather than a duplicate created), so it stops short of full when/when-not coverage.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantive context beyond them: the section AND all blocks inside it are permanently removed, which section types are protected, that ambiguous headings cause a failure with nothing deleted, and what the tool returns. These are real operational facts an agent cannot get from the schema or annotations.

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 paragraphs — action, eligibility constraints, behavior/return — front-loaded with the destructive verb. No filler and no restatement of the title.

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 a destructive two-parameter tool with no output schema, the description covers the action, the constraint set, the failure mode, and the return value. There is no obvious gap an agent would need to guess about before calling.

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 baseline is 3, but the description adds meaning the schema lacks: the 'section' parameter is matched by heading, and a non-unique heading causes a fail-without-delete rather than an arbitrary deletion. That uniqueness rule is genuinely new information about how the argument is resolved.

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 ('Deletes a custom section from a Wanderlog trip itinerary') and immediately scopes it to custom sections only, distinguishing it from the sibling wanderlog_add_section and wanderlog_update_section. An agent can tell what this does without opening the schema.

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?

Explicitly states the when-not: day sections, the default 'Places to visit' list, and system sections are protected. It also names where custom sections come from (wanderlog_add_section). It stops short of routing the agent to a specific alternative for the protected cases (e.g., rename_day or update_section), so it is clear context rather than full when/when-not/alternatives.

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

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

With no annotations at all, the description carries the full behavioral burden and does well: it discloses the ambiguity outcome (numbered list, no mutation), the failure outcome (error when nothing matches), and partial-update semantics ('Only the fields you supply via new_* are modified; all other fields on the expense are preserved'). It stops short of auth/permission requirements, reversibility, and what a successful response contains.

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 sentences, each earning its place: identification mechanism first, then the two failure modes, then the partial-update guarantee. No filler, no restating of the tool name, and the most consequential behavior (nothing is changed when ambiguous) is stated plainly.

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 a 10-parameter mutation tool with no annotations and no output schema, the description covers the risky parts well: ambiguity handling, no-match errors, and preserved fields. Gaps remain around authorization prerequisites and what a successful edit returns, which matters more here because no output schema exists to document the response.

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 the schema already documents every parameter, including that date/amount/currency exist 'to disambiguate which expense to edit' and that new_* fields are omitted to leave values unchanged. The description largely restates that contract in prose rather than adding new meaning (e.g., no guidance on substring collisions, amount tolerance, or currency normalization edge cases beyond what the schema says). 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 specific verb+resource: 'Edits an existing budget expense on a Wanderlog trip,' and adds the lookup mechanism (case-insensitive substring of description) plus the mutable fields. The word 'existing' and the verb 'Edits' separate it in practice from add_expense/remove_expense, but no sibling is named explicitly, so differentiation is inferred rather than stated.

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 concrete operating guidance: no match returns an error, multiple matches return a numbered list with nothing changed, and the agent should narrow via a more specific description or a date/amount/currency filter. What's missing is routing guidance against the sibling mutation tools (add_expense, remove_expense, list_expenses) — it never says when to prefer this over those.

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

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.

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

With no annotations supplied, the description carries the full behavioral burden and does substantial work: case-insensitive matching, three distinct outcome branches (single match replaces in place, zero matches errors, multiple matches returns numbered previews requiring a retry). It omits whether the edit is reversible/undoable and whether all in-note occurrences are replaced when only one location matches, which are meaningful gaps for a mutation tool.

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-loads what the tool does and where it searches, then walks through match outcomes in the order an agent would encounter them. No filler sentences, and the retry instruction is placed exactly where the multi-match behavior is described.

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 a four-parameter mutation tool with no annotations and no output schema, the description covers search scope, matching semantics, and all outcome paths well enough to invoke correctly. What is missing is safety context (reversibility, permissions, whether the returned previews are actionable before confirmation) and any hint of the success payload shape.

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 the four parameters are already documented, including the day format variants and case-insensitivity of old_text. The description only reinforces the day filter's purpose and the substring nature of old_text, adding little beyond structured data.

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 note content in a Wanderlog trip by finding and replacing a substring') and immediately delimits scope to freestanding notes, place annotations, and checklist titles/items. This clearly separates it from wanderlog_add_note, wanderlog_remove_note, and wanderlog_edit_journal without the agent needing to open any schema.

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 guidance: use a substring find/replace, narrow with the optional 'day' filter, and call again with a more specific substring when multiple matches come back. It does not explicitly say when to prefer a different sibling (e.g., remove_note or add_note) or whether whole-note rewriting is possible, but the operating context is clear.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the guide is public and that the tool renders full content as readable text, which establishes a safe read operation, but it does not mention error behavior for missing or private guides, authentication requirements, or rate limits.

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 description is two tight sentences that front-load what the tool does, then supply the parameter source and the sibling alternative. Every sentence earns its place, with no wasted wording.

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 a read-only guide-fetching tool with no output schema, the description gives a clear high-level account of what is returned: sections, places, notes, and readable text. It does not explain failure modes for invalid or private guide keys, but the essential information needed to invoke the tool correctly is present.

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, including the day filter and response_format enum, are already documented in the schema. The description mentions passing guide_key from a search response, but that repeats the schema description rather than adding new semantics, so the baseline of 3 is appropriate.

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 gives a specific verb and resource: fetches the full content of a public Wanderlog guide, including sections, places, and notes, and renders it as readable text. It also clearly distinguishes this from wanderlog_get_trip for the user's own trips, so an agent can tell the tools apart without opening either schema.

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 explicitly states when to use it (reading a public Wanderlog guide, using a guide_key from a wanderlog_search_guides response) and when not to use it (for your own trips, use wanderlog_get_trip instead). This names a concrete alternative and the condition that selects it.

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

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

With no annotations supplied, the description carries the full burden and does most of it: it discloses that this is a read operation, that output verbosity is caller-controlled, and that the day parameter narrows scope. It does not mention failure behavior for an unrecognized day string or whether any trip may be inaccessible to the caller, which keeps it short of full transparency.

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 return contents are front-loaded, followed by format guidance and then the prerequisite call, which is a sensible order. The third paragraph slightly repeats the format distinction already implied and adds a sentence an agent may not need on every invocation, but there is no filler prose.

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 and no annotations, the description must explain what comes back — and it does, listing the three sections and distinguishing concise vs detailed payloads. It stops short of covering empty-trip behavior or invalid day handling, a minor gap for a low-risk read tool.

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 all three parameters are already documented, making 3 the baseline. The description does add some meaning the enum text lacks — detailed format also surfaces the numeric trip id and the forwarding email — but it does not explain the day-filter syntax beyond what the schema already states, so the marginal gain 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?

The description names a specific verb and resource ("Returns the itinerary for one Wanderlog trip") and enumerates the payload contents: hotels list, places-to-visit list, and each day's scheduled places. That specificity immediately separates it from wanderlog_list_trips, which only enumerates trips.

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 explicit routing: use concise format for summarization/Q&A, detailed format when addresses, phone numbers, check-in/out dates, numeric trip id, or forwarding email are needed. It also names the prerequisite step ("If you don't know the trip_key, call wanderlog_list_trips first"), so the agent never has to guess the alternative.

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

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

With no annotations supplied, the description carries the load and does reasonably well: it explains what happens downstream (Wanderlog parses flight/hotel/car confirmations from Booking.com, Airbnb, airlines), that they are attached to the trip, and that they are deduplicated against existing reservations. It omits whether the address is permanent or per-trip-stable, and whether any authorization level is needed to obtain it.

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 answer is front-loaded in the first sentence, followed by behavior, a help link, and usage. The final sentence's list ('configuring a mail filter, an integration or copy pasting the address...') is slightly wordy but each item adds a concrete use case.

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 a one-parameter read tool with no output schema and no annotations, the description covers what is returned, how the imported data behaves, and when to call it. Minor gaps remain about the address's persistence and any restrictions on what email types are accepted beyond the examples given.

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% and the single parameter's schema description already points to wanderlog_list_trips as the source of the key. The description adds no further meaning about trip_key, so the baseline of 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 specific verb and resource: 'Returns the email address you can forward reservation emails to for automatic import into this trip.' No sibling tool offers this capability, and the scope (per-trip import address) is unmistakable.

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 states explicitly when to use it – 'when a user wants to set up automated import for a trip' – and gives concrete examples (mail filter, integration, pasting into a forward). No when-not-to-use or alternative-tool guidance is given, but no plausible alternative exists among the siblings.

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

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

With no annotations, the description carries the full burden. It does disclose security-relevant behavior — 'view' is read-only and 'safe to share with anyone', while 'edit' is full-permission — which is genuinely useful. It omits auth requirements, link permanence, and whether links can be revoked, leaving real gaps for a no-annotation tool.

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 purpose, then a compact, readable bulleted breakdown of the three modes and a fallback rule. Slightly redundant with the schema enum descriptions, but the structure is efficient.

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 a two-parameter lookup tool, the description covers purpose, every mode's meaning, and a default policy. Remaining unknowns — link lifetime or revocation and auth context — are minor for this operation.

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 mode enum and its values are already documented in the input schema, and the description largely repeats that. It adds only the tie-breaking default hint, which is already present as the schema default.

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 specific verb and resource: 'Returns the wanderlog.com URL for a trip', plus the intent ('so the user can open it in a browser'). That clearly separates it from data-returning siblings such as wanderlog_get_trip.

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 explicit direction on choosing a mode, including a default instruction ('If you don't know which mode the user wants, default to edit'). It does not, however, say when to call this versus a sibling like wanderlog_get_trip, so the guidance is contextual rather than comparative.

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

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

No annotations are supplied, so the description carries the full burden and does well: it discloses ordering ('newest entries last'), the fields returned per line, and empty-state behavior ('friendly message when the trip has no matching expenses'). It does not mention read-only semantics, permissions, or behavior with very large expense lists, leaving minor gaps.

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 short sentences, each doing work: purpose, return shape, and filter/routing advice. The ordering fact is front-loaded and there is no filler.

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 properly covers return content, ordering, and the empty case, and all five parameters are documented in the schema. Minor omissions remain around whether trip_key is an ID or slug and any pagination behavior for long expense lists.

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%, and the schema already documents case-insensitivity for description/currency, the YYYY-MM-DD pattern, and the ISO 4217 constraint. The description only restates which filters exist, adding no syntax or matching semantics beyond the schema. 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?

States a specific verb and resource ('Lists budget expenses on a Wanderlog trip') with explicit scope. The sibling set includes add/remove/edit expense tools, and the description makes clear this one only reads.

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?

Explicitly routes the agent: use the filters to find the exact expense to hand to wanderlog_remove_expense or wanderlog_edit_expense when several are similar. That is a concrete when-to-use next step. It lacks an exclusion note (e.g., when to prefer wanderlog_get_trip) but the context is clear.

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

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

With no annotations provided, the description carries the full disclosure burden and does reasonably well: it specifies the per-line output shape (title, date/time, text preview), notes that the journal summary is reported when set, and covers the empty-state behavior ('Returns a friendly message when the trip has no journal stops'). It never explicitly states the operation is non-mutating or mentions pagination/limits, which is the main residual gap.

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 capability is front-loaded in the first sentence, followed by the output shape, then filter usage, then the empty-state note — a clean information hierarchy. Every sentence earns its place, and no sentence repeats the tool title or name.

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?

There is no output schema and no annotations, so the description must convey the return shape and safety profile itself; it does cover the return shape well and implies a read-only listing. For a simple 3-parameter read tool this is close to sufficient, with only the absence of an explicit read-only/non-mutating statement keeping it below full marks.

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%, and the schema already documents the date pattern, the case-insensitive substring semantics for title, and the required trip_key — so the description is not needed to explain any parameter. Its only added meaning is framing title/date as filters that narrow the listing, which is a modest restatement rather than new semantics. Baseline 3 is appropriate here.

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 specific verb and resource — 'Lists the stops in a Wanderlog trip's journal (travelogue), in order' — so the agent knows exactly what is returned and that ordering is preserved. It further disambiguates by naming the mutation siblings wanderlog_edit_journal and wanderlog_remove_journal as the downstream consumers of this read, though it never states the inverse contrast (i.e., what to call instead of this tool).

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 context for the filters — 'Use the optional title / date filters to narrow the list' — and a concrete workflow reason to call it: 'handy for finding the exact stop to pass to wanderlog_edit_journal or wanderlog_remove_journal.' What's missing is any explicit when-not guidance (e.g., that trip-level details belong in wanderlog_get_trip rather than the journal listing), so it stops short of a full routing rule.

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

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

With no annotations, the description carries the burden and does well: it discloses the fields returned (title, dates, place count, trip_key), the line format with the [key: ...] suffix, and the extraction instruction an agent needs to chain calls. It leaves out whether results are paginated or whether very large accounts are truncated, which is the main remaining gap for a listing tool.

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 scope, then the return shape, then the selection guidance — a sensible order with no filler sentences. The final forwarding-email sentence is slightly tangential for a list tool but does route the agent to the right sibling, so it earns most of its place.

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?

The tool has a single optional enum parameter, no annotations, and no output schema, so the description must explain the return shape — and it does for both concise and detailed modes. Combined with the key-extraction instruction and sibling cross-references, an agent has everything needed to call it and use the result.

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, but the description adds the intent behind the enum — concise versus detailed content differences and specifically what you gain from 'detailed' (numeric trip id, forwarding email) and why you'd want the email (importing reservation confirmations). That is meaning beyond the schema's field list, though the field list itself is largely restated.

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 (list all trips) plus the scope that matters operationally: owned plus shared-with-you. It also implicitly separates itself from wanderlog_get_trip by noting that this returns the trip_key while get_trip requires it.

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 an explicit trigger ('use this tool first when the user mentions a trip by name but you don't have its trip_key yet') and names the downstream tools that depend on the key (wanderlog_get_trip, wanderlog_search_places). It also states when to switch to response_format='detailed' and points to wanderlog_get_trip_forwarding_email for the email use case.

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

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

With no annotations, the description carries the disclosure burden and does well: it promises preservation of ID, notes, images, times and booking details, and specifies that an ambiguous reference changes nothing and returns candidates. It does not state permission/auth requirements or what a successful response contains, leaving a modest gap for a mutation tool.

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 effect and the preservation guarantee, then a compact bullet block for the three destination modes, then the failure behavior. No sentence is redundant and the structure mirrors how an agent would reason about the 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?

For a 5-parameter mutation tool with no annotations and no output schema, the description covers effect, constraints, aliasing to a sibling, and error/ambiguity behavior. Only the success response shape and any permission prerequisites are left unstated.

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 baseline is 3; the description adds genuinely new meaning by declaring the three destination options mutually exclusive (the schema has no oneOf) and by clarifying that positional counting includes notes/checklists while before/after targets exclude them.

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 (moves an existing place or reservation block) plus the precise scope (another position within its current section) and the key non-behavior (does not delete or recreate). This clearly separates it from wanderlog_add_place and wanderlog_remove_place.

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?

Explicitly enumerates the three mutually exclusive destination modes, states that exactly one must be chosen, rules out cross-section moves, and warns against the tempting remove-and-re-add workaround. It also points to wanderlog_remove_place as the shared reference syntax, giving an agent everything needed to pick this tool and call it correctly.

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

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

With no annotations, the description carries the full burden and does well: it discloses case-insensitive matching, an error on zero matches, and that a multi-match returns a numbered list with nothing deleted. It omits permission requirements and whether deletion is reversible or undoable, which is a meaningful gap for a destructive 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?

Three tight sentences, front-loaded with the action and matching rule, then the three outcome branches in the order an agent will encounter them. No redundant restatement of the tool name or filler.

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 a destructive mutation with no output schema, the description explains return behavior for each branch (deleted, error, numbered list), which is the key missing piece. It lacks authorization or reversibility notes, the one thing an agent would still want before calling.

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 each parameter is already self-documenting. The description restates the substring semantics and explains the disambiguation purpose of date/amount/currency filters, which adds only marginal meaning beyond what the schema already says.

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 (removes a budget expense from a Wanderlog trip) plus the matching mechanism (substring of the description), which separates it from sibling mutations like wanderlog_remove_place and wanderlog_edit_expense without the agent needing to open another schema.

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?

The description gives a concrete retry protocol: if several expenses match, re-call with a more specific description or add a date/amount/currency filter. It doesn't explicitly contrast with wanderlog_edit_expense or wanderlog_list_expenses as a pre-check alternative, so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the full burden and does so unusually well: it discloses case-insensitive substring matching, the conditional-delete rule, the no-op guarantee on ambiguity, and the error path. It omits whether a deletion is reversible and what permissions are required, which are the remaining gaps for a destructive mutation.

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 one short paragraph covering each outcome path. No redundant restatement of the title or schema fields; every sentence adds a branch condition the agent must handle.

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?

There is no output schema, and the description covers the ambiguous and error return shapes but not the success response. For a three-parameter removal tool that is nearly complete; only the successful-deletion return value and irreversibility are unstated.

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 baseline is 3, but the description adds real meaning beyond the schema by explaining that 'title' is a substring matcher whose ambiguity is resolved interactively and that 'date' exists to disambiguate duplicate titles. This tells the agent how the parameters behave together, not just their types.

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 ('Removes a stop from a Wanderlog trip's journal') plus the matching mechanism. It is clearly distinguishable from the sibling tools wanderlog_add_journal and wanderlog_edit_journal without opening any schema.

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?

Explains the operational conditions well: exactly one match deletes, no match errors, multiple matches returns a list and deletes nothing, with explicit remediation ('re-call with a more specific title or add a date filter'). It doesn't name sibling alternatives such as edit_journal for modifying rather than removing, but the when-to-use context is clear.

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

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

With no annotations at all, the description carries the full burden and does much of it well: it discloses case-insensitive matching, that a single match causes deletion, that zero matches yields an error, and that multiple matches return a preview list rather than deleting. It omits reversibility (is the deletion undoable?) and any permission or auth expectations for a destructive operation, which keeps it from a 5.

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 opening sentence front-loads verb, resource and matching mechanism, then the branching outcomes are laid out in a compact decision sequence. The final sentence on the 'day' filter is slightly redundant with the schema description, but nothing is wasted overall.

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 a destructive, three-parameter tool with no annotations and no output schema, the definition covers the important edge cases (no match, ambiguous matches, disambiguation strategy) that an agent needs before invoking it. The remaining gaps are the consequences of deletion — reversibility, confirmation, and any post-delete return shape — which matter for a mutation tool with no annotation safety net.

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 day format variants and the case-insensitive substring semantics. The description restates the text-matching and day-scoping behaviour and only marginally adds value by framing 'day' as a narrowing filter rather than introducing new syntax or constraints.

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 names a specific verb (remove) and resource (a note block within a Wanderlog trip) and goes further by stating the selection mechanism — substring matching on note text. That verb+resource+mechanism combination makes it clearly distinguishable from wanderlog_edit_note and wanderlog_remove_place without opening any schema.

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 actionable usage guidance for the tricky case: if multiple notes match, you get previews back and should retry with a more specific substring, and the optional 'day' filter narrows the search scope. What it doesn't do is explicitly route the agent between this tool and its near neighbours (edit_note, remove_place, delete_section), so it stops short of full sibling differentiation.

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

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

With no annotations, the description carries the full burden, and it does disclose the highest-value non-obvious behavior: ambiguous references return a numbered candidate list and make no change. It omits reversibility, permission requirements, and confirmation behavior, which are gaps for a destructive 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?

Front-loaded with the one-line purpose, followed by a scannable bulleted list of reference forms and a closing note on ambiguity. Slight redundancy with the schema's place_ref description mildly lowers it from 5.

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 a two-parameter destructive tool with no annotations and no output schema, it covers reference syntax and the ambiguity fallback well. Missing are the consequences of removal (e.g. whether other schedule blocks shift) and permissions, which would round it out.

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% and the place_ref schema description already enumerates the same reference forms, so the description largely restates structured data. It does reinforce the semantics of natural-language resolution, but adds little operational detail beyond the schema.

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 ('Removes') and a precisely scoped resource ('a place (or flight, train, hotel — any block) from a Wanderlog trip'), which also implicitly separates it from siblings like wanderlog_remove_expense, wanderlog_remove_note, and wanderlog_move_block.

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 guidance on how to form references and, crucially, what to do when the reference is ambiguous (re-call with an ordinal or more specific filter). It does not explicitly contrast with sibling removal tools (e.g. remove_expense for expenses), so 4 rather than 5.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It does valuable work by explaining that an empty 'heading' resets to Wanderlog's auto-generated title, but it omits permissions required, what happens if the day doesn't exist or is ambiguous, and whether the original heading is recoverable.

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 short paragraphs, front-loaded with the core action and followed by context and the edge-case behavior. The reset instruction partially duplicates the schema's own 'heading' description, which is minor redundancy rather than waste.

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 a simple three-parameter mutation with a fully documented schema and no output schema, the description covers purpose, examples, and the reset edge case. The residual gap is the ambiguous 'heading/subheading' phrasing, which never clarifies whether one call sets both fields or only the heading.

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 the schema already documents all three parameters including accepted day formats and the empty-string reset. The description reinforces the empty-string semantics and adds illustrative heading examples, but contributes no meaning beyond the schema, making the baseline 3 appropriate.

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 ('Renames the heading/subheading of a specific day') and grounds it with a concrete example of what day headings look like in the itinerary. It does not explicitly distinguish itself from sibling tools like wanderlog_update_section or wanderlog_delete_section, which also touch itinerary structure, so it falls short of a 5.

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?

The sentence 'Use this tool to replace them with more descriptive titles' implies the intended use case, and the empty-string behavior gives a second usage mode (resetting). There is no explicit when-not guidance or named alternative for editing other itinerary elements, leaving routing to the agent's inference.

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

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

With no annotations supplied, the description carries the whole burden and does substantial work: it discloses the free-text resolution policy (highest-popularity match wins), the soft-hint escape hatch via 'alternative_geos' (up to 2), and the empty-result fallback that returns the top 5 nearby destinations with guides. That is exactly the kind of surprising behavior an agent needs warning about. It stops short of stating a result limit or pagination for the guide list itself, so it is not fully complete.

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 purpose, then inputs, then the next-step handoff — a sensible order with no filler sentences. It loses a little economy by restating the geoAutocomplete and alternative_geos mechanics that the schema parameter descriptions already spell out verbatim.

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, so the description must name the response surface, and it does: guide_key, alternative_geos, and alternative_geos_with_guides, plus what response_format changes in the payload indirectly through the schema. For a three-parameter read tool this covers what an agent needs to call it and interpret the result.

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 the schema already documents geo_id, destination, and response_format in detail, and paragraph two largely repeats the resolution and alternative_geos behavior already present in the destination parameter. The genuinely additive piece is the mutual-exclusivity constraint ('exactly one of destination or geo_id'), which the schema does not encode via oneOf, plus the downstream use of the returned guide_key.

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 and resource: 'Lists user-written Wanderlog travel guides for a destination,' and qualifies the content as 'long-form recommendations and itineraries other travellers have published.' It also implicitly separates itself from wanderlog_get_guide by routing full-content reads there, so an agent can pick between the two on purpose alone.

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?

Explicitly states when to reach for it ('user asks for inspiration, an itinerary they can copy, or what guides exist for X') and names the follow-on tool: 'Pass the returned guide_key to wanderlog_get_guide.' It also gives a hard input rule, 'Specify exactly one of destination or geo_id,' which is real selection guidance rather than a restatement of the name.

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

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

With no annotations, the description carries the burden and does reasonably well: it discloses the return shape (ranked offers, per-vendor deal comparison, available_filters facet block, alternative_geos), the popularity-based geo resolution behavior, and the token tradeoff between concise and detailed formats. It omits auth requirements, rate limits, and whether the search hits live vendor APIs or cache, which keeps it from a 5.

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 short paragraphs, each front-loaded with the decision that matters most: what the tool returns, how to disambiguate the destination, then the verbosity knob. No filler sentences and no restatement of the name or title.

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 a 22-parameter tool with no output schema and no annotations, the description does the essential work of describing return values, the geo fallback loop, and the verbosity tradeoff. What remains thin is guidance on the large filter surface and any note about pagination or result-count behavior beyond the limit parameter.

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 baseline is 3; the description adds genuine value beyond it by spelling out the mutual-exclusivity constraint between destination and geo_id, the semantics of alternative_geos as a soft re-call hint, and the field-level difference between concise and detailed output. It leaves the filter parameters (amenities, lodging_types, price_range, etc.) to the schema, which is acceptable given full coverage.

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 — searching an aggregated hotel inventory across airbnb/expedia/google/kayak for a destination and date range — and distinguishes itself from siblings like wanderlog_search_places and wanderlog_add_hotel by naming the aggregator and vendor set. An agent can tell immediately this is the discovery tool for lodging offers, not trip mutation or generic place search.

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 operational guidance: 'Specify exactly one of destination or geo_id', the fallback workflow of re-calling with a geo_id from alternative_geos when the wrong city is picked, and when to prefer response_format='detailed'. It does not name sibling alternatives (e.g. why not wanderlog_search_places or wanderlog_add_hotel), so it stops 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.

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

With no annotations supplied, the description carries the full burden and does well: it discloses the return shape (names + short descriptions, or place_ids in detailed mode), the important non-obvious trait that results are geographically biased rather than global, and the rationale for the two-pass pattern. It omits result-count limits, pagination, and what happens when the trip_key is invalid.

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 short paragraphs, front-loaded with purpose then usage then workflow; each sentence contributes something. The final paragraph is slightly workflow-oriented rather than descriptive, but it is not padding.

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 a 3-parameter read tool with no annotations and no output schema, the description covers purpose, result content, geographic bias, and the concise/detailed progression adequately. Remaining gaps (result volume, failure modes, behavior on ambiguous queries) are minor but real.

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%, including explicit docs for trip_key, query, and the response_format enum, so the baseline is 3. The description adds only the practical sequencing of concise vs detailed; it does not extend the meaning of 'query' (e.g., free-text matching rules) or clarify search radius relative to the trip destination beyond what trip_key's schema text already says.

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 ('Search for real-world places') and enumerates the entity types covered (restaurants, attractions, hotels, parks, landmarks), plus the geographic scoping to the trip destination. It is not explicitly differentiated from the sibling wanderlog_search_hotels, which overlaps with the 'hotels' category it claims to cover, so an agent could still hesitate between the two.

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 a concrete usage trigger ('resolve user requests like find a good coffee shop in Queenstown') and a sequencing rule when the goal is to add a place: concise first, then detailed to obtain place_ids. It does not name alternatives to use instead (e.g., wanderlog_search_hotels or wanderlog_search_guides) or state exclusions, so when-not guidance is missing.

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

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.

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

With no annotations, the description carries the burden and mostly succeeds: it discloses exactly what is preserved (blocks stay in place), what is created (empty day sections), what is destroyed (day sections out of range), and the default refusal-with-loss-list behavior. Gaps remain around the success return value, reversibility of a forced deletion, and any permission requirements.

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 primary effect, then a clearly labeled SAFETY block, then a scope-exclusion sentence. Every sentence contributes a distinct fact and the paragraphing makes the destructive path scannable.

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 a mutation tool with no annotations and no output schema, the description covers the destructive path, the guardrail, content preservation, and section scope well. Minor omissions are what a successful call returns and confirmation that the trip itself must already exist.

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% and the force parameter is already documented in detail in the schema, including its default and refusal semantics. The description reinforces force's purpose but adds no new syntax or format meaning for start_date, end_date, or trip_key beyond what the schema states.

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+resource: 'Changes the date range of an existing Wanderlog trip.' The following sentences delineate exact scope (per-day sections only), which cleanly separates it from siblings like wanderlog_rename_day, wanderlog_add_section, and wanderlog_update_section.

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 clear operating conditions: it refuses destructive shrinks by default, lists the lost content, and tells the agent to either pass force:true or move content first. It also states the out-of-scope sections (Hotels, Flights, Transit, Places-to-visit), implicitly routing those needs elsewhere, though it never names a specific sibling tool to use instead.

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