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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: items start unchecked, can be ticked off in the app, and the tool returns a confirmation with title and item count. However, it doesn't cover potential errors, permissions, or rate limits, leaving some 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 description is well-structured and front-loaded with the core purpose, followed by usage guidelines and return information. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

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?

Given no annotations and no output schema, the description does a good job covering the tool's purpose, usage, and basic behavior. However, as a mutation tool, it could benefit from more details on error handling or side effects, though the return confirmation is adequately described.

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 parameters. The description adds value by explaining the purpose of items ('Each string becomes one checkbox item, initially unchecked') and providing context for day parameter usage in common patterns, but doesn't elaborate on trip_key or title 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 clearly states the verb ('Adds') and resource ('a checklist to a Wanderlog trip'), making the purpose specific and unambiguous. It distinguishes this tool from siblings like wanderlog_add_expense or wanderlog_add_note by focusing on checklists, not other trip components.

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 provides explicit guidance on when to use this tool, including 'Add at least one checklist per trip' and common patterns for different contexts (e.g., 'On the trip (no day)', 'On day 1', 'On specific days'). It also distinguishes usage from siblings by specifying checklist-specific scenarios, though it doesn't explicitly name 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?

No annotations provided, so description carries full burden. It discloses the effect (expense appears in budget tracker linked to place) and return value, but lacks details on side effects, idempotency, or constraints like duplicate prevention.

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: action, usage guidance, return value. No redundant information, well-structured for quick parsing.

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?

Adequate for a simple add operation with 7 parameters. Provides usage context and return description, but could mention validation or error handling. No output schema and no annotations, so more detail would be beneficial.

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 parameters are well-documented. The tool description reinforces the overall purpose but adds no new semantic information beyond what's in the schema's parameter descriptions.

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 clearly specifies the action (adds), resource (budget expense), and context (to a Wanderlog trip linked to a place). This distinguishes it from sibling tools like adding places or checklists, which serve different purposes.

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 explicit when-to-use context ('Use this after adding places to give the trip a cost dimension') and a prerequisite ('The place must already exist in the trip'). No explicit exclusions or alternatives are needed given the sibling list.

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 full burden. It discloses that the tool creates a section automatically if needed and describes the return format ('confirmation with the resolved hotel name and the booking window'). However, it doesn't mention important behavioral aspects like whether this is a write operation (implied but not stated), what permissions are needed, or potential error conditions.

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 perfectly sized at three sentences, each earning its place. It's front-loaded with the core purpose, followed by important behavioral context (automatic section creation), and concludes with return value information. Zero waste or redundancy.

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 4-parameter write operation with no annotations and no output schema, the description does well by explaining the core functionality, automatic section creation, and return format. However, it could be more complete by explicitly stating this is a write operation and mentioning any prerequisites or constraints beyond what's in the parameter schemas.

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 parameters thoroughly. The description doesn't add any additional parameter semantics beyond what's in the schema descriptions. It mentions the parameters indirectly ('with check-in and check-out dates') but provides no new information about their usage or meaning.

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 clearly states the specific action ('Adds a hotel booking'), target resource ('to a Wanderlog trip'), and scope ('with check-in and check-out dates'). It distinguishes from sibling tools like wanderlog_add_place or wanderlog_add_expense by focusing specifically on hotel bookings rather than generic items.

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 provides clear context about when to use this tool - specifically for adding hotel bookings to trips. It mentions automatic creation of a 'Hotels and lodging' section if needed, which is helpful guidance. However, it doesn't explicitly state when NOT to use it or mention alternatives among the sibling tools.

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 burden of behavioral disclosure. It effectively explains that notes 'appear inline between places in a day' and serve as 'connective tissue,' clarifying their role in itinerary construction. It also mentions the return value ('confirmation of where the note was added'), though it doesn't detail permission requirements or mutation effects beyond the implied creation action.

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 efficiently structured: the first sentence states the purpose, the second explains the functional role, and subsequent sections provide usage guidelines and examples without redundancy. Every sentence contributes directly to tool understanding, making it front-loaded and waste-free.

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?

Given the tool's moderate complexity (3 parameters, no annotations, no output schema), the description is largely complete. It covers purpose, usage context, and behavioral role, though it lacks details on error conditions, authentication needs, or the exact format of the return confirmation, which would be beneficial for full agent guidance.

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%, providing baseline documentation for all parameters. The description adds minimal semantic value beyond the schema, only implying through examples that 'text' should be practical travel advice rather than arbitrary content, but doesn't elaborate on parameter interactions 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 clearly states the specific action ('Adds a text note to a Wanderlog trip') and resource ('Wanderlog trip'), distinguishing it from sibling tools like wanderlog_add_place or wanderlog_add_expense by focusing on textual annotations rather than physical locations or financial items.

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 provides explicit guidance on when to use this tool ('after adding each place or group of places') and includes five concrete examples of appropriate note content (e.g., transportation tips, booking advice), giving clear context for application without needing to specify exclusions.

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 full burden and does well at disclosing key behaviors: it explains the place matching logic ('Searches for the place near the trip's destination, picks the best match'), clarifies where the place gets inserted ('either a specific day or the general "Places to visit" list'), describes the note attachment mechanism, and mentions the return format. It doesn't cover error cases or rate limits, but provides substantial operational 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?

The description is efficiently structured with clear paragraphs: first stating the core operation, then providing usage guidance for parameters, then clarifying when to use alternatives, and finally describing the return. Every sentence adds value with zero redundant information, and it's appropriately sized for a 6-parameter tool with complex sibling relationships.

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 tool with 6 parameters, no annotations, and no output schema, the description does well: it covers the core operation, parameter usage, sibling differentiation, and return information. The main gap is lack of explicit error handling or permission requirements, but given the rich parameter guidance and behavioral context, it's mostly complete.

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 baseline is 3. The description adds meaningful context beyond the schema: it explains the practical use of the note parameter ('transit directions, what to order, booking tips, time guidance'), clarifies the relationship between start_time and end_time, and provides guidance on when to use versus omit parameters. This elevates the score above baseline.

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 clearly states the verb 'Adds' and resource 'a place to a Wanderlog trip', specifying the exact operation. It distinguishes from siblings like wanderlog_add_note by explaining this tool attaches notes directly to places rather than creating separate note blocks, and from wanderlog_search_places by emphasizing it picks the best match and inserts into the itinerary.

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 provides explicit guidance on when to use this tool versus alternatives: it states 'PREFERRED: Use the "note" parameter... This is better than a separate wanderlog_add_note call' and specifies 'Use standalone wanderlog_add_note only for freestanding commentary between places.' It also clarifies when to use start_time/end_time parameters and when to omit the day parameter.

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 full burden and provides valuable behavioral context: it explains that updates can include notes or times, mentions the natural-language resolution with disambiguation behavior, and states that changes require at least one update field. However, it doesn't cover potential errors, permissions, or mutation side effects.

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 front-loaded with the core purpose, followed by usage guidance and constraints in clear, efficient sentences. Every sentence adds value without redundancy, making it easy to scan and understand quickly.

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 does well by explaining what the tool does, when to use it, and key behaviors like disambiguation. However, it lacks details on return values or error handling, which would be helpful given the complexity of natural-language place resolution.

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 parameters thoroughly. The description adds minimal value beyond the schema, such as hinting at the purpose of 'note' ('Practical context: transit, tips, timing, what to see') and referencing sibling syntax, but doesn't significantly enhance parameter understanding.

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 clearly states the specific action ('Updates an existing place'), resource ('in a Wanderlog trip'), and scope ('with an inline note, start/end time, or both'). It distinguishes from siblings like wanderlog_add_place (adds new) and wanderlog_remove_place (removes), making the purpose unambiguous.

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?

Explicit guidance is provided: 'Use this to enrich places that were already added' clarifies when to use versus alternatives like wanderlog_add_place for new places. It also specifies prerequisites ('At least one of note, start_time, or end_time must be provided') and references sibling wanderlog_remove_place for context.

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 burden of behavioral disclosure. It effectively describes key behaviors: the trip is created empty with pre-generated day sections, returns a trip key for reference, and provides practical guidance about what makes a good itinerary. It doesn't mention error conditions or rate limits, but covers the essential creation workflow thoroughly.

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 appropriately sized and front-loaded with the core purpose in the first sentence. The subsequent guidance about populating the trip is valuable but somewhat lengthy. Every sentence serves a purpose, though some could be more concise. The structure flows logically from creation to population guidance.

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 creation tool with no annotations and no output schema, the description provides excellent contextual completeness. It explains the creation outcome (empty trip with day sections), the return value (trip key), and comprehensive guidance on how to use sibling tools to build a complete itinerary. This addresses the complexity of trip creation in Wanderlog's ecosystem effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the baseline is 3. The description doesn't add any parameter-specific information beyond what's already documented in the schema descriptions. It mentions 'destination and date range' generically but provides no additional syntax, format, or usage details about the parameters.

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 clearly states the specific action ('Creates a new Wanderlog trip') with precise resource details ('for the given destination and date range') and distinguishes it from siblings by explaining it creates an empty trip with pre-generated day sections, unlike other tools that add content. The first sentence provides a complete purpose statement.

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 provides explicit guidance on when to use this tool (to create a new empty trip) and when to use alternatives, listing four specific sibling tools (wanderlog_add_place, wanderlog_add_note, wanderlog_add_hotel, wanderlog_add_checklist) that should be used together after creation to populate the trip. It also explains the relationship between tools for creating a complete itinerary.

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 fully discloses behavior: case-insensitive search, scope across note types, handling of no matches (error) and multiple matches (numbered previews), and in-place replacement when exactly one match is found. It also mentions the optional day filter. Could add return value details.

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 concise at 8 sentences, well-structured with the main action first, then behavioral details and optional filter. Every sentence provides useful information without redundancy.

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 description covers search scope, match handling, and optional filter but lacks specification of the return value on success (e.g., confirmation or updated content). Given no output schema, this omission reduces completeness.

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 value by explaining search behavior (case-insensitive, multiple match handling) and clarifying the day format flexibility. It extends beyond the schema's brief parameter descriptions.

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 clearly states it edits note content by finding and replacing a substring, specifying the resources (freestanding notes, place annotations, checklist items). It distinguishes from sibling tools like wanderlog_add_note and wanderlog_remove_note.

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 explains when to use the tool (to replace a substring), how it handles matches (single, none, multiple), and provides guidance on using a more specific substring or the day filter. It does not explicitly state when not to use it, 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?

No annotations provided, so description must carry full burden. It implies a read operation ('fetches'), but does not explicitly state idempotence, side-effect-free nature, or authentication requirements. Adequate but lacks explicit behavioral traits.

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?

Two sentences, front-loaded with purpose, no unnecessary words. Efficient and clear.

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, but description indicates return type ('readable text') and contents (sections, places, notes). With 3 parameters all documented, description is nearly complete; could specify response format more explicitly.

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 baseline is 3. The description adds value by connecting guide_key to wanderlog_search_guides, providing context beyond schema definitions.

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?

Clearly states the tool fetches full content of a public Wanderlog guide (sections, places, notes) and renders as text. Distinguishes from sibling wanderlog_get_trip by specifying scope (public vs. own 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?

Explicitly tells when to use: after obtaining a guide_key from wanderlog_search_guides. Also instructs when not to use: for own trips, use wanderlog_get_trip instead. Provides clear 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 provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it returns itinerary data, supports optional day filtering, and offers two output formats with clear distinctions. However, it doesn't mention potential limitations like rate limits, authentication requirements, or error conditions, leaving some behavioral aspects unspecified.

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 perfectly structured and front-loaded: the first sentence states the core purpose, followed by specific usage guidelines for format selection, and ends with prerequisite guidance. Every sentence serves a distinct purpose with zero redundancy, making it highly efficient and easy to parse.

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?

Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description provides excellent coverage of purpose, usage, and parameter context. It falls slightly short by not describing the return structure or potential error cases, which would be helpful since there's no output schema. However, it compensates well with clear behavioral guidance for a read-only 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?

The input schema has 100% description coverage, providing a strong baseline. The description adds meaningful context by explaining the practical use of parameters: it clarifies that trip_key comes from wanderlog_list_trips, gives examples of day filter formats, and most importantly, explains when to choose 'concise' vs 'detailed' response_format based on user intent, which goes beyond the schema's technical descriptions.

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 clearly states the tool's purpose with specific verbs ('returns the itinerary') and resources ('one Wanderlog trip'), listing exactly what it returns: hotels list, places to visit list, and each day's scheduled places. It distinguishes itself from sibling tools like wanderlog_list_trips (which finds trip keys) and wanderlog_get_trip_url (which presumably returns a URL rather than itinerary content).

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 provides explicit guidance on when to use this tool versus alternatives: it instructs to call wanderlog_list_trips first if the trip_key is unknown, and it specifies when to use 'concise' versus 'detailed' formats based on user needs (summarizing vs. specific info requests). This covers both prerequisites and format selection criteria.

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 burden. It effectively discloses behavioral traits: it's a read-only operation (returns a URL), describes permission levels for each mode (full-permission, read-only, suggest-mode), and mentions sharing implications. However, it doesn't cover potential errors (e.g., invalid trip_key) or rate limits, 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?

The description is front-loaded with the core purpose, followed by structured details about mode variants and a clear default rule. Every sentence earns its place: the first states the goal, the next explains mode options, and the last provides usage guidance. No wasted words, and it's appropriately sized for the tool's complexity.

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?

Given no annotations and no output schema, the description does well by covering purpose, usage, and parameter context. However, it doesn't specify the return format (e.g., a string URL) or error handling, which could be useful for an agent. For a simple URL-fetching tool, it's nearly complete but has minor omissions.

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 baseline is 3. The description adds value by explaining the practical meaning of mode variants beyond the schema's enum list: it clarifies that 'edit' is for owners, 'view' is safe to share, and 'suggest' allows collaborators to propose changes. This enhances understanding but doesn't fully detail trip_key semantics beyond referencing wanderlog_list_trips.

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 clearly states the verb ('Returns') and resource ('the wanderlog.com URL for a trip'), specifying it's for opening in a browser. It distinguishes from siblings like wanderlog_get_trip (which likely returns trip data) and wanderlog_list_trips (which lists trips), focusing specifically on URL generation rather than trip content manipulation.

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 provides explicit guidance on when to use different modes: 'edit' for owners, 'view' for safe sharing, and 'suggest' for collaborative proposals. It also offers a decision rule: 'If you don't know which mode the user wants, default to edit.' This gives clear alternatives and a fallback strategy.

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 full burden and does well: it discloses authentication requirement ('authenticated user's account'), scope of data returned ('owned and shared-with-you'), return format details ('compact list with title, dates, place count, and trip_key'), and specific extraction instruction for downstream use. It doesn't mention rate limits or pagination, but covers essential behavioral aspects.

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 well-structured sentences with zero waste: first states purpose and scope, second provides usage guidance, third gives implementation detail. Every sentence adds value and is front-loaded with key information.

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 list tool with 1 parameter and no output schema, the description is quite complete: covers purpose, authentication, scope, return format, and usage guidance. It doesn't explain the exact structure of returned data or error conditions, but provides enough context for effective use given the tool's complexity.

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 fully documents the single parameter. The description doesn't add any parameter-specific information beyond what's in the schema. Baseline 3 is appropriate when schema does all the parameter documentation work.

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 clearly states the verb ('Lists') and resource ('all Wanderlog trips'), specifies scope ('in the authenticated user's account'), and distinguishes from siblings by noting it returns trip_key needed by wanderlog_get_trip and wanderlog_search_places. It goes beyond a simple restatement of the name/title.

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 use this tool ('when the user mentions a trip by name but you don't have its trip_key yet') and names specific alternative tools (wanderlog_get_trip, wanderlog_search_places) that require the key obtained from this tool. Provides clear context for tool selection.

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?

The description fully discloses behavioral traits: case-insensitive matching, exact match vs multiple matches vs no match outcomes, and the optional day filter. Since no annotations are provided, the description carries the full burden and meets it well.

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 concise (4 sentences) and well-structured: first sentence states purpose, then details matching, multiple match handling, and optional filter. No redundant or unnecessary information.

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?

Given the absence of an output schema, the description explains the outcomes: deletion, no match error, multiple match previews. It does not specify the exact format of the preview or success response, but it is largely complete for the tool's complexity.

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?

The schema already describes each parameter, but the description adds context about case-insensitivity, the nature of the text substring, and the day format ('day 2', 'May 4', ISO). This enriches the parameter 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 clearly states that the tool removes a note block from a Wanderlog trip by matching a substring of its text content. The verb 'removes' and resource 'note block' are specific, and it distinguishes itself from sibling tools like wanderlog_add_note (adds) and wanderlog_edit_note (edits).

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 explains the matching behavior (case-insensitive, substring), how to handle multiple matches (supply more specific substring), and the optional day filter. It does not explicitly compare to alternative tools or state when not to use it, but the context is clear for the intended use.

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 burden of behavioral disclosure. It clearly describes the tool's behavior: it removes items, handles ambiguous references by returning a numbered list without making changes, and requires re-calling with more specific inputs. This covers key operational traits like mutation effects and error handling, though it doesn't mention permissions 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 appropriately sized and front-loaded, starting with the core purpose and immediately following with detailed reference forms and behavioral notes. Every sentence adds value, with no wasted words, and the structure logically flows from general to specific usage scenarios.

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?

Given the tool's complexity (mutation with natural-language parsing) and no annotations or output schema, the description does well by explaining behavior, reference formats, and ambiguity handling. However, it lacks details on return values (e.g., what happens on successful removal) and potential error cases beyond ambiguity, leaving minor gaps in completeness.

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 baseline is 3. The description adds significant value beyond the schema by detailing supported reference forms (e.g., exact/partial names, role keywords, day filters, ordinal prefixes, combinations) and providing examples of how 'place_ref' works in practice. This enhances understanding of parameter usage, though it doesn't fully explain 'trip_key' beyond what the schema provides.

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 clearly states the verb ('removes') and resource ('a place from a Wanderlog trip'), specifying it applies to any block type (place, flight, train, hotel). It distinguishes from siblings like 'wanderlog_add_place' by being the removal counterpart, making the purpose specific and differentiated.

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 explicitly states when to use this tool: to remove items based on natural-language references. It provides clear guidance on when not to use it (when references are ambiguous, as it returns a list without changes) and how to handle alternatives (re-call with more specific filters). This covers both usage context and exclusions effectively.

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 full burden. It clearly states the effect (renames heading), explains what headings are (itinerary titles), and documents the reset behavior. It does not mention side effects beyond renaming, but for a simple rename tool this is sufficient.

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 concise with three short sentences, each earning its place: first states the action, second provides context, third handles edge case. It is front-loaded and has no unnecessary words.

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?

Given the tool's simplicity (rename a day heading) and the absence of an output schema, the description fully covers behavior, parameter details, edge cases, and context (headings appear in itinerary). No gaps remain.

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%, but the description adds value beyond the schema: it clarifies that 'day' accepts multiple formats (e.g., 'day 3', 'May 4') and that 'heading' can be empty to reset. This enhances understanding of parameter usage beyond the schema's property descriptions.

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 explicitly states the tool renames day headings in a Wanderlog trip, using a specific verb and resource. It distinguishes itself from sibling tools (e.g., wanderlog_edit_note, wanderlog_remove_place) by being the only one focused on renaming day headings.

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 explains when to use the tool (replace headings with more descriptive titles) and includes a special case (empty string resets to auto-generated heading). While it does not explicitly mention when not to use it, the sibling tools cover different operations, making the intended usage 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 provided, so description carries full burden. It discloses auto-pick behavior for free-text destinations, limited alternatives, and fallback alternatives when no guides exist. Does not mention authentication or rate limits, but covers key behaviors.

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 purpose, followed by usage guidance and parameter details. Every sentence adds value, no fluff. Well-structured for quick scanning.

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?

Even without an output schema, the description explains what the response contains based on response_format, including fields and alternative geos. Also provides next step: use wanderlog_get_guide. Complete for a search 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%, baseline 3. Description adds value by explaining the auto-pick logic for destination, the mutual exclusivity of destination/geo_id, and the meaning of alternative_geos and alternative_geos_with_guides fields.

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 clearly states 'Lists user-written Wanderlog travel guides for a destination' and distinguishes from siblings like wanderlog_search_places and wanderlog_get_guide by specifying the resource and the follow-up action.

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 tells when to use: 'Use this when the user asks for inspiration, an itinerary they can copy, or "what guides exist for X".' Also provides constraints and alternatives: 'Specify exactly one of destination or geo_id' and 'Pass the returned guide_key to wanderlog_get_guide'.

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 burden of behavioral disclosure. It effectively describes key behaviors: results are geographically biased toward the trip's location (not global), it returns candidate results with names and short descriptions, and it supports two response formats with different outputs. However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions.

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 efficiently structured with four focused sentences that each add value: first states purpose, second explains usage context, third clarifies geographic scope, and fourth provides workflow guidance. There's no redundant information, and key points are front-loaded appropriately.

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 search tool with 3 parameters, 100% schema coverage, and no output schema, the description provides strong contextual completeness. It explains the tool's purpose, usage scenarios, geographic behavior, and format differences. The main gap is the lack of output details (what exactly is returned beyond 'names and short descriptions'), but given the schema coverage and clear behavioral context, this is a minor limitation.

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 parameters well. The description adds meaningful context by explaining that results are 'geographically biased toward the trip's destination' (enhancing trip_key understanding), providing query examples like 'sushi restaurant', and clarifying the purpose difference between 'concise' and 'detailed' formats beyond the schema's technical descriptions.

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 clearly states the tool searches for real-world places near a Wanderlog trip destination, specifying the resource (places) and action (search). It explicitly distinguishes this from sibling tools like wanderlog_add_place by focusing on search rather than addition, and mentions specific place types (restaurants, attractions, hotels, parks, landmarks).

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 provides explicit guidance on when to use this tool: for resolving user requests like 'find a good coffee shop' into place candidates, and for preparing to add places to a trip. It distinguishes usage between 'concise' format for presenting options and 'detailed' format for obtaining place_ids for downstream actions, offering clear alternatives within the tool itself.

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 full burden and delivers comprehensive behavioral disclosure. It explains content preservation logic ('Preserves content on days that remain...'), safety mechanisms ('refuses by default and returns a list of the content that would be lost'), override behavior with force parameter, and scope limitations regarding other trip sections.

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 efficiently structured with clear sections: core functionality, safety behavior, and scope limitations. Every sentence adds essential information with zero waste. It's appropriately sized for a tool with significant behavioral complexity.

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 provides complete context: it explains what the tool does, when to use it, safety considerations, parameter implications, and limitations. The behavioral transparency section compensates for the lack of structured annotations.

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 baseline is 3. The description adds meaningful context beyond the schema: it explains the consequences of the force parameter ('allows the update even when it would delete days that currently contain places') and clarifies that days are added/removed based on date range changes, providing valuable semantic understanding.

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 clearly states the specific action ('Changes the date range'), target resource ('existing Wanderlog trip'), and scope ('only the per-day sections are added/removed'). It distinguishes from sibling tools like wanderlog_add_hotel or wanderlog_remove_place by specifying it only affects day sections, not other trip components.

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 provides explicit guidance on when to use this tool vs alternatives: it states 'Does not affect the Hotels, Flights, Transit, or Places-to-visit sections', implying those require different tools. It also gives clear prerequisites: 'move the content to other days first' before using force parameter.

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