mcp-server

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

Annotations already mark `readOnlyHint: true`. The description adds value by listing the types of data returned (description, highlights, gallery, meeting point, redemption type, bookable rates) and confirming it's free. No destructive behavior is implied.

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: the first enumerates output fields; the second provides usage context. No fluff, every sentence serves a 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?

Despite no output schema, the description lists key output fields and notes it's free. It covers the essential information an agent needs, though might lack details on image sizes or pagination (if any).

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?

Input schema has 100% description coverage and is sufficiently clear. The description mentions the activity code provenance but adds no new 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 the tool returns 'Full content for one activity' listing specific fields (description, highlights, gallery, etc.) and specifies the input comes from `pricetik_activity_search`. It differentiates from siblings by mentioning the output feeds into `pricetik_activity_get_booking_url`.

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: after `pricetik_activity_search` and before `pricetik_activity_get_booking_url`. It also notes it's 'Free at every tier.' Lacks explicit when-not-to-use, but 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?

The description adds significant context beyond the readOnlyHint annotation: it verifies a bookable rate exists, confirms the user completes the booking (respecting the certification boundary), mentions free tier, and explains idempotency caching. No contradictions.

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 dense and efficient: four sentences covering purpose, verification, user action, free tier, and idempotency. No extraneous 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?

The description explains the core functionality and constraints well, but lacks explicit details about the return format (e.g., whether the URL is a string or object). Given the absence of an output schema, a brief note on the return type would improve 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?

The input schema already provides 100% coverage with clear descriptions for each parameter. The description adds value by mentioning that the URL is pre-filled with trip parameters and that verification occurs, but does not elaborate on parameter syntax 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 the tool 'return[s] a pricetik.com/tickets/... checkout URL pre-filled with the trip parameters' and distinguishes it from sibling tools like pricetik_hotel_get_booking_url by focusing on activities. It also explicitly notes the user completes the booking, not the agent.

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 get a booking URL for an activity) and provides guidance on idempotency via an Idempotency-Key header. 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?

Beyond the readOnlyHint annotation, the description explains pricing behavior (returns price-from in requested currency and source EUR) and cost/free tier information.

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 with no wasted words, front-loaded with purpose and key details, highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, return value (price info), destination format, and cost, leaving pagination to schema; adequate 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?

Despite 100% schema coverage, the description adds meaning by explaining the destination code format and currency auto-conversion, which is not obvious from parameter names alone.

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 bookable tours, attractions, excursions by destination and dates, distinguishing it from sibling tools like pricetik_activity_details or pricetik_flexible_dates.

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 guidance on using a 3-letter Hotelbeds destination code and notes the tool is free with no API key, giving clear context for usage.

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 that the tool is cache-backed and requires no API key, consistent with the readOnlyHint annotation. It explains the two return types (destination vs. hotel) and how to use the results. While it doesn't detail error handling or rate limits, the behavioral context is adequate for an agent.

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 moderately sized and front-loaded with the primary purpose. It clearly structures the two use cases and concludes with usage guidance. While not extremely concise, every sentence serves a purpose and no information is redundant.

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 does a good job explaining the output shape and how it integrates with sibling tools. It covers key aspects like the two kinds of results and how to use them for hotel booking. The complexity is moderate and the description is complete enough without missing critical details.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds value by explaining how the 'q' parameter is processed into canonical shapes and what the output contains (e.g., providerPropertyId for hotels), which goes beyond the schema's type 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 tool resolves free-text into canonical shapes needed by other PriceTik tools. It provides two specific cases (destination vs. hotel) and distinguishes itself from siblings like pricetik_hotel_search by explaining how it enables hotel name resolution without a UUID round-trip.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs the agent to call this first to avoid asking the user for a code. It explains when to use it (before hotel search/booking details) and distinguishes from pricetik_hotel_search which only accepts city/landmark. This provides clear guidance on when and why to use 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?

Annotations already indicate this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false), so the description adds value by specifying that it is member-only (returns 403 otherwise) and caps at 25 options per session. No contradiction with 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 compact yet complete: it opens with the purpose, then lists surfaces, explains the ref object, gives usage tips, and states constraints. Every sentence contributes unique information without redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description covers all necessary context: when to use, how to populate parameters, constraints, and best practices. It addresses the complexity of a nested ref object and ensures the agent understands the expected workflow. Minor omission: does not describe the return value or success/error handling, but the tool's primary purpose is action-oriented.

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%, providing baseline 3. The description adds meaningful detail by explaining how to construct the ref object differently per surface (propertyId, activityCode, ticketId, rateToken) and which display fields to copy. It also clarifies the purpose of the optional note field, exceeding basic schema documentation.

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 starts with a specific verb ('Propose a candidate') and resource ('to the group'), immediately clarifying the action. It lists the four supported surfaces (hotel, activity, ticket, transfer) and distinguishes from sibling tools like pricetik_hotel_search or pricetik_group_trip_vote, making the tool's unique role 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?

The description provides explicit guidance on when to use this tool: after finding candidates via search tools, and recommends adding 2–4 strong candidates per surface. It also states constraints (member-only, 25-option cap) but does not explicitly exclude scenarios where the tool should not be used, such as for candidates not found via the listed search 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?

Discloses behavioral traits beyond annotations: status change to 'cancelled', error codes (403, 409), no refund because no booking is touched, and state restrictions. Annotations indicate readOnlyHint=false and destructiveHint=false, which description aligns with (non-destructive cancel).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each with distinct purpose: constraint, effect, error conditions, usage guidance. Front-loaded with key action. No redundant text.

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 (state transitions, error cases, authentication), the description covers all essential aspects. No output schema but return values are adequately implied. Sibling tools are mentioned for contrast.

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?

Only one parameter 'sessionId' with schema description 'Group trip session UUID.' Description adds no extra meaning beyond schema. Schema coverage is 100%, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool cancels a group trip session, with specific verb 'cancel' and resource 'group trip session'. It distinguishes from sibling 'pricetik_group_trip_finalize' by explaining when to use each.

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 'organizer-only' usage constraint, mentions authentication requirement, and provides a clear when-to-use directive: 'Use this when the group abandons the trip; to lock a plan instead, use pricetik_group_trip_finalize.'

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?

Discloses authentication requirements, idempotency key usage, and booking behavior (per-traveler via separate tools). Adds context beyond annotations (readOnlyHint=false, destructiveHint=false) without contradiction.

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?

Description is well-structured and front-loaded with key purpose. Each sentence adds value, though slightly verbose; could be tightened slightly without loss.

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 5 parameters, no output schema, and no nested objects, the description is highly complete. It explains return fields, choreography, limitations, and integration with sibling tools.

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% with each parameter described. The description adds minimal additional meaning beyond what's in the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: starting a shared group trip-planning session. It distinguishes from the single-user counterpart pricetik_trip_plan and lists key outputs (session, shareCode, shareUrl).

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 (multi-user planning) and contrasts with the single-user tool. Offers choreography steps (create → search → add options → vote → finalize), guiding the agent on proper sequencing.

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?

Adds context beyond annotations: returns finalized plan with vote tallies, handoffPolicy, display-only prices, irreversible session move to 'finalized', 409 on repeat, and that PriceTik never books.

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?

Single dense paragraph but front-loaded with main action and key constraint. Could be slightly more structured, but every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, description covers return format, prerequisites, constraints, side effects, and price warnings. Fully adequate for a complex finalization 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%, but description adds key nuance: optionIds omission locks all candidates, not auto-picked top-voted; must read get first. This clarifies ambiguous 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 clearly states the verb 'Lock in' and the resource 'group's plan', and distinguishes from sibling tools like add_option, remove_option, vote, cancel, reopen by focusing on finalization.

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 organizer-only requirement, 403 for non-organizers, advises reading pricetik_group_trip_get first, explains behavior when optionIds is omitted vs provided, warns about live rates and irreversibility.

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 provide readOnlyHint=true, and the description adds that it is a 'Pure read', explains the authentication requirement, and mentions the 403 error for non-members. No contradiction; it effectively supplements the annotations with context about authorization and response content.

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 paragraph but efficiently front-loads the core purpose, then lists return fields, usage timing, and prerequisites. Every sentence provides essential information without redundancy. It is concise yet comprehensive.

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?

Despite lacking an output schema, the description fully explains what the tool returns (status, members, options with vote tallies, caller's votes) and under what circumstances to use it (polling after changes). It also covers error handling (403) and dependencies (join first). This is complete for a read-only fetch 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?

The input schema has 100% coverage with descriptions for both parameters. The description goes beyond by clarifying that exactly one of sessionId or shareCode must be provided, which is not explicit in the schema. This adds meaningful usage context, elevating from baseline 3.

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 verb 'Fetch' and the resource 'a group trip session', and details the returned data (status, members, options with vote tallies, caller's votes). It distinguishes itself from sibling tools like pricetik_group_trip_create or pricetik_group_trip_vote by being a read operation.

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: poll after adding options or between conversations, check convergence before finalizing. It also states prerequisites (authenticated API key, join first via pricetik_group_trip_join) and error for non-members (403). This helps the agent decide when to use this tool over 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?

The description adds significant value beyond annotations: it declares idempotency (safe to retry), requires authenticated API key, and states membership ownership. It does not contradict the annotations (readOnlyHint=false, destructiveHint=false) and provides full transparency for a mutation 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?

Four concise sentences with no wasted words. Each sentence adds crucial information: joining action, displayName purpose, post-join capabilities, and authentication/retry instructions. Well front-loaded with the primary 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?

Given no output schema and moderate complexity, the description covers joining, idempotency, display name, post-join actions, and auth. It doesn't detail error handling for invalid share codes, but overall it is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds context for displayName ('so other members see who voted') and implies the purpose of shareCode. This extra meaning helps the agent understand parameter semantics beyond the schema alone.

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 'Join a group trip session by share code' with the verb 'Join' and resource 'group trip session'. It distinguishes from sibling tools like create, get, add_option, vote, and finalize by focusing on the joining action and mentioning idempotency.

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 join a group trip) and what happens after joining (read session, add options, vote). It does not explicitly mention when not to use it or provide alternatives, but the context is clear. The sibling list implicitly differentiates.

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?

Adds upsert behavior, member-only restriction, and post-vote read recommendation. No contradiction with annotations, which are minimal.

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 with no filler. Front-loaded with action and resource. Every sentence adds value.

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?

Covers all aspects: purpose, parameters, access, idempotency (upsert), and next step. No output schema needed for this simple mutation.

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

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

Schema coverage is 100% and includes descriptions for each parameter. The description does not add significant extra meaning 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?

Description clearly states the verb 'Record the caller's vote' and resource 'candidate option'. Distinct from siblings like pricetik_group_trip_get (read) and pricetik_group_trip_add_option (add).

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?

Describes voting behavior (one vote per member, upsert) and access restriction (member-only). Lacks explicit alternative tools but implies after voting read get for tallies.

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 the description confirms a read operation. It adds behavioral details: tier caps on responses (e.g., Open tier caps amenities at 8, POI at 3, description at 240 characters) and that include fields beyond tier are dropped. This provides useful context beyond the annotation, though response format is not detailed.

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 paragraph that front-loads the core purpose. It is concise yet covers essential details without filler. While bullet points could improve scannability, the current structure is efficient and every sentence contributes.

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 4 parameters, no required, no output schema, the description adequately covers parameter usage and return content. It lists the types of information returned (name, description, star rating, etc.) and explains tier caps. However, it does not specify the response format (e.g., JSON), which would be helpful for an agent. Overall, it is fairly complete for a read-only 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 description coverage is 100%, but the description adds meaningful value: it clarifies that exactly one of propertyId or providerPropertyId is required and explains the include array option with tier dependencies (Pro tier unlocks rooms and issues, Scale tier unlocks voucherFacilities and fullDescription). This goes beyond the schema's static 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 action ('Get full property content') and the resource ('PriceTik hotel'), listing specific fields (name, description, star rating, etc.). It distinguishes from sibling tools like pricetik_hotel_deal_score and pricetik_hotel_price_check, which focus on price/deal, not full details.

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 specifies when to use: after a hotel search, to retrieve detailed content. It explains that exactly one of propertyId or providerPropertyId is required. While it does not explicitly list when not to use, the context implies this is the only tool for full details, and tier limitations are noted. No direct alternative is named, but the sibling list shows other purposes.

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?

Beyond the readOnlyHint annotation, the description discloses that URLs are affiliate redirects, details error responses, explains the currentBest fields returned, and notes loyalty program linking. This provides comprehensive behavioral 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 information-dense and well-structured, but slightly lengthy. Every sentence adds value, and it's front-loaded with the core purpose. Could be marginally shorter without losing clarity.

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?

Despite lacking an output schema, the description thoroughly explains response fields (currentBest, loyaltyApplied) and error handling. It also distinguishes this tool from sibling hotel tools like pricetik_hotel_price_check and pricetik_hotel_should_book.

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 coverage, baseline is 3, but the description adds significant value: clarifies the two usage forms, explains how roomCode works in stay-based form, and provides context for optional parameters like childrenAges and holderEmail.

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 generates a one-click signed PriceTik checkout URL for a hotel stay. It distinguishes between two forms (stay-based and rateKey) and provides explicit use cases, 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?

Provides explicit guidance on when to use the stay-based form vs rateKey, when to re-call pricetik_hotel_price_check for expired keys, and instructs not to fetch the URL server-side. Also explains error codes 410 and 422 with actionable steps.

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?

Beyond the readOnlyHint annotation, the description discloses critical behavioral traits: cache-first operation, no provider call on read, and the 'dataAvailable:false' response with 'note' and 'nextStep' for unwarmed rates. This fully informs the agent of expected behavior.

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 front-loaded with the core purpose. Every sentence adds essential information without redundancy or unnecessary detail.

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?

Despite lacking an output schema, the description adequately explains the return value (per-provider pricing, availability status) and special cases. It references a next step tool, providing a complete picture for the agent.

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 already covers all parameters with descriptions (100% coverage). The description adds value by explaining the semantic difference between propertyId and providerPropertyId and the requirement to use exactly one, which is not evident from the schema alone.

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 specific verbs ('Check', 'Returns') and clearly identifies the resource ('current rates across all hotel providers for a specific property and date range'). It distinguishes from siblings by focusing on rate checking rather than searching, comparing, or booking.

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 explains when to use the tool (to get rates) and provides explicit instructions on passing exactly one of two property identifiers. It does not explicitly state when not to use or list alternatives, but the context is clear and sufficient for correct invocation.

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 provide readOnlyHint: true. Description adds valuable context: returns lowest available nightly rate cached, filter flags, destinationResolved behavior, recommendation to use pricetik_hotel_price_check for live rates, and stream option. No contradiction. Could mention pagination or rate limits, but overall strong.

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?

Description is compact yet comprehensive, front-loaded with core purpose, then alternatives, return info, error handling, and additional notes. Every sentence adds value, no redundancy. Well-structured for quick consumption.

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 19 parameters (100% schema coverage) and no output schema, the description covers purpose, usage guidelines, behavioral nuances, error handling (destinationResolved), streaming option, and cross-tool references. It is complete for an agent to invoke correctly.

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

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

Schema coverage 100% so baseline 3. Description adds meaningful semantics beyond schema: destination is geographic not hotel name, segments match on any overlap, excludeResortFees is SQL-level filter. These clarifications help the agent select correct parameter values.

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 it searches hotels by destination, dates, guest count. It explicitly distinguishes itself from pricetik_trip_plan (hotel+activity stitch) and pricetik_hotel_get_booking_url/_details (for specific named hotels). The verb 'Search' and resource 'hotels' are specific, and the scope is well-defined.

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 guidance: for specific named hotels, resolve with pricetik_destinations first; for single-call hotel+activity, use pricetik_trip_plan. Also instructs on how to handle destinationResolved: false (ask user, never retry). Clearly states when to use this tool vs 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?

Annotations declare readOnlyHint=true; description adds details about output format, default filtering, group session behavior, and error conditions. No contradiction, and adds useful behavioral context beyond 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?

Four sentences, front-loaded with main purpose, every sentence adds value. No fluff.

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?

Explains output format, default behavior, authentication, and group session use case. Without output schema, it provides enough for an agent to invoke correctly. Minor gap: no mention of other HTTP status codes beyond 401 and 403 implicitly.

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. Description adds some nuance for tripSessionId (e.g., share link) but largely restates schema descriptions. Adequate but not exceptional.

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 it exports bookings as an RFC-5545 .ics string and structured events array. Distinguishes from siblings by positioning itself as the capstone to pricetik_trip_plan and pricetik_my_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?

Provides clear context: default upcoming-only, includePast for full history, tripSessionId for group plans, and authentication requirements (bearer API key, 401 for open-tier). Does not explicitly list alternative tools but implies usage flow.

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. Description adds that auth is required (OAuth or bearer API key) and specifies ordering ('newest activity first') and returned fields (sessionId, shareCode, etc.), providing good additional 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?

Three sentences, front-loaded with purpose, no wasted words. Concise and well-organized.

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?

Sufficient for a parameterless list tool. Specifies return fields and usage context. Could mention pagination or default limits, but not necessary.

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?

No parameters in schema, so baseline is 4. Description adds value by detailing the return fields (sessionId, shareCode, title, destination, status, role, memberCount), helping agent understand what to expect.

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 specifies verb 'List', resource 'group-trip sessions', and scope 'authenticated user's (as organizer or member)', but does not explicitly distinguish from sibling tools like pricetik_group_trip_get or pricetik_my_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 states when to call: when a returning user references a group trip but sessionId is missing. Also mentions alternative sources (create/join) that provide sessionId.

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?

Discloses trip composition, status filter behavior, authentication failure for Open-tier, and the note field for handoff bookings. No contradiction with annotations (readOnlyHint=true is consistent).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with core purpose, well-structured with clear sections, and every sentence adds value. Slightly verbose in a couple of places but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description fully explains response content (hotel, activities, totals, manage URLs, note field). Covers authentication, scope, and filter behavior completely.

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% with descriptions, so baseline is 3. Description adds value by explaining default values and filter options ('upcoming', 'past', 'all') and limit range (1-25).

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 'List the authenticated user's trips' with specific verb and resource, and clearly distinguishes from sibling tools by focusing on personal bookings, not group trips or hotel searches.

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 defines when to use (for order-book fills and agent-assisted bookings), when not to use (handoff bookings not tracked), and how to handle empty results (relay to different URL). Also specifies authentication requirements.

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 provide readOnlyHint: true, and the description adds valuable behavioral context: 'Coverage is lazy — a name never surfaced via search may miss until first searched.' Also states it's free with no API key, which is beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded: first sentence defines core purpose, second directs to siblings, third adds details. No wasted 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?

No output schema exists, but description explains return structure ('ranked candidates {activityCode, name, destinationCode, fromPrice}'). Covers scope, lazy coverage, pricing, and flow to other tools. Complete for this tool.

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

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

Schema coverage is 100%, so descriptions already exist. The description adds minimal extra meaning for parameters beyond restating the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it resolves a free-text activity name into a Hotelbeds activityCode, which is a specific verb+resource. It distinguishes from siblings like pricetik_activity_details and pricetik_activity_search by outlining the workflow.

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 the agent to pass the resulting activityCode to pricetik_activity_details or pricetik_activity_search. It mentions optional scoping with destinationCode but does not explicitly state when not to use it. Still, 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?

The description fully discloses behavioral traits beyond the readOnlyHint annotation: it explains the cache-only nature ('never calls Hotelbeds'), conditional rate joining, and the 'best-effort match' behavior of the bedType filter. There is no contradiction with 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, well-structured paragraph of three sentences. It front-loads the core purpose, then explains the mechanism and lists filters. Every sentence adds essential information without redundancy or 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?

Given the complexity (12 parameters, no output schema), the description covers the core behavior: cached data, rate joining, filtering options, and identifier requirements. It could mention what the output looks like (e.g., a list of room objects) but the lack of output schema is compensated by the detailed parameter behavior. Overall, it provides sufficient context for an AI 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 100% schema coverage, the baseline is 3. The description adds meaningful context: it explains that rooms/guests are 'carried into each room’s bookingUrl' and that bedType filtering is 'best-effort match'. It also clarifies the mutual exclusivity of propertyId and providerPropertyId. This adds value 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 it returns a filtered, ranked room catalog for a property, reading cached data and optionally joining cheapest rates. It specifies the data source (cached hotel_property_content.rooms) and explicitly differentiates from external calls ('Cache-only — never calls Hotelbeds'). This distinguishes it from sibling tools like pricetk_hotel_details or pricetk_hotel_search that 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?

The description provides clear context on when to use the tool (filtering room types for a property) and includes usage instructions like 'Pass exactly one of propertyId / providerPropertyId'. However, it does not explicitly state when not to use this tool or contrast it with similar sibling tools (e.g., pricetk_hotel_details), which would make the guidance more complete.

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 the description adds behavioral details: results are grouped by surface, relevance-gated, each result carries a drillDownTool, and the events surface returns a separate 'Event tickets' section. No contradictions.

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 relatively long but well-structured with clear sections and front-loaded purpose. Every sentence adds value, though it could be slightly more concise; but given the complexity, it is justified.

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 5 parameters, no output schema, and many sibling tools, the description covers usage guidelines, behavioral nuances, parameter details, and distinguishes from alternatives comprehensively. It leaves no major 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining what each surface value returns, noting category is shopping-only, mentioning tier-limited for limit, and suggesting omitting surface for scope-aware default. This goes beyond 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 explicitly states it is a 'discovery search across PriceTik surfaces (shopping/hotels/events)' and distinguishes it from dedicated tools like pricetik_hotel_search, making the purpose clear and specific.

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 guidance on when to use (exploratory or unknown surface), when not to use (specific intent, multi-surface trips), and lists alternatives (pricetik_hotel_search, pricetik_activity_search, pricetik_trip_plan, pricetik_compare_destinations). Also warns against using surface=all for multi-surface queries.

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, so the agent knows it's safe. The description adds valuable details: returns status, tier, flags, and conditional account block for authenticated vs anonymous callers, without contradiction.

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, front-loaded with purpose and usage, then details. Every sentence contributes meaning, no wasted 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?

Despite no output schema, the description fully explains return values, including conditional behavior. Given the tool's simplicity and existing annotations, it is completely adequate.

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?

There are no parameters (schema coverage 100%), so the description does not need to add parameter info. Baseline 4 is appropriate as it adds no param details but none are needed.

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 checks 'Intel API health and feature flag state', specifying the verb 'Check' and the resource. It distinguishes itself from sibling tools as the only status/health check tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use before making calls to verify the API is available', providing clear usage context. While it doesn't specify when not to use, the purpose makes it 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?

Beyond the readOnly annotation, the description discloses that the data is live-event inventory from an affiliate, that the checkout link should be surfaced unchanged, and that PriceTik never auto-purchases. Also mentions it provides alternative upcoming dates, which is an important behavioral trait.

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 concise sentences, each adding value: the first lists what the tool returns, the second clarifies affiliate nature and usage, the third positions it as a companion to search. No redundant or 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 no output schema, the description adequately outlines the key return fields (venue, date, performers, price, link, other dates). It also explains the affiliate context. Minor gap: does not mention potential error cases or response format details, but overall sufficient for an agent to understand what to expect.

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 reinforces that the id is a UUID or slug from the search tool, but does not add new semantic information 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?

Clearly states it provides full detail for a live-event ticket listing, explicitly listing what is included (venue, date, performers, from-price, checkout link, other upcoming dates). Distinguishes from siblings by specifying it is for live-event tickets and is a companion to pricetik_ticket_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Indicates it should be used after search by referencing id or slug from pricetik_ticket_search, and is described as a companion to that tool. Gives guidance on how to handle the affiliate checkout link. However, does not explicitly exclude other use cases or compare to other detail 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?

Beyond the readOnlyHint annotation, the description explains that results are affiliate links (no auto-purchase), recurring dates collapse into one result with a moreDates count, and output includes specific fields (venue, city, date, from-price, checkout link). This adds significant behavioral context, though it does not cover pagination or no-result scenarios.

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 and immediately distinguishes from siblings. It is well-structured, providing output details, behavioral notes, and alternatives in a logical order. It is informative without being overly verbose, though it could be slightly more concise in the first sentence.

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 has 7 parameters (all documented in schema) and no output schema, the description covers the output format, affiliate nature, recurring date behavior, and alternative tools. It does not explain error conditions or pagination, but overall it is sufficiently complete for an agent to understand and 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?

All 7 parameters are already described in the schema with 100% coverage. The description adds context by summarizing the filtering dimensions (name, type, city, date window) and hinting at the purpose of dateFrom/dateTo (to attend a specific event). This meets the baseline for high schema coverage but does not add substantial new parameter semantics.

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 live-event tickets (concerts, theater, sports, comedy) by name, type, city, and date window. It explicitly distinguishes from two sibling tools, pricetik_activity_search and pricetik_search, by stating what they return instead.

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: it tells the agent to use this tool for event tickets, to use pricetik_activity_search for tours/attractions, pricetik_search for retail products, pricetik_ticket_details for other dates of recurring events, and pricetik_trip_plan to bundle tickets with a hotel. This covers when and when not to use the 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?

Annotations already declare readOnlyHint=true. Description adds critical context: no API key required, URLs are affiliate redirects that must be passed unchanged (never server-side fetch), and rows carry a drillDownTool for subsequent calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with core purpose, then efficiently covers surfaces, parameters, URL handling, and alternative tool. Every sentence adds value; no 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 complexity (5 surfaces, drillDownTool, URL behavior) and lack of output schema, the description thoroughly explains response structure and usage constraints, making it fully actionable.

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 description adds significant meaning: explains each surface's behavior (shopping default 60, hotels biggest drops, etc.), default values, and that category applies only to shopping.

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 returns trending deals ranked 0-100 across verticals, with specific verb 'get best deals' and distinguishes from sibling 'pricetik_search' for specific queries.

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 (general trending deals) and when not (specific queries go to pricetik_search). Describes surface parameter options and optional filters.

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 provide readOnlyHint=true. The description adds value by disclosing that the tool fans out parallel searches, has a stricter rate limit (10/min), supports streaming with ?stream=ndjson, and includes non-fatal error notes for transfers. No contradiction with 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 about 120 words, front-loaded with the main purpose, then details parameters, then usage guidelines. It is dense but efficient, with no redundant sentences. Slight room for more structured formatting.

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 complexity (18 params, no output schema, orchestration behavior), the description covers orchestration, rate limits, streaming, non-fatal errors, and clear parameter roles. It is thorough and leaves little 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?

Schema coverage is 100% (all 18 parameters described), establishing a baseline of 3. The description adds meaning by calling out key params like includeTickets, groupByDay, and includeTransfer, and explaining the budget split (~70/30 hotel/activities), elevating 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 it is a 'single-call orchestrated trip planner' that stitches hotels, activities, and estimated spend, and it names specific sibling tools (pricetik_hotel_search, pricetik_ticket_search) to distinguish itself from those alternatives.

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 says when to use this tool: 'Use this for a single-call hotel + activity (+ ticket) stitch' and when not: 'for hotels only use pricetik_hotel_search, for tickets only use pricetik_ticket_search'. It also mentions rate limit and free tier.

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