nomadpoint

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

Annotations already indicate a write operation (readOnlyHint: false) and non-destructive behavior (destructiveHint: false). The description adds meaningful beyond-annotation context by noting the tool works without a scan and, crucially, that it also adds the country to the user's nationalities—an important side effect for visa computations. This goes beyond the basic write/read flags, though it doesn't cover all possible behaviors like duplicate handling.

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 sentences, each contributing essential information: the primary action and the key side effect. There is no fluff or redundant restatement of the tool name, making it highly concise and well-structured.

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 conveys the core action and an important side effect, but given there is no output schema and only partial parameter documentation, it leaves gaps about return values, parameter usage, and edge cases. It's adequate for a straightforward create operation but not fully complete for an agent to understand all consequences.

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 only 33% (only issue_date and expiry_date have descriptions), and the description does not mention any parameters by name or explain their semantics. The phrase 'from its details alone' is vague and does not help an agent understand required vs optional fields or what each parameter represents. With low schema coverage, the description was expected to compensate but did not.

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 records a passport from details alone, which is a specific verb and resource. It distinguishes from potential scan-based workflows by adding '(no scan needed)' and highlights the side effect of adding the country to nationalities. However, it doesn't explicitly differentiate from sibling create_* tools beyond the resource type, so it's clear but not maximally distinguishing.

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 implies usage when passport details are available and no scan is required, but it doesn't explicitly state when not to use it or name alternative tools. The side-effect note ('adds the country to the user's nationalities') provides some cautionary context, but there's no direct comparison to other tools like create_visa or update_* functions.

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 are minimal and do not describe behavior beyond non-read-only status. The description adds only that the accommodation is 'booked' and is a 'place to stay,' but it does not disclose important behavioral aspects such as required prerequisites (e.g., journey existence), failure modes, or how the created record behaves for the trip.

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 a single, front-loaded sentence with no wasted words. It would benefit from more detail given the tool's complexity, but as far as conciseness and structure, it is efficient and readable.

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 17 parameters, low schema coverage, and no output schema, this description is too thin to fully orient an agent. It omits required-field context, relationships to sibling tools, and any sense of expected outcome or constraints.

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 low at 41%, so the description should compensate by explaining parameter meaning, but it does not. The type examples overlap with the schema's type enum, and the description gives no additional semantics for the 17 parameters or the two required 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 the action ('Add') and resource ('booked place to stay ... to a trip'), with type examples (hotel/hostel/apartment). However, it does not distinguish create_accommodation from the sibling create_stay, so the tool's unique role among siblings remains unclear.

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?

No guidance is provided about when to use this tool versus create_stay or the other creation tools. The word 'booked' implies a post-booking context, but no explicit when-to-use or when-not-to-use scenarios are given.

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 are all false/noisy (readOnlyHint=false, destructiveHint=false, etc.), so they provide little signal; the description carries the burden and adds useful workflow context by clarifying the conceptual difference between a stay and accommodation. The only gap is not describing what happens on duplicate calls or how the stay relates to check-in/checkout dates, but since annotations don't declare idempotency or safety, there's no contradiction and the description does enough.

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 dense sentences, zero wasted words. The em-dash aside is genuinely useful, not decorative, and the pointer to create_accommodation serves double duty as both usage guidance and differentiation. Every phrase earns 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?

For a create tool with 9 params, no enums, no nested objects, and no output schema (so nothing to describe about return values), the description covers the essential workflow context well. It fully explains the conceptual model needed to use the tool correctly. Slightly more emphasis on preconditions (e.g., does the trip need to exist? what happens with overlapping stays?) would push it to a 5, but the current coverage is solid.

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 67% (6/9 params documented), just under the 80% threshold for a baseline-3. The description itself contributes no parameter-level semantics, and the undocumented params (journey_id, notes, checkout_flexible) are relatively self-explanatory. The description stays within its lane — neither helping nor hurting — landing at a solid 3 for acceptable-but-unremarkable parameter support.

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?

Uses a specific verb-resource pair ('Add a stay...to a trip') and immediately clarifies the domain meaning with the parenthetical 'a stop in a city'. It distinguishes itself from its closest sibling (create_accommodation) by explaining that a stay gets a destination onto the itinerary, which is exactly the kind of scoping the rubric rewards.

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 positions the tool within the workflow ('This is how a destination gets onto the itinerary') and names the exact alternative ('book lodging for it with create_accommodation on the same dates'). This tells the agent when to use this tool versus the confusable sibling, and even implies a temporal relationship between the two calls.

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 annotation sets 'destructiveHint' to true, and the description says 'Remove', which implies a destructive operation. However, there is no statement about whether the action is reversible, permanent, or has side effects on other trip data. The absence of such details reduces transparency for a delete 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?

The description is concise and to the point, consisting of a single clear sentence. It avoids unnecessary verbosity, making it easy to read. However, it could be structured to include more details without losing conciseness, but overall it is appropriately brief for a simple delete action.

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 provides minimal context: it mentions 'the trip', implying a travel-planning domain, but does not clarify the relationship between the accommodation and the trip, or what happens after deletion. There is no output schema, and the parameter's format is unspecified, leaving a significant completeness 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?

The single parameter 'accommodation_id' is not described in the schema (0% coverage), and the description only refers to 'a booking' without explaining that this ID is required. While the parameter name is self-explanatory, the description does not explicitly map it to the booking, leaving room for ambiguity about what exactly is removed.

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 action ('Remove') and the object ('a booking from the trip'), which unambiguously conveys that this tool deletes an accommodation booking. The tool name 'delete_accommodation' reinforces this intent, so there is no confusion about the tool's purpose.

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 no guidance on when to use this tool, what prerequisites exist (e.g., the booking must already be added to the trip), or what the effect is on the overall trip plan. It is a bare statement of action, leaving the user without context on how or when to invoke 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent knows it's a destructive operation. The description adds the scope (an activity from a trip) but does not disclose side effects like cascading deletions or irreversibility beyond the annotation's implication. Given the strong annotation coverage, this is adequate.

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 a single sentence, highly concise, and front-loaded with the action. Every word is necessary and provides clear meaning. There is no verbosity 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?

Given the simplicity of the tool (one parameter, no output schema, no nested objects), the description is sufficiently complete. It states the action and the resource. It could mention that the deletion is permanent or that the activity must exist, but the annotation (destructiveHint) covers the destructive nature. Overall, it meets the needs for a simple delete 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 description coverage is 0%, but the tool has only one parameter (activity_id). The description implicitly conveys that the parameter is the identifier of the activity to delete, but it does not explicitly state the format or source. Since the schema provides the name and type, and the tool's purpose is clear, the description adds enough context for a single simple parameter.

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 'Remove an activity from the trip.' clearly specifies the action (remove) and the resource (activity from a trip). It is distinct from sibling tools like delete_accommodation or update_activity, so the agent can easily identify what this tool does.

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 implies when to use the tool: when you need to remove an activity from a trip. It does not explicitly state when not to use it or mention alternatives (e.g., for deleting other resources). However, the context is clear enough for a simple delete operation.

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, so the description's 'Remove' is consistent. However, it adds no extra behavioral context beyond what annotations provide (e.g., irreversibility, impact on related data). The description is adequate but not enhanced.

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 a single, concise sentence with no redundancy. It is front-loaded with the verb and object, and every word is necessary.

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 (one parameter, no output schema) and that annotations cover the destructive nature, the description is minimally complete. However, it could mention that the operation is permanent or that the flight must exist, though not strictly required. It is adequate but lacks any extra context.

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 0%. The description does not mention the flight_id parameter or its purpose. Although the parameter name is self-explanatory, the description fails to compensate for the lack of schema coverage, leaving the agent to infer the identifier's role.

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 'Remove a flight from the trip' clearly states the action (remove) and the resource (flight) within the trip context. It is specific and distinguishes from sibling delete tools for other entities.

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 the purpose but no explicit guidance on when to use this tool vs alternatives or any prerequisites. The context (deleting a flight) is implied but no exclusions or alternative references are provided.

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 indicate destructiveHint=true and readOnlyHint=false, but the description goes further by detailing the exact consequences: it deletes stops, flights, bookings, activities, and affects every member. It also adds 'Irreversible' and 'Owner only' which are not in annotations. This provides substantial behavioral context beyond the structured data, warning agents about the permanent and broad impact.

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 sentences, perfectly concise. The first sentence states the core function and scope, the second adds permissions and a warning. No redundant words or filler. It is front-loaded with the most critical information and earns every word.

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 delete tool with one parameter and no output schema, the description covers all essential aspects: the exact effect (deletes the trip and all sub-items), the scope (for every member), the permission requirement (owner only), and the irreversibility with a confirm-first instruction. This is complete given the tool's simplicity and the presence of destructiveHint.

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 lists only journey_id as a string with no description, and the tool description has 0% schema coverage. However, the description mentions 'a trip' which implies that journey_id is the trip's identifier, adding some semantic context. It does not explicitly explain how to obtain the ID or format expectations, but for a single simple parameter, the implied meaning might be sufficient. Still, it falls short of fully documenting the parameter's purpose.

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: 'Permanently delete a trip and everything on it — stops, flights, bookings, activities — for every member.' It specifies the verb (delete), resource (trip), and scope (everything on it, for every member), and distinguishes it from sibling delete_* tools that target individual items. The inclusion of 'travel' and the specific list of sub-items makes it 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?

The description provides usage context: 'Owner only' indicates who should use it, and 'Irreversible; confirm with the user first' gives a clear prerequisite. While it doesn't explicitly name alternatives like 'use delete_flight for a single flight' or 'use leave_journey to leave without deleting', the emphasis on 'everything on it' for every member implicitly contrasts with lighter deletion or leave options. This is strong but not fully explicit about when not to use 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?

The annotations explicitly declare destructiveHint: true, and the description's 'Delete' is fully consistent with that, so there is no contradiction. However, beyond that alignment, the description discloses nothing additional — no mention of irreversibility, cascade effects on related journeys, or any confirmation behavior. Annotations already carry the safe-destructive profile, and the description adds no further behavioral color.

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 a single, front-loaded sentence with zero filler — 'Delete a recorded visa.' Every word is purposeful and the statement is immediately scannable. The brevity is a genuine strength, and the structure could not reasonably be improved for this trivial delete operation.

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 minimally complex tool (one string parameter, no output schema, no enums), the description is close to sufficient — the destructiveness is covered by annotations and the purpose is clear. However, in the context of a travel-app domain (create_journey, list_visas, etc.), a note on whether deleting a visa cascades to journeys or whether it can be undone would materially improve completeness. The core use case is served, but edge-behavior questions remain unanswered.

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 0% schema description coverage, the description carries the burden of explaining visa_id, but 'a recorded visa' is all it offers. It never explains that visa_id is an identifier, what format it follows, or where to obtain it (e.g., from list_visas). A single clarifying phrase like 'the ID returned by list_visas' would have turned this into a 4, but as-is the agent is left to infer the ID's provenance and type.

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 'Delete' as the verb and 'a recorded visa' as the resource, precisely matching the tool's name and unambiguously distinguishing it from the sibling delete_document, delete_flight, and delete_* tools targeting other entities. The word 'recorded' adds a small but meaningful scope qualifier, making the purpose crystal clear.

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?

There is zero guidance on when to use this tool versus alternatives. No exclusions are provided (e.g., 'use this instead of update_visa to remove a visa'), no prerequisites are mentioned, and there is no pointer to related tools like list_visas for finding the visa_id. The description offers no context for the decision of when to invoke this tool.

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 explains the return structure including the nuance of booked stays appearing in both lists, complementing the readOnly and idempotent annotations. No side effects are implied, and the closure is appropriate.

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, well-structured, and uses clear punctuation. It conveys essential information in two sentences without unnecessary verbosity.

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 the main output components and the filtering capability, and the annotations handle safety aspects. It does not specify error handling or default behavior, but these are not critical for completeness given the tool's simplicity.

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 optional date parameters are clarified with their purpose, and journey_id is implicitly understood. The schema descriptions for dates are minimal, but the description adds meaningful context.

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 function ('Get one journey's itinerary') and lists the included components (stays, flights, booked accommodations, activities), distinguishing it from sibling tools that operate on multiple journeys.

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 practical guidance on using date parameters ('Pass from_date/to_date to read one window of a long trip instead of all of it'), though it does not explicitly compare with alternatives like list_journeys.

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 the operation read-only and idempotent; the description adds a meaningful behavioral detail: anyone who opens the link joins immediately, and there is no separate acceptance step. This clarifies the practical impact of sharing the link without contradicting the 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?

The description is a single focused sentence with no filler, restating none of the annotations. It front-loads the essential idea and adds one necessary behavioral nuance about the invitation flow.

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 simple single-parameter input, no output schema, and robust annotations, the description gives the agent key behavioral context (immediate join, no accept step) in an economical way. It still omits an explicit statement that the tool returns the link itself, but the purpose remains inferable from name and description.

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 only parameter, journey_id, has no schema description, and the description itself never explains what value to provide. The phrase 'onto a trip' loosely connects the share link to a journey, but with 0% schema coverage the description should compensate much more explicitly.

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 identifies the resource as the share/invite link for a trip and clarifies its role as a co-editor invitation. It relies on the tool name for the action verb ('get') and uses 'trip' instead of 'journey', so it stops just short of a fully explicit 'returns/retrieves' 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 implies the use case: an agent needs the invite link to add a co-editor, and the link alone is sufficient since there is no separate accept step. It does not explicitly contrast this with sibling tools like list_journey_members or get_journey, so usage guidance remains inferred rather than prescriptive.

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 readOnlyHint=true and idempotentHint=true, so the description doesn't need to repeat that. It adds value by explaining what data is returned (profile, passports, documents) and why it matters ('which decide every visa answer'). This goes beyond the annotations by providing domain-specific 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 two sentences, front-loaded with the core purpose, and every word earns its place. It's concise, informative, and well-structured.

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 (no parameters, no output schema), the description is complete. It explains what the tool returns and why it's important. The only minor gap is that it doesn't explicitly state the return format, but that's not necessary for a zero-parameter tool with no 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?

The tool has zero parameters, and the schema coverage is 100% (empty properties). The description doesn't need to explain parameters, but it does explain the output semantics (what the user gets). Since there are no parameters, a baseline of 4 is appropriate, and the description adds value by clarifying the content of the response.

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: to retrieve the user's profile, passports/nationalities, and passport documents. It uses a specific verb ('get') and resource ('me'), and distinguishes itself from siblings like get_country_info and get_visa_status by focusing on the user's identity data.

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 for when to use this tool: 'Worth reading before planning anything.' It implies this is a foundational tool to call before other actions, but it doesn't explicitly mention alternatives or when not to use it. However, given the tool's unique purpose, this is sufficient.

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, covering the safety profile. The description adds a permission constraint (owners can't leave) which is useful context. However, it does not disclose side effects such as removal from the member list or potential failure conditions. Given the annotation coverage, this is adequate but not rich.

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 a single, front-loaded sentence with a clarifying clause, conveying the essential action and a key exclusion with no wasted words. It is concise and well-structured.

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 tool with one parameter and no output schema, the description covers the core purpose and a critical restriction. It does not describe return values or failure modes, but these are less critical given the tool's simplicity and the presence of destructiveHint annotation. The description is complete enough for the agent to use the tool correctly.

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

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

With 0% schema description coverage, the description must compensate. It does not explicitly define journey_id, but the tool name and purpose make it inferable as the ID of the shared trip. For a single simple parameter, this is acceptable, though more explicit documentation would improve clarity.

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 action (leave) and the resource (a trip shared by someone else), and explicitly distinguishes from deletion: 'Owners can't leave their own trip — they delete it.' This differentiates it from sibling tools like delete_journey and makes 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?

The description provides a clear when-not by stating owners cannot use this tool and should delete instead. It implies when to use (when you are a non-owner of a shared trip) but does not explicitly mention alternative tools like remove_journey_member, though that tool is likely intended for owners to remove others. The guidance is solid but not exhaustive.

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 declare readOnlyHint=true and idempotentHint=true, which already communicate safety. The description adds that only metadata is returned, not files, providing behavioral context beyond what annotations cover. This is useful and does not contradict 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?

The description is a single clear sentence that conveys the essential information without fluff. It is front-loaded and efficient, earning a top score.

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 good annotations and a well-described schema, the description is adequate. It clarifies the return scope (metadata not files) but does not explicitly state the output is a list, which is obvious from the context. No significant gaps.

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 includes a single optional parameter with a complete description of allowed values, giving 100% schema coverage. The tool description adds no extra meaning about the parameter, so the baseline score 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 clearly states the tool lists the user's travel documents (passports, visas, etc.) and specifies it returns metadata only, not files. This distinguishes it from sibling tools like add_passport or delete_document, 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?

The description implies this is for retrieving document metadata, but does not explicitly contrast it with alternatives like creating or deleting documents. The context (metadata vs files) and the tool name make usage clear, though explicit alternatives are not stated.

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 readOnlyHint and idempotentHint, so the description does not need to repeat safety. It adds useful scope and output context ('they own or have joined, with dates and whether they own it'), but does not disclose additional behavior such as ordering, pagination, or what happens with an empty trip list.

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 a single, well-structured sentence that immediately states the action, scope, and key output fields. It contains no filler 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 simple, parameterless list tool, the description is fully complete: it identifies what is listed, whose journeys are included, and what information is returned. No output schema exists, but the description covers the essential return-value expectations at the appropriate level of detail.

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 tool has zero parameters, and the schema already fully reflects this with an empty properties object. The description therefore has no parameter semantics to clarify, and a baseline of 4 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 uses a specific verb ('List') and identifies the resource ('the user's trips (journeys) they own or have joined'), plus the key output details (dates and ownership). This clearly distinguishes it from sibling tools like get_journey or list_journey_members.

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 implies the usage context: it is for listing all of the user's journeys rather than a single journey or members. However, it does not explicitly mention alternatives or provide exclusion guidance, so the usage guidance remains implicit rather than explicit.

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 readOnlyHint and idempotentHint annotations already cover behavioral safety. The description adds no extra information about side effects, data sources, or potential errors. It only confirms the scope (user holds), which is minimal added 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 description is a single, concise sentence that lists the key attributes. It is efficiently written and avoids redundancy, though the dash-separated list feels slightly telegraphic. 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?

The description names the fields but does not specify the output structure (e.g., array of objects, ordering, or any filtering). Since there is no output schema, the description should ideally clarify the expected response format. It is partially complete but leaves some ambiguity.

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 tool has no parameters, so there is nothing to describe. The absence of parameters is clear and requires no additional explanation. Perfect score.

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 lists visas the user holds and enumerates key fields (type, number, validity, entries used). This is specific enough to distinguish from create/update/delete operations, though it could be more explicit in saying 'list' or 'retrieve'.

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?

No explicit guidance is provided on when to use this tool. There is no mention of alternatives like get_visa_status or get_visa (if such exists), nor any context about querying a single visa vs. all visas. The description relies solely on the tool name for intent.

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 readOnlyHint=true, idempotentHint=true, and openWorldHint=false, covering the safety profile. The description adds search criteria but no additional behavioral context such as result limits, no-results behavior, or pagination. This is adequate but not rich.

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 a single, front-loaded sentence with no filler or redundant information. Every word contributes to understanding the tool's purpose and primary parameter semantics.

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 read-only search tool with two parameters and strong annotations, the description is mostly complete. It covers the core query semantics and purpose, though it omits limit behavior and explicit sibling differentiation, which would make it fully 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 0%, so the description must compensate. It does clarify that the 'query' parameter accepts an airline name or IATA code, which is valuable. However, the optional 'limit' parameter is left completely unexplained, leaving a gap.

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 uses a specific verb ('Find') and resource ('airlines') with clear search criteria ('by name or IATA code'). It clearly distinguishes this tool from sibling search tools like search_airports and search_cities.

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 clearly implies this tool is for looking up airlines by name or IATA code, which gives enough context for when to use it. However, it does not explicitly mention alternatives or when not to use it, though sibling names make the distinction obvious.

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 readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate that. It adds value by implying the tool returns airport codes and that guessing is not acceptable, which is useful behavioral context. However, it doesn't describe the return format or any pagination, but given the annotations, 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 two sentences, front-loaded with the purpose, and every word earns its place. It's concise and structured effectively.

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 (2 params, no output schema, read-only annotations), the description is complete enough. It explains the purpose, usage context, and the critical requirement to not guess codes. It could mention the limit parameter, but that's a minor 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 0%, so the description must compensate. It mentions the query parameter implicitly ('by city, name or IATA code') but doesn't explain the 'limit' parameter. The description adds some meaning for 'query' but not for 'limit', so it partially compensates but leaves a gap.

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: 'Find airports by city, name or IATA code.' It specifies the resource (airports) and the search criteria, and it distinguishes itself from siblings like search_airlines and search_cities by focusing on airports and mentioning IATA codes.

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 tells when to use this tool: 'Use this to get the codes create_flight requires — never guess them.' This provides clear context and an exclusion (never guess codes), and it names the sibling tool create_flight as the consumer of the output.

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 indicate a non-read-only, idempotent, non-destructive tool, and the description adds useful behavioral context: omitting travellers or passing an empty list means everyone, with everyone being the common case. It does not mention overwriting existing assignments or prerequisites, but the idempotent annotation reduces some of that need.

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 with no filler. It front-loads the core action and immediately gives the most important behavioral default, making it easy for an agent 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?

For a simple setter with no output schema, the description covers the essential behavior and default, while the schema supplies the enum values and traveler-source guidance. It could explicitly mention that this modifies an existing item, but the sibling create/update tools and tool name make that reasonably inferable.

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 only 33%, but the description adds meaningful semantics for the travelers parameter, including empty-list behavior and the default-to-everyone rule. It provides little meaning for item_id or item_type beyond what the enum values themselves show, so it only partially compensates for the low schema 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?

The description gives a concrete outcome ('say which people... an item is for') with helpful examples like 'one person's separate flight, one person's room.' It clearly identifies the resource (item travellers) but does not explicitly state 'assign' or 'update' and does not distinguish itself against sibling tools.

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 tells the agent when subsetting travellers is appropriate by explaining that omitting them means everyone, and that everyone is the default for most items. It does not name alternative tools or state exact when-not-to-use conditions, so it falls short of a 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?

Annotations already declare readOnlyHint=false (modifying), destructiveHint=false (non-destructive), and idempotentHint=true. The description's 'Change' is consistent and adds no contradiction. However, it does not disclose partial-update semantics (e.g., 'only specified fields are updated') or potential failure modes like missing accommodation_id. Given annotations cover safety, this is acceptable but not enriching.

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 a single, concise sentence with no wasted words. It is well-structured and front-loaded with the action and main targets, making it easy to scan.

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 16 parameters, low schema coverage, and no output schema, the description is too sparse. It does not clarify that only provided fields are updated, what 'property' refers to, or what constitutes a successful response. The tool's complexity demands more context to guide correct invocation, making this description inadequate.

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 low (38%), so the description should compensate. It groups parameters into broad categories ('property', 'dates', 'price', 'confirmation', 'notes'), which gives some meaning but omits many fields (latitude, longitude, provider, booking_url, etc.). It does not clarify ambiguous terms like 'property' (name vs. address) or how partial updates work. The description adds marginal value but insufficiently covers the parameter space.

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: 'Change a booking's property, dates, price, confirmation or notes.' It uses a specific verb ('Change') and resource ('a booking's...'), and implicitly distinguishes from sibling update tools by being accommodation-specific. The listed fields align with the schema, 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?

Usage guidance is only implied. The description says what the tool does but does not explicitly state when to use it (e.g., 'Use this when you need to modify an existing accommodation') or contrast with creation/deletion. No alternatives or exclusions are mentioned, leaving the agent to infer that it applies to existing bookings.

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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. However, it adds no extra context about side effects, partial update behavior, or what happens to unspecified fields. It does not contradict the annotations, but it does not enhance transparency either, leaving uncertainty about the update semantics.

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 a single, efficient sentence with no filler or repetition. It is front-loaded with the action and clearly structured. It earns its place by being concise, even though it may be under-specified.

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 17 parameters, only 24% schema coverage, and no output schema, a tool of this complexity needs a richer description. The current one-sentence description does not explain return values, update behavior, or provide any usage context. It is far from complete for an agent to correctly invoke the tool, especially given the lack of guidance on how to use the many parameters.

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 only 24%, so the description must compensate for undocumented parameters. It mentions 'title, timing, place, or notes' but does not explain those or the other 13 parameters (e.g., price, emoji, stay_id). It adds little beyond the schema's few descriptions, and given the low coverage, this is a significant gap.

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 function: changing an activity's title, timing, place, or notes. It distinguishes this from create_activity and delete_activity by using the verb 'change'. However, it only mentions a subset of the fields in the schema (title, timing, place, notes) while the schema includes many more properties like price, emoji, and address, so it is not fully comprehensive but still 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?

The description gives no guidance on when to use this tool versus alternatives. It does not mention that it is for modifying existing activities or that create_activity should be used for new ones. No exclusions, prerequisites, or contextual advice is provided. The only hint is the name and existence of siblings, which is not explicit 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?

Annotations already indicate idempotent, non-destructive, and non-read-only. The description adds no extra behavioral context (e.g., side effects, validation, or failure 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 a single, succinct sentence with no redundant information or unnecessary details.

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 many parameters and sibling operations, but the description does not mention what it returns, how it interacts with search tools, or any side effects. Given no output schema, more context is needed for complete understanding.

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 18 parameters with only 33% descriptions. The description loosely maps some fields (route, times, seat, confirmation, notes) to parameters but does not cover all (e.g., price, currency, airline_code). It provides minimal compensation for the low schema 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?

The description clearly states the action ('Change') and the resource ('a flight'), listing specific attributes (route, times, seat, confirmation, notes). It is distinct from create_flight and delete_flight.

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?

No explicit guidance on when to use this tool versus alternatives. It does not mention that it is for existing flights or require flight_id as a prerequisite, nor does it contrast with create/delete operations.

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 discloses permission requirements ('Owner only') and a notable behavioral consequence ('no missing-stay warnings' for home-base countries). It also mentions archiving as an action. Combined with annotations (idempotentHint=true, destructiveHint=false), this provides good transparency, though it omits details on return values or error handling.

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 a single, well-organized sentence listing actions and a clarifying note. It avoids repetition and fluff, making it easy to parse. The structure is efficient and direct, suitable for an 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 the presence of annotations (idempotent, destructive) and absence of an output schema, the description provides necessary context: what actions are possible, permission requirements, and a specific behavioral nuance. It does not address edge cases or error handling, but that is not always required. Overall, it is sufficiently complete for typical usage.

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 description explicitly covers all parameters: 'rename' for name, 'change dates' for start/end dates, 'change description' for description, 'archive' for is_archived, and 'set home-base countries' for home_base_country_codes. It adds context for home_base_country_codes ('no missing-stay warnings') and aligns with schema descriptions for dates and country codes. The schema covers 43% of parameters descriptively, but the tool description fills in the rest with meaningful actions.

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 resource (journey/trip) and lists actionable verb-object pairs: rename, change dates, change description, archive, set home-base countries. It distinguishes itself from other update_* tools by focusing on journey-specific fields and mentions 'Owner only' to clarify access.

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 implicitly indicates when to use this tool (for updating journey attributes) and provides a usage constraint ('Owner only'). However, it does not explicitly contrast with alternative tools or state when not to use it, but the scope is clear enough for an agent to select it appropriately among 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?

Annotations already indicate idempotent, non-readOnly, non-destructive. The description adds no further behavioral context, such as whether omitted fields are left unchanged or reset to defaults. It doesn't explain the effect of partial updates despite all parameters being optional. With low annotation coverage, it should elaborate more.

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?

A single, front-loaded sentence that packs all relevant info with no redundancy. It efficiently communicates the tool's purpose and main parameters.

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 11 optional parameters and no output schema, the description is relatively complete but leaves gaps: it doesn't mention whether updates are partial or whole, how the tool handles conflicting values (e.g., budget_min > budget_max), or any defaults. The field list is helpful but not exhaustive, and there's no note about idempotency behavior or return value.

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 only 18%, but the description compensates by grouping parameters semantically: 'where home is' (home_city, home_country_code), 'home airport' (home_airport_code), 'currency', 'nightly budget' (budget_min/max), 'travel pace', and 'working hours' (work_start/end/timezone). It covers most fields, though temperature_preference is omitted. This adds meaning beyond the bare 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?

Description clearly states the action ('Set') and the resource ('standing facts every trip should respect'), listing specific fields like home, home airport, currency, nightly budget, travel pace, and working hours. This distinguishes it from sibling tools that target individual trips or resources.

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?

No explicit guidance on when to use this tool versus alternatives, such as update_journey or other update tools. While it implies it's for global preferences, it never contrasts with siblings or states exclusions (e.g., 'not for per-trip settings'). No when/when-not advice.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, and the description's 'Change' is consistent with those. However, the description adds no behavioral context beyond the action itself, such as whether unspecified fields are preserved, whether at least one field must be supplied, or what the 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?

The description is a single, front-loaded sentence with no filler or redundancy. It efficiently communicates the core purpose.

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 8 parameters, no output schema, and no usage guidance, the description is too thin. It does not explain partial-update semantics, required stay_id, or what happens when multiple fields are updated together, leaving important operational context 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 description coverage is 63%, so the schema carries most parameter meaning. The description summarizes the main editable fields ('city, country, dates or notes') but does not explain checkout_flexible, city_code, or stay_id semantics beyond what the schema already 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 uses a specific verb ('Change') and identifies the resource ('a stop') plus the affected fields (city, country, dates, notes). It is clear enough, though 'stop' does not exactly match the tool name 'stay', and it does not explicitly distinguish this from sibling update_* tools.

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?

No guidance is provided about when to use this tool versus alternatives like update_accommodation, update_activity, or update_flight. There is no mention of prerequisites, partial-update behavior, or when not to use 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?

Annotations already indicate mutation, non-destructive behavior, and idempotence. The description adds a meaningful behavioral detail: setting `is_active` to false archives the visa. It does not say whether omitted fields remain unchanged, but the archive mechanism is still a useful contribution beyond the schema.

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 one direct, front-loaded sentence. It avoids fluff and provides exactly the core action plus the most non-obvious archive behavior.

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 14 parameters and no output schema, the description is under-specified. It clarifies the archive path but omits update semantics for the 13 other fields, whether omitted fields are preserved or reset, and the observable result of archiving.

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 low at 21%. The description adds semantic meaning only for `is_active`; the remaining 13 parameters are left to their names and types, with no discussion of partial updates, defaults, or omitted-field 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 description states a concrete action ('Change') and a resource ('recorded visa'), and adds a distinct sub-operation for archiving via `is_active` set to false. This clearly distinguishes it from create_visa and delete_visa.

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 usage context: the tool is for modifying an existing recorded visa, or archiving it by setting `is_active` to false. It does not explicitly name alternatives, but the 'recorded visa' phrasing makes the appropriate scope obvious.

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