mcp-server

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 include readOnlyHint=true, which is consistent. The description adds behavioral context beyond annotations: cache-backed, no API key required, and explains the two output types (kind:'destination' and kind:'hotel') and the fields returned. No 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?

The description is well-structured and front-loaded with the main purpose. It is somewhat long but each sentence adds value, explaining use cases and cross-referencing sibling tools. Minor redundancy 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?

Given the tool has two modes and is a resolver for multiple downstream tools, the description is comprehensive. It explains output shapes, how to use results (e.g., pass providerPropertyId to watch/booking tools), and ties into other tools. No output schema exists, so the description adequately covers return values.

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 both parameters. The description adds context about what 'q' is used for (free-text destination) and mentions limit constraints, but largely repeats schema info. Since schema already covers parameters, 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: 'Resolve free-text into the canonical shape other PriceTik tools need.' It distinguishes two specific cases (destination and hotel) and explicitly differentiates from sibling pricetik_hotel_search, which only accepts a city/landmark. The verb 'resolve' and resource 'free-text' 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 tells when to use this tool: 'Agents call this first so they never have to ask the user for a code.' It explains that pricetik_hotel_search only accepts city/landmark, so for hotel names this tool is required. It also provides an alternative use: feed airportCode into pricetik_transfer_search. Additionally, it states no API key required, giving 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?

Beyond the readOnlyHint annotation, the description discloses that the tool is backed by a cached hypertable, returns up to 10 candidates with confidence flags (high/low), and includes tier-based window limits. 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 concise (~100 words) and well-structured: main purpose in first sentence, followed by data source, parameter selection, output format, confidence detail, and tier limits. Every sentence adds value without 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 no output schema, the description adequately explains the return format and confidence flags. It covers tier clamping and parameter options. However, it omits error cases or behavior when no candidates found, but overall is sufficient for effective use.

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 parameter descriptions. The description adds value by explaining the grouping of propertyId/destination and the output format (candidate triples with confidence). This goes beyond mere schema repetition.

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

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

The description clearly states the tool's purpose: 'Find the cheapest contiguous N-night stay within a flexible date window.' It specifies the data source (cached hypertable) and distinguishes from siblings like pricetik_hotel_price_check by emphasizing flexibility and caching.

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 context on when to use (flexible date range, hotel or destination) and mentions it never calls Hotelbeds, implying it's fast but cached. However, it does not explicitly contrast with siblings like pricetik_hotel_price_check or pricetik_search for fixed dates.

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?

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 indicate destructiveHint=true, but the description adds substantial behavioral context: authorization restrictions (organizer-only), irreversibility (409 on repeat), output structure (finalized plan grouped by surface with vote tallies and handoffPolicy), and the fact that PriceTik never books on behalf of users. 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 moderately long (4 sentences) but each sentence serves a distinct purpose: authorization, parameter explanation, output description, warnings. It is well-structured and front-loaded with the core action. Slightly verbose due to multiple warnings, but all are necessary.

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

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

Given the absence of an output schema, the description covers return values (finalized plan with tallies and handoffPolicy), error cases (403, 409), workflow dependency (must read group trip first), and related tools (booking URLs). It is complete for a complex mutation tool with no output schema.

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

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

Schema description coverage is 100%, yet the description adds crucial semantic detail: optionIds can be omitted to lock all candidates (but does not auto-pick top-voted; winners must be explicitly passed from pricetik_group_trip_get), and the maxItems constraint is reinforced. 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 clearly states 'Lock in the group's plan' and distinguishes from sibling tools like cancel, reopen, etc. It specifies the verb 'finalize' on the resource 'group trip', and differentiates between passing a subset of optionIds or omitting to lock all candidates.

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 it's organizer-only (403 for others), instructs to read pricetik_group_trip_get first and pick top-voted options, and advises to use separate booking tools for each traveler. It also warns that finalizing is irreversible and that prices are display-only, guiding when to use this tool versus re-checking live rates.

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?

Discloses that the option's votes are removed with it, and that the operation is only allowed for organizers and while planning. Provides clear error scenarios (403, 409, 404). Annotations indicate destructiveHint=false but description clearly indicates a destructive removal, which is a 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-load the main action and conditions, with zero wasted words. Every sentence adds necessary information.

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

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

Given no output schema, the description adequately covers return status codes (403, 409, 404) and side effects (votes removed). No further context needed for a removal 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% and both parameters are well-documented as UUIDs. The description adds no extra semantic detail beyond what the schema 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 removes a candidate option from a group trip session, specifying that it is organizer-only and only works while the session is planning. It distinguishes from the sibling tool pricetik_group_trip_add_option.

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 (prune weak candidates before voting), who can use (organizer-only), conditions (only while planning), error codes (403, 409, 404), and mentions alternative tool pricetik_group_trip_add_option for proposing.

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 behavioral traits beyond annotations: it clears the finalized selection, allows group deliberation, and specifies error conditions (403 for non-organizer, 409 for non-finalized). Annotations already indicate non-readOnly/non-destructive, but description adds actionable detail.

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

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

The description is two sentences, front-loads the core purpose, and includes all critical details without extraneous words. 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 the simple nature of the tool (one parameter, no output schema), the description is complete: it covers prerequisites, authorization, side effects, error conditions, and relationship to sibling 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% with a single parameter described as 'Group trip session UUID.' The description does not add further meaning to the parameter beyond contextualizing it as the session to reopen. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool reopens a finalized group trip session back to planning, specifies it is organizer-only, and explicitly labels it as the undo for pricetik_group_trip_finalize. This distinguishes it from sibling tools like finalize and cancel.

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 usage context: only for reopening a finalized session, organizer only, and specifies error codes for invalid states (403, 409). It mentions being the explicit undo for finalize, offering guidance on when to use, though it does not explicitly list 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?

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 already declare readOnlyHint=true, so the description is not required to repeat safety info. The description adds valuable behavioral context: the score is computed from multiple factors, and the mutual exclusivity of propertyId and providerPropertyId is clarified. 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?

The description is a single sentence that efficiently communicates the purpose, output range, input constraints, and key factors. Every word serves a purpose, and it is front-loaded with the main 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?

While the description covers the core functionality and parameter constraints, it fails to describe the return format or structure. Given the absence of an output schema, the description should specify whether the result is a simple number or an object. This gap reduces completeness for an agent deciding how to use the result.

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

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

The description adds meaning beyond the 100% schema coverage by explaining that propertyId is the internal UUID and providerPropertyId is the handle from search/lookup, and explicitly requiring exactly one of them. This resolves ambiguity not present in the schema's optional designation.

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

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

The description clearly states that the tool returns a 0-100 deal score based on rate history, provider spread, demand, and seasonal timing. It effectively distinguishes itself from sibling tools like pricetik_hotel_price_check by emphasizing a composite score rather than a simple price comparison.

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 context on when to use (to obtain a deal score) and how to pass parameters (exactly one of propertyId or providerPropertyId). However, it does not explicitly state when not to use this tool or mention alternative sibling tools like pricetik_hotel_should_book for purchase decisions.

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 (which is consistent), the description details key behaviors: automatic rateKey refresh near expiry, URL redirect semantics (do not fetch server-side), content of the currentBest block (no margin fields), and loyalty auto-stamping. This provides rich context for safe agent usage.

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 every section contributes essential information (two forms, error handling, response details). The structure flows logically from purpose to specifics to edge cases. Minor redundancy could be trimmed, but overall it is 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?

Given the tool's complexity (10 parameters, multiple forms, error codes, loyalty integration) and lack of an output schema, the description covers all necessary aspects: input forms, error handling, response structure, and usage nuances. An agent has enough information to invoke 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 10 parameters are described in the schema (100% coverage), and the description adds substantial extra value: explaining the role of roomCode (ignored with rateKey), the conditional requirement for childrenAges, and the distinction between providerPropertyId and PriceTik UUID. This helps an agent correctly structure inputs.

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: 'Generate a one-click signed PriceTik checkout URL for a hotel stay.' It specifies two distinct forms (stay-based and rateKey-based) and contrasts with sibling tools like pricetik_hotel_price_check and pricetik_hotel_search, making the scope 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 recommends the stay-based form as 'the preferred form for agents' and explains when to use each form. It also provides error-handling guidance (e.g., on 410 and 422 responses). However, it could further clarify when not to use this tool versus alternative tools (e.g., for price comparison before generating a 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?

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 declare readOnlyHint=true. The description adds behavioral details: null return for unobserved days, tier-dependent lookback, and allTime full-history, beyond what annotations provide. No 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?

The description is a single paragraph but packs significant detail efficiently. It is front-loaded with the main purpose; could benefit from slight restructuring for scanability, but overall concise and informative.

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

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

With no output schema, the description comprehensively explains all returned components (bestNightlyRate, OLS trend, summary headline, allTime block) and edge cases (null days, tier limits). Complete 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 coverage is 100% with descriptions for all parameters. The description adds meaning by explaining tier limits for 'days', mutual exclusivity of propertyId/providerPropertyId, and currency FX purpose, enhancing agent understanding.

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

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

The description clearly states it retrieves daily best-nightly-rate-across-providers series with trend and all-time stats, distinguishing it from sibling tools like pricetik_hotel_price_check and pricetik_hotel_deal_score by focusing on historical rate analysis.

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 analysis but does not explicitly state when to use this tool versus alternatives like pricetik_hotel_price_check. It provides tier-limit constraints but lacks direct guidance on tool selection.

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

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

Adds significant behavioral context beyond the readOnlyHint annotation: data is cached, themes are inferred from cached amenity content rather than per-category reviews, and cues are -1/0/+1 with reasons. 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?

Two sentences: first defines output, second explains data source and limitations. Front-loaded, concise, and no extraneous 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 read-only tool with two optional parameters and no output schema, the description explains the output components, data source, and derived nature of themes. Missing explicit return format but adequate for agent understanding.

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

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

Schema coverage is 100% with descriptions already explaining the mutual exclusivity requirement. The tool description does not add new information about the parameters beyond what is in 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?

Description clearly states it provides a synthesized review summary for a property, including score, count, star rating, segments, and theme cues. Distinct from sibling tools which handle search, details, booking, 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?

Description mentions cache-only data and inferred themes, indicating when the tool's output is derived. However, it does not explicitly compare to alternatives like pricetik_hotel_details that may also contain review information, leaving the agent without clear when-not guidance.

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

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

Annotations declare readOnlyHint=true, consistent with read-only search. Description adds behavioral context: caches the lowest nightly rate, mentions NDJSON streaming for REST callers, and clarifies that excludeResortFees is a SQL-level filter. 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 front-loaded with core purpose and constraints, then covers alternatives and advanced features. Every sentence adds value, though slightly long. Structured logically: purpose -> usage guidance -> special cases -> streaming option -> sibling contrast.

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 and no output schema, description covers what is returned (properties with lowest nightly rate cached) and how to use result IDs. Mentions streaming for REST but that's extra. Sufficient for an agent to understand the tool's behavior and integration with other 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 has 100% description coverage, but description adds value beyond schema: clarifies destination param is geographic (not hotel name), explains nearPoiLat/Lng/RadiusKm override centroid, segments matching logic, and excludeResortFees detail. Not all params need extra context, but description enriches key ones.

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 'Search hotels by DESTINATION...' and explicitly distinguishes from sibling tools: for specific named hotels use pricetik_destinations, for hotel+activity stitch use pricetik_trip_plan. The verb 'search' and resource 'hotels' are precise.

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 and when-not-to-use: 'To act on a SPECIFIC named hotel... resolve it first with pricetik_destinations' and 'Use this for hotels only; for a single-call hotel + activity stitch, use pricetik_trip_plan instead.' Also explains how to use nearPoi parameters and providerPropertyId for further actions.

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 readOnlyHint=true indicate no destructive behavior. The description adds context beyond annotations by listing input signals (rate trend, demand pressure, etc.) and explicitly states 'No LLM is invoked', which is useful for understanding behavior. However, 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, front-loaded with purpose, and every sentence adds value. No wasted words: first sentence states what it does and what signals combine; second sentence lists return fields and a notable behavior (no LLM).

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 return values (confidence, reasoning, best rate, historical context, demand zone, seasonal flag). It also mentions determinism and no LLM invocation, addressing completeness for a recommendation tool with multiple inputs.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add new meaning beyond what the schema provides, such as clarifying the propertyId/providerPropertyId mutual exclusivity (already in 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 the tool provides a deterministic recommendation (book_now, wait, watch) for a PriceTik hotel property and stay window, combining multiple signals. It distinguishes from sibling tools by focusing on recommendation rather than search, price check, or rate history.

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 what the tool does but does not explicitly state when to use it versus alternatives like pricet_hotel_price_check or pricet_hotel_watch_rate. It implies usage for decision-making but lacks explicit when-to-use or when-not-to-use 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?

The description fully discloses behavioral traits beyond annotations: it is not read-only (creates a watcher) and not destructive (just a subscription). It details defaults (expiresAt to checkIn minus 48 hours), idempotency key behavior, action handling, and delivery methods. No contradictions with annotations (readOnlyHint=false, destructiveHint=false).

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 comprehensive and well-structured, starting with the main purpose and then detailing usage nuance. While it is lengthy, every sentence adds value. A slight reduction in verbosity could improve conciseness, but it remains clear and 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?

Given the complexity (13 parameters, no output schema), the description is thorough: it explains triggers, actions, defaults, limitations (free tier), expiry, idempotency, and management via sibling tools. Return behavior (delivery via email/dashboard or webhook) is covered, making it sufficiently complete for an agent to use confidently.

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: it explains the difference between propertyId and providerPropertyId, when to use each trigger (targetNightlyRate, dropPercent, dealScoreAbove), implications of webhookUrl omission, and action parameter behavior. This goes well beyond the 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 the tool's purpose: subscribing to a rate alert for a hotel property and stay window, triggered when the nightly rate hits or drops below a target. It uses specific verbs ('subscribe') and distinguishes itself from sibling tools by focusing on alert creation rather than price checking or 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?

The description provides explicit when-to-use guidance: differentiates between end users (omit webhookUrl) and developer integrations (supply webhookUrl), explains free tier limits (3 active alerts), default expiry, idempotency for retries, and lists sibling tools for management. It also clarifies trigger requirements ('Provide at least one trigger').

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 already declare readOnlyHint=true, and the description adds valuable detail: returns ranked candidates with a 'best' handle only when one clearly wins, cache-backed, no API key required. It also explains the side effect of calling pricetik_hotel_details on the handle (warms indexing for watch). 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 a single paragraph but dense with information, every sentence contributes. Front-loaded with main purpose, then usage, then output details, then integration tips. 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?

Despite no output schema, the description explains the return structure (array with candidates, 'best' handle). It covers all 3 parameters, integration with 3 sibling tools, and caching behavior. Complete for its complexity and annotations.

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

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

Schema coverage is 100% with descriptions. The description adds context: 'optionally bias with near' and explains the meaning of limit. It links output to other tools. While schema covers basics, the description enhances understanding of how parameters affect results.

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

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

The description explicitly states the core purpose: 'Turn a hotel NAME into a chainable handle'. It specifies the input (hotel name) and output (providerPropertyId/propertyId). It distinguishes itself from sibling pricetik_hotel_search by clarifying that this tool resolves names while the sibling only accepts city/landmark. The verb 'resolve' and resource 'property' are 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?

Clear guidance on when to use (to get a specific hotel handle) and when not (pricetik_hotel_search is for cities/landmarks). It names alternative tools (pricetik_hotel_details, etc.) that use the output. It also advises confirming with user if no clear winner. This is comprehensive.

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. The description adds that it never calls Hotelbeds (cache-only) and joins cheapest cached rate per room when stay window is passed, providing valuable 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?

The description is three sentences with no wasted words: states purpose, explains key behavior (cache, rate join), and lists filters. It is concise and 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 10 optional parameters and no output schema, the description provides a solid overview of functionality and constraints. It lacks details on return format or sorting, but overall covers essential context.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds context about the join and ranking but does not significantly augment parameter meaning beyond what is in 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 'Filtered, ranked room catalog for a property,' specifies it reads cached data and joins cheapest rates, and lists filters. It distinguishes from sibling hotel search tools by focusing on room types of a specific 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 explains when to use the tool (when needing room types with filters and optional rate join) and notes it is cache-only, implying not for real-time data. It does not explicitly name alternatives 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?

Beyond the readOnlyHint annotation, the description details surface-specific behaviors (grouped by surface for 'all', scope-aware default, events surface returns activities plus event tickets) and mentions result fields (drillDownTool, watchTool). 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?

The description is front-loaded with purpose but is lengthy. However, every sentence adds value, and the structure is logical. Slightly long but not wasteful; very informative.

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 complexity and no output schema, the description covers all necessary aspects: behavior, parameter details, usage guidelines, result characteristics, and references to related tools. Fully sufficient 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 is 100%, but the description adds significant value: explains scope-aware default for surface, tier-limitation for limit, and context for each parameter (e.g., category only for shopping). Provides 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 the tool is a discovery search across PriceTik surfaces and explicitly differentiates from dedicated tools like pricet_hotel_search and pricet_activity_search, providing strong purpose clarity.

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?

Extensive guidance on when to use this tool vs alternatives: for specific intents prefer dedicated tools, for multi-surface trips use parallel calls or pricetik_trip_plan, and for 'best deals' use pricetik_trending_deals. Includes explicit when-not-to-use instructions.

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

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

Annotations only declare readOnlyHint=true, but the description adds significant behavioral details: it returns status, tier, flags, and conditionally an account block with specific fields depending on authentication. This goes well beyond the annotation, fully disclosing the tool's 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: first sentence states purpose, second gives usage guidance, third and fourth detail output. Every sentence adds value with 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?

For a tool with no input parameters and no output schema, the description is fully complete: it explains the return values, conditional behavior based on authentication, and appropriate usage context. 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?

The input schema has 0 parameters, so baseline is 4. The description does not add parameter info (none exist) but compensates by explaining the output structure and conditional behavior, which indirectly clarifies why no parameters 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 the tool's purpose: 'Check Intel API health and feature flag state.' The verb 'check' and the resource 'API health and feature flag state' are specific and unambiguous. It distinguishes itself from sibling tools which focus on hotels, trips, 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?

The description explicitly says 'Use before making calls to verify the API is available,' providing clear usage context. It also advises pre-checking before using pricetik_set_target_price, linking to a specific dependent tool. It lacks explicit 'when not to use' guidance but still provides strong directional advice.

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

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

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.