mcp-server

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

Annotations declare readOnlyHint=true, and the description adds that it is 'Cache-only,' providing further behavioral context. It also clarifies that trip duration remains fixed, which is helpful beyond the annotation's safe-read indication.

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 long with no filler. It front-loads the core purpose, adds differentiation, and ends with a usage note ('Cache-only'). Every sentence 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?

Given four well-described parameters, no output schema, and annotations indicating read-only safety, the description provides sufficient context: purpose, usage guidance, behavioral nuance (fixed duration, cache), and differentiation. No gaps remain.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description mentions 'anchored ±N-day shifts' which maps to the shiftDays parameter, but this does not add significant new meaning 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 provides anchored ±N-day shifts of an intended check-in, returning alternatives ranked by savings. It explicitly distinguishes itself from the sibling pricetik_flexible_dates by contrasting fixed vs flexible duration, ensuring the agent uses the correct 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?

The description explicitly contrasts with pricetik_flexible_dates ('this tool keeps the trip duration fixed and just tests wiggle room on the start date'), providing clear guidance on when to use this tool vs. its sibling. It also notes 'Cache-only,' indicating it may not return fresh live data.

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: it calls Hotelbeds /checkrates, returns bookable boolean, expiresAt, currentNet/currentGross, paymentType, freeCancellation flag. No annotation 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?

Two sentences, front-loaded with the core purpose. Every word 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?

Given 2 params and no output schema, description fully covers purpose, usage, return values, and behavioral details. No gaps remain.

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

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

Schema coverage is 100% with good descriptions. The tool description reinforces that rateKey comes from pricetik_hotel_price_check and surface must be 'hotel'. No additional semantic value added 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?

Clear specific verb 'check availability' on a 'rateKey' resource. Distinguishes from pricetik_hotel_price_check by noting it's cheaper because it doesn't re-price.

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: 'right before pricetik_hotel_get_booking_url to confirm a held rate.' Also warns not to pass activity rateKeys, directing to pricetik_activity_get_booking_url.

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 readOnlyHint=true, and the description does not contradict this. It adds valuable behavioral context beyond annotations: 'Stricter rate limit than other tools (10/min) — fans out 2–4 parallel hotel + activity searches.' It also describes the return format (median nightly rate, top-3 hotels/activities, seasonal-premium flag), which is helpful since there is no output 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 moderately long but well-structured and front-loaded with the core purpose. All sentences add value, including the rate limit warning and sibling tool references. A 4 is appropriate due to slight verbosity, though it remains 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?

Given the absence of an output schema, the description thoroughly explains what the tool returns (median rate, top hotels/activities, seasonal-premium flag). It covers required and optional parameters, the rate limit, and prerequisite steps (resolving activity codes). The context is complete for an 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?

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains the relationship between activityCodes and destinations ('parallel to destinations'), what happens when activityCodes is omitted (activity-side comparison skipped), and provides guidance on obtaining activity codes (using pricetik_destinations and the activityDestinationCode field).

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 ('compare') and resource ('destinations'), and distinguishes from sibling tools by specifying what it does not do (live-event tickets) and pointing to alternatives (pricetik_trip_plan, pricetik_ticket_search). It also explains the output (median rate, top hotels/activities, seasonal-premium flag).

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

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

The description explicitly states when to use it: 'Pass 2–4 destinations + same date window + same guest count.' It also provides clear guidance on what not to use it for and suggests alternatives ('Live-event tickets are not compared here... bundle them via pricetik_trip_plan includeTickets=true'). Additionally, it recommends using pricetik_destinations first to resolve activity codes.

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: cache-backed, no API key required, and the specific return fields (hotel-search-friendly text, Hotelbeds code, country, subtitle). 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?

Three sentences, front-loaded with the core purpose, no unnecessary words. Efficient 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 no output schema, the description adequately explains return fields (hotel-search-friendly text, Hotelbeds code, country, subtitle) and mentions caching and auth. For a simple tool, this is sufficient.

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 3. The description adds meaning beyond schema by explaining that the output is a canonical shape needed by other tools, and implies q is free-text and limit controls suggestions. This adds value.

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 resolves free-text into canonical shape including hotel-search-friendly text, Hotelbeds activity destination code, country, and subtitle. It distinguishes itself as a preprocessing step from sibling tools like pricetik_search or pricetik_hotel_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?

The description advises 'Agents call this first so they never have to ask the user for a destination code,' clearly indicating when to use. It also mentions cache-backed and no API key required, but does not explicitly state alternatives or when not to use.

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

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

Annotations include readOnlyHint: true, and the description aligns by noting 'Cache-only — never calls Hotelbeds.' It adds behavioral details: 'Returns a deterministic headline plus a renderable line list' and error handling. 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?

Extremely concise: three sentences cover purpose, behavior, and error handling with no wasted words. Core purpose is front-loaded.

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 covers input, behavior (cache-only, deterministic), output format (headline + line list), and error recovery. 100% schema coverage and readOnlyHint annotation reduce burden.

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% with each parameter described. The description does not add new semantic information beyond what the schema already provides, meeting the baseline expectation.

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 'Decompose a hotel total into base rate, taxes & fees, paid amenities (resort fees, parking), and seasonal premium,' clearly indicating the tool's purpose and output. It distinguishes from siblings by specifying cache-only behavior and error recovery using pricetik_hotel_price_check.

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 and when-not-to-use guidance: 'Cache-only — never calls Hotelbeds' and 'On 404 PriceDataUnavailable, run pricetik_hotel_price_check first to populate the cache.' This tells the agent exactly when to invoke this vs. other 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?

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral details: uses cached hypertable, never calls Hotelbeds, returns up to 10 sorted candidates, and explains the confidence flag (high/low based on observed rates). 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?

A single concise paragraph of about 4 sentences, front-loaded with the action verb. Every sentence adds value, no filler. Efficiently communicates the core 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?

Despite no output schema, the description includes return format (checkIn, checkOut, propertyId triples sorted by cost, confidence flag). Covers complexity: caching, tier limits, parameter requirements, and the top-25 destination limitation. Complete for agent decision-making.

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, baseline 3. The description adds extra meaning: explains mutual exclusivity of propertyId/destination, tier clamping on window length, and the meaning of the confidence flag. Provides context 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 opens with a specific verb+resource: 'Find the cheapest contiguous N-night stay within a flexible date window.' It clearly distinguishes from siblings by noting it uses cached data and never calls Hotelbeds, setting it apart from other price-check 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?

Provides clear when-to-use context: pass either propertyId or destination, explains tier clamping (window range limits by plan), and notes the tool is backed by cached data (no live calls). Missing explicit comparison with siblings like pricetik_alternative_dates, but the context 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 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?

Beyond annotations (readOnlyHint and destructiveHint both false), the description adds critical behavioral context: requires authenticated API key, Idempotency-Key header for safe retries, the creator becomes organizer, and the session is coordinate-only (no booking on behalf). 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 paragraph but packs dense information efficiently. It front-loads the core purpose, then details parameters, return values, choreography, and constraints. Every sentence contributes value without redundancy.

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

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

Given the tool's complexity (5 parameters, no output schema), the description fully covers what the agent needs: purpose, inputs, outputs (with explanation of shareCode and shareUrl), workflow, prerequisites, and limitations. It is complete for a creation 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 baseline is 3. The description adds value by rephrasing parameter meanings with examples (e.g., title: 'Vegas bachelor party', displayName: 'Alex') and clarifying that dates are proposed. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: 'Start a shared GROUP trip-planning session that friends join by share code'. It identifies it as the multi-user counterpart to pricetik_trip_plan, differentiating it from siblings. The verb 'start' and resource 'shared group trip-planning session' are 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?

The description provides explicit when-to-use guidance: it is the multi-user counterpart to pricetik_trip_plan. It outlines a choreography (create → search → add options → vote → finalize) and states that sessions are coordinate-only, with booking per-traveler via booking-url tools. It also mentions authentication and idempotency 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 already mark destructiveHint=true. Description adds critical details: return format (grouped by surface with vote tallies and handoffPolicy), post-finalization steps (hand each traveler their own booking handoff), price caveats (display-only, re-check live rates), and irreversible nature. 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?

Single paragraph of ~150 words, front-loaded with core action and constraint. Every sentence adds value. Could be slightly more structured (e.g., bullet points) but still efficient and clear.

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

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

Covers all necessary aspects for an AI agent: caller restrictions, input behavior, return values (grouped by surface, vote tallies, handoffPolicy), next steps (booking handoff via surface-specific tools), price caveat, error conditions (403, 409, irreversible). No output schema, so description adequately explains return data.

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 basic descriptions. Tool description adds significant usage context: how to use optionIds (pick top-voted subset) and behavior when omitted (locks all candidates). This surpasses 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?

Describes a specific verb ('Lock in the group's plan') and resource ('group trip'), with clear constraints (organizer-only, 403 for others). Distinguishes from siblings like pricetik_group_trip_get (read) and pricetik_group_trip_vote (vote).

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 who can call (organizer-only), what to do first (read pricetik_group_trip_get), how to pick options (top-voted), and when to omit optionIds (lock all candidates). Also warns about irreversibility and 409 on repeat.

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?

The description discloses that the tool is read-only (consistent with readOnlyHint annotation), preserves input order and length, and computes optional haversine distance. It adds behavioral context beyond annotations, such as the error response for invalid length. 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 two sentences, each providing essential information without redundancy. It front-loads the primary purpose and quickly lists output fields and constraints. 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?

Given no output schema, the description adequately describes the response (fields, order preservation). It explains the optional distance feature and error handling. It could be slightly more detailed about 'deal score' or 'top amenities', but overall it is sufficient for an agent to understand what the tool returns.

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% parameter description coverage, so the description does not need to explain each parameter. It adds value by describing the response fields and the behavior of the 'referencePoi' parameter (computes distance). However, the core parameter meanings are already in the schema, so the description adds moderate extra 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: 'side-by-side comparison of 2 to 4 PriceTik hotel properties' for a stay window, and lists the fields returned (name, star rating, nightly rate, deal score, amenities, distance). It distinguishes from sibling tools like pricetik_hotel_search (which finds properties) or pricetik_hotel_details (single property).

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

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

The description explicitly states the valid input range (2 to 4 properties) and the consequence of invalid input (HTTP 400). It implies this tool is for comparison, not for individual property details or searches. However, it does not explicitly mention when not to use it or suggest alternatives, leaving some inference to the agent.

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 description doesn't add safety info. However, it lists underlying factors (rate history, provider spread, demand, seasonal timing) beyond what annotations provide, adding useful behavioral context about how the score is derived.

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 sentence that immediately states the output range (0-100) and key factors. No filler or redundancy; every word 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?

No output schema, but the description specifies the return value (0-100 deal score). It covers the input context (property and dates) and the factors. With good schema and annotations, this is adequate 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%; each parameter has a description (propertyId as UUID, dates as YYYY-MM-DD). The description adds no extra detail per parameter beyond what the schema already provides, 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 returns a 0-100 deal score based on rate history, provider spread, demand, and seasonal timing. It distinguishes from siblings like pricet_hotel_should_book by specifying a numeric score output with explicit factors.

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 use when a deal score is needed but provides no explicit guidance on when to use this tool versus alternatives such as pricet_hotel_should_book or pricet_explain_price. No when-not-to-use or alternative references.

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 mark readOnlyHint=true. Description adds tier caps for Open tier (amenities at 8, POIs at 3, description at 240 characters) and tier-based restrictions on include sections, providing 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?

Concise, front-loaded with purpose, no fluff. Each sentence adds meaningful information. Well-structured for an AI agent.

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

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

No output schema, so description adequately lists returned fields (name, description, star rating, amenities, etc.) and mentions tier caps. 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 coverage is 100% with descriptions for all 4 parameters. Description adds critical context: exactly one of propertyId or providerPropertyId required, and explains the include array options tier requirements in more detail than 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?

Clearly states the tool retrieves 'full property content' for a PriceTik hotel, listing specific fields (name, description, star rating, etc.). Distinguishes from sibling tools like pricetik_hotel_search by specifying lookup via propertyId or providerPropertyId.

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: after pricetik_hotel_search to get details. Describes the optional include array with tier-based unlocks. Does not explicitly mention 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?

Adds substantial behavioral context beyond annotations: explains URL lifecycle (redirects, do not fetch server-side), rateKey refreshing, loyalty program integration, and error handling. Annotations only indicate readOnlyHint, which 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?

The description is well-structured with clear sections for two forms and error handling, but it is quite verbose (multiple paragraphs). Some details, like specific error codes and loyalty behavior, could be condensed.

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 explains the response fields (currentBest block, loyaltyApplied) and covers error conditions and edge cases (expiring rateKeys, loyalty). Fairly complete for a complex tool with 10 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 coverage is 100%, so baseline is 3. Description adds significant extra meaning: explains the distinction between stay-based and rateKey-based forms, role of roomCode, and loyalty behavior. This warrants a score of 4.

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, and distinguishes two forms (stay-based and rateKey-based). This differentiates it from siblings like pricetik_hotel_price_check and pricetik_hotel_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?

Explicit guidance on when to use each form (stay-based preferred for agents, rateKey-based when a rateKey is available), and how to handle specific error responses (410, 422). Does not explicitly exclude other tools but provides clear context.

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

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

Annotations already provide readOnlyHint=true, so the description's additional detail (returns per-provider pricing with availability status) adds minimal behavioral context beyond what is declared. No mention of side effects, auth, or rate limits.

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

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

Two sentences with no extraneous information. The purpose is front-loaded and every word 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?

For a simple read-only tool with 3 parameters and no output schema, the description adequately covers functionality. It could mention error handling or what happens if no data is found, but is otherwise sufficient.

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 for all parameters. The tool description does not add any extra meaning beyond what the schema provides, so a 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 verb 'check current rates' and the resource 'for a specific property and date range', distinguishing it from sibling tools like historical rates or explanations. It explicitly mentions returning per-provider pricing with availability.

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 for checking current rates across providers, but does not explicitly contrast with alternatives (e.g., pricetik_hotel_rate_history) or specify when not to use. However, the context is clear enough for most agents.

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 value beyond the readOnlyHint annotation by detailing behavioral traits such as tier-limited days parameter, deterministic OLS trend slope, null bestNightlyRate for days with no observations, and the full-history nature of the allTime block. However, it does not mention rate limits or authentication requirements.

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

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

The description is reasonably concise, front-loading the main purpose in the first sentence. Subsequent sentences provide necessary details like allTime block, tier limits, and null behavior. Every sentence adds value, though the structure could be slightly more 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?

The description covers all key aspects: output structure (daily series, trend slope, headline, allTime block), parameter tier limits, and null handling. Without an output schema, this provides sufficient context for an agent to use correctly. Minor missing details like error handling or rate limiting.

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?

Even though schema description coverage is 100%, the description adds specific information beyond the schema, such as the exact tier limits for the days parameter (Open: up to 7, Pro: up to 90, Scale and above: up to 180) and that allTime is always full-history. This enhances understanding beyond the schema's 'tier-clamped' mention.

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 'retrieve' and the resource 'daily best-nightly-rate-across-providers series' for a specific hotel and stay window. It also distinguishes itself from sibling tools like pricetikk_hotel_price_check and pricetikk_hotel_deal_score by mentioning deterministic OLS trend slope and allTime block.

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

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

The description implies usage for historical rate data and judging deals against years of rates, but it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or when-not-to-use guidance. Given the many sibling tools, more explicit guidance would be helpful.

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 readOnlyHint=true. The description additionally discloses that the tool is 'cache-only,' themes are derived from cached amenity content (not live data), and Hotelbeds does not expose per-category breakdowns. It also explains that theme cues are surfaced as -1/0/+1 with reasons, providing full transparency about data limitations and output format.

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 extremely concise at two sentences. The first sentence lists what the tool provides, and the second explains the cache-only nature and theme encoding. Every sentence adds value without redundancy.

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

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

Given the simplicity of the tool (one input, no output schema), the description adequately describes the output components (score, count, star rating, segments, theme cues with reasons). It could be more explicit about the output structure, but the description is sufficient for confident agent 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?

Schema coverage is 100% with a single parameter (propertyId) described as 'PriceTik hotel UUID.' The description adds no further semantics about the parameter beyond what the schema provides, so it meets the baseline expectation without enrichment.

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 that the tool returns a 'synthesised review summary' including score, count, star rating, segments, and theme cues for cleanliness, location, staff, value, and comfort. This distinguishes it from siblings like hotel_details or hotel_deal_score, which serve different purposes.

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

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

The description implies usage for obtaining review summaries and mentions that themes can be 'quoted confidently,' but it does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or direct comparisons to siblings 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 indicate readOnlyHint: true, and the description adds behavioral details such as caching ('cached on PriceTik'), NDJSON streaming for direct REST callers, and the structure of output (header frame, property frames, closing summary). It does not contradict annotations and provides useful operational context beyond the structured fields.

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, front-loading the main purpose. Each sentence adds value, and technical details like NDJSON are placed at the end. Minor redundancy with sibling tool mention could be tightened, 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, yet the description explains the high-level return: properties with lowest nightly rate, cached, and mentions providerPropertyId for further use. The NDJSON output structure is described. It does not detail every property field, but for a search tool this is acceptable given the complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning for several parameters: e.g., nearPoiLat/Lng for pinning search center, segments for lifestyle filtering, excludeResortFees with SQL-level filter explanation. This goes beyond the schema's basic 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 uses specific verbs and resources: 'Search hotels by destination, dates, and guest count.' It clearly distinguishes the tool from its sibling pricetik_trip_plan by stating 'Use this for hotels only; for a single-call hotel + activity stitch, use pricetik_trip_plan 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 clear when-to-use guidance: for hotel searches. It explicitly tells when not to use (pricetik_trip_plan) and suggests using the returned providerPropertyId with pricetik_hotel_price_check for live rates. However, it does not directly address all sibling tools like pricetik_hotel_compare, though the scope is still well-defined.

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?

Description adds context beyond readOnlyHint annotation, specifying return fields (confidence, reasoning, rate, demand zone, seasonal flag) and emphasizing no LLM invocation. 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?

Two sentences, front-loaded with main purpose, second sentence lists return fields. No filler; 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?

Given no output schema, description adequately covers return values and logic. Could detail the recommendation meaning, but 'book_now/wait/watch' is intuitive. Overall sufficient for agent invocation.

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 covers all 7 parameters (100% coverage), so description adds little beyond stating that urgency and maxNightlyRate are optional and that the tool checks budget. 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?

Description explicitly states it returns a 'book_now, wait, or watch recommendation', combining multiple signals. Verb 'Get' and resource 'recommendation' are clear, and it distinguishes from siblings like pricetick_hotel_deal_score and pricetick_hotel_price_check.

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?

Description lists factors used but lacks explicit when-to-use or when-not-to-use guidance compared to alternatives. Implies use for deterministic recommendation but no differentiation from similar 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?

Description adds substantial context beyond annotations: details what checks are performed (row count, median age, stalest row, etc.), the return format (classification + per-block detail), and that it is free. Annotations already provide readOnlyHint=true; no contradiction. Slight deduction for not mentioning any rate limits or authentication, but the detail is 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 three sentences well-structured: first sentence defines scope and components, second explains return value, third gives usage guidance. Every sentence contributes, no fluff, front-loaded with key information.

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

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

For a zero-parameter read-only tool with no output schema, the description is comprehensive: it explains inputs (none), outputs (classification and detail), exact data checked, and usage context. It fully informs an agent when and why to use this tool among the many hotel-related siblings.

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

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

Input schema has zero parameters, so baseline is 4 per guidelines. Description adds no parameter info but does not need to; it provides rich context about the output and usage, compensating for the lack of parameters.

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

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

Description clearly identifies the tool as returning cache-side health for the PriceTik hotel surface, listing specific components (content cache freshness, rate-history coverage, etc.) and output format. It effectively distinguishes from sibling tools by specifying 'hotel surface', which differentiates it from general status tools like pricetick_status.

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 ('before high-stakes booking flows to verify the cache is fresh') and what it does not provide ('surfaces no live partner quota numbers'), giving clear context for appropriate invocation 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?

Discloses all relevant behavioral traits: requires free API key, owned by account, delivery methods (account vs webhook), free tier cap of 3 alerts, default expiration set to checkIn minus 48 hours, idempotency key support, and management via sibling tools. No annotations contradict these details.

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

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

The description is moderately long but well-structured, starting with purpose and then providing details. Every sentence contributes useful information. Could be slightly more concise, but overall effective.

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 (9 parameters, rate alert behavior, multiple delivery options), the description provides enough context for correct usage, including limitations, defaults, and retry safety. No output schema exists, but the description compensates well.

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 extra context beyond the schema: clarifies webhookUrl usage for developers vs end users, explains the default for expiresAt, and mentions the Idempotency-Key header. This adds significant value, raising from baseline 3 to 4.

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 subscribes to a rate alert for a specific property and stay window, using a specific verb 'Subscribe'. It distinguishes itself from sibling tools by mentioning management tools like pricetik_alert_list, pricetik_alert_delete, etc.

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 (to get notified when rate drops below target) and when-not-to-use (when webhookUrl is omitted for end users, recommend account delivery). Also explains tier limitations and references sibling tools for management, giving clear 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 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 declare readOnlyHint=true, consistent with the description's 'List' verb. The description adds authentication context (requires API key, Open-tier returns 401), which is useful 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?

Two sentences, front-loaded with purpose, no redundant information. 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?

Despite no output schema, the description details the trip contents (hotel, activities, spend, countdown, manage URLs). However, it omits pagination or limit behavior, which is somewhat covered by the schema.

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

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

Schema coverage is 100%, and the description mentions the status filter with defaults but does not add significant 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?

The description clearly states the tool lists authenticated user's trips grouped by destination with overlapping dates, and details what each trip includes. It is distinct from sibling tools like search or hotel 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?

Authentication requirements (bearer API key) are mentioned, but there is no explicit guidance on when to use this tool over alternatives like pricetrik_search or pricetrik_trip_plan.

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=true, and the description reinforces this by stating 'Cache-only — never calls Hotelbeds.' It also discloses behavioral details like joining cheapest cached rate per room when a stay window is provided and best-effort bedType matching. This adds value beyond annotations, though ranking logic is not explained.

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 with a clear structure: first sentence states the tool's purpose, second explains the join and cache behavior, then lists filters concisely. No wasted words; every part 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?

The description covers input well with filters and behavior, but without an output schema, it does not describe the structure of returned room objects. Given the complexity (9 parameters, ranked output), some output description would improve completeness, but it is adequate for a filtered-list 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%, so baseline is 3. The description adds context: it explains that checkIn/checkOut enable rate join, that bedType is a best-effort match against name/description, and lists filters. This clarifies the purpose of parameters beyond their schema descriptions.

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

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

The description clearly states it is a 'Filtered, ranked room catalog for a property.' It specifies the data source (cached hotel_property_content.rooms), the join logic (cheapest cached rate per room with stay window), and the available filters. This distinguishes it from sibling tools like pricetik_hotel_details which focus on hotel-level info.

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: to get filtered room types for a property. It mentions cache-only behavior and the need to pass a stay window for rate join. However, it does not explicitly state when not to use or mention alternative tools for related tasks, but the context from sibling names helps.

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 significant behavioral context: surface-specific behaviors (shopping returns retail, hotels returns destination+UUIDs, events returns bookable activities plus event tickets section), grouping by surface for 'all', drillDownTool field, and scope-aware default. 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?

Description is quite long but well-structured with clear sections and guidance. Every sentence earns its place; could be slightly more concise but the detail is justified for a complex tool with many sibling alternatives.

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 explains return structure (grouped by surface, drillDownTool, ticket rows with fields). Could be more explicit about overall response format, but given the complexity and lack of output schema, it provides sufficient context for tool selection and invocation.

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 3. Description adds meaning beyond schema: explains surface enum values in detail, notes limit is tier-limited, category only applies to shopping, and default surface is scope-aware. Adds value but schema already describes parameters well.

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's a discovery search across PriceTik surfaces, with specific verb 'Search' and resource 'PriceTik surfaces'. It distinguishes from dedicated sibling tools like pricetik_hotel_search and pricetik_activity_search, and different behaviors per surface.

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

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

Explicit guidance on when to use this tool vs. alternatives: for specific intent prefer dedicated tools, for exploratory or unknown surface use this; for multi-surface trip avoid surface=all and use parallel dedicated calls or trip_plan/compare_destinations. Also mentions alternatives like pricetik_trending_deals.

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 it returns status, tier, and feature flags. Annotations already note readOnlyHint=true, and the description adds behavioral context 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 concise sentences front-load the action and purpose. No redundant or filler content.

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 zero-parameter health check tool with no output schema, the description fully explains purpose, usage timing, and return values. Complete for its 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?

No parameters exist, so the description adds no parameter meaning beyond the input schema. With 100% schema coverage, 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 'Check Intel API health and feature flag state', using a specific verb and resource. It distinguishes from siblings like pricetick_hotel_status which is hotel-specific, making 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 explicitly advises 'Use before making calls to verify the API is available', providing clear when-to-use guidance. While it doesn't list when not to use or alternatives, the context implies it's a preliminary step.

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 readOnly behavior (supported by annotations), no API key needed, affiliate redirect URLs must be passed unchanged, rows carry drillDownTool, and default minDealScore of 60 for shopping. No contradictions 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?

Description is slightly long but every sentence adds necessary context. Front-loaded with core purpose and well-structured. Could be slightly more concise, but appropriate given complexity.

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

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

Despite no output schema, description thoroughly explains return data: surfaces return specific content (hotels => 7-day drops, tickets => reasons breakdown), rows carry drillDownTool, and 'all' returns labeled sections. Covers edge cases and usage notes.

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?

Schemas cover 100% of parameters but description adds significant value: explains surface enums in detail (e.g., hotels = biggest 7-day drops, tickets = below median with reasons), clarifies category only for shopping, and minDealScore default behavior. Also mentions drillDownTool in rows.

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

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

Clearly states the tool discovers today's best deals ranked 0-100 across all verticals. Distinguishes from siblings by explicitly naming pricetik_search for specific queries and pricetik_deals_for_you for user-interest-ranked deals.

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

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

Explicitly tells when to use alternatives: pricetik_search for specific queries, pricetik_deals_for_you for user interests. Also explains each surface value and its use case (e.g., 'tickets' for live-event tickets below median with reasons breakdown).

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, but the description adds substantial context: parallel fan-out, 10/min rate limit, free tier, affiliate ticket inventory with checkout links, ticket prices excluded from estimated total, transfer availability notes, streaming support. 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?

Description is lengthy but each sentence adds value, front-loaded with main purpose. Could benefit from more structured paragraphs, but overall clear and efficient for the complexity.

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

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

With 18 parameters, nested objects, and no output schema, the description covers main behaviors, return structure (eventTickets[], transfer rateToken), edge cases (transferUnavailable), and alternatives. Missing some output format details but sufficient for agent invocation.

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 has 100% description coverage for all 18 parameters, so baseline is 3. The description adds meaning beyond schema by explaining interplay of parameters (e.g., includeTickets semantics, transfer rateToken usage, groupByDay itinerary details).

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 defines the tool as a single-call orchestrated trip planner that combines hotels, activities, and estimated spend. It distinguishes from sibling tools like pricetik_hotel_search and pricetik_ticket_search, specifying 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 when to use this tool vs alternatives: 'Use this for a single-call hotel + activity (+ event ticket) stitch; for hotels only, use pricetik_hotel_search; for tickets only, use pricetik_ticket_search.' Also provides context for optional features like includeTickets and includeTransfer.

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