FlightSeatmap

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

Annotations already mark readOnly=false, openWorld=true, idempotent=false, and destructive=false. The description adds the concrete side effect of email notification and the authentication requirement, which go beyond the annotations. 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 action, each sentence provides distinct value (purpose, preferences, prerequisites). 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?

The description covers the main usage context: what it does, required prerequisites (existing flight, authentication), and mentions search_flight as a fallback. However, there is no output schema and the description does not state what the tool returns (e.g., alert ID), nor does it mention behavior on duplicate alerts. For a moderate-complexity 6-param tool, this is adequate but leaves these gaps.

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

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

The input schema has 100% description coverage, so baseline is 3. The description summarizes supported preferences (window, aisle, etc.) which aligns with the enum but adds little new detail. It does connect the alert to a specific flight, matching the flight parameters.

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

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

The description states the exact action ('Create a seat alert'), the trigger (when a matching seat becomes available on a specific flight), and the delivery mechanism (email). This clearly distinguishes it from sibling tools like list_seat_alerts or search_flight.

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

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

It explicitly instructs to use search_flight first if the flight is not already in the database, providing a precondition and an alternative tool. It also indicates the tool requires authentication. However, it does not contrast with all sibling alternatives (e.g., find_best_seats) or state when not to use it.

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

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

The description adds the authentication requirement not present in annotations, and hints at the need to locate the ID first. With destructiveHint already signaling deletion, this extra context is valuable. It does not explain idempotency or error behavior, but annotations cover the core safety profile.

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 action, then practical guidance. No superfluous words; 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?

For a single-parameter delete operation with annotations, the description covers the core action, ID acquisition workflow, and auth requirement. It omits response/error details, but given the simplicity and existing annotations, it is sufficiently complete.

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

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

The schema fully documents alert_id with a clear description, and the description merely repeats 'by its ID' without adding new semantic details. With 100% schema coverage, the baseline 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 states 'Delete a seat alert by its ID' with a specific verb and resource, clearly distinguishing it from siblings like create_seat_alert and list_seat_alerts. The scope is 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?

It explicitly instructs to use list_seat_alerts to find the alert ID, providing a clear prerequisite. It also mentions authentication, setting context for when the tool can be invoked. No explicit exclusions, but the workflow 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?

Annotations already declare readOnlyHint=true, and the description's verbs 'Discover' and 'Lists' align with a read-only operation. The description adds context beyond annotations by specifying the categories of MCPs returned (award flights, delays, lounges). It does not disclose whether any remote network calls occur, but given the simple listing nature and existing annotation, this is sufficient.

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

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

The description is two sentences long and both sentences provide essential information: the purpose and the specific content of the list. There is no fluff, repetition, or unnecessary detail. Every word earns its place.

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

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

For a tool with no parameters, no output schema, and a simple discovery task, the description fully covers what the tool does, what it returns, and the categories involved. No additional context is necessary for an agent to decide when to invoke it.

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

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

The tool has zero parameters and the schema covers 100% of properties (none). Per the rules, a baseline of 4 is appropriate when there are no parameters. The description does not need to add parameter semantics because there are none to clarify.

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 a specific verb ('Discover') and resource ('other flight & travel MCP servers'), and explains what it does ('Lists complementary remote MCPs'). It distinguishes itself from sibling tools, which focus on seat maps, alerts, and flight search, by addressing the discovery of additional MCP servers.

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

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

The description implies when to use this tool: when the user wants to extend their client with additional flight-related MCP servers. It mentions covering award flights, airport delays, and lounges, which gives context for typical use cases. However, it does not explicitly state alternatives or when not to use it, but the clear difference from siblings makes usage obvious.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is known. The description adds that the tool returns a ranked list and highlighted seatmap, which is useful behavioral context, and it lists supported preference categories. There is no contradiction with annotations.

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

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

The description is a single, information-dense sentence that front-loads the core purpose and includes output details. No filler or redundancy.

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

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

The tool has a moderate parameter set and no output schema, but the description conveys the key behavior and return artifacts. It falls short of explaining edge cases like no seat matches or interpretation of 'best', but overall it is reasonably complete given the read-only annotation.

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

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

Schema coverage is 100%, with each parameter described (e.g., flight_number format, preference enum). The description's mention of 'window, aisle, extra legroom' essentially reiterates the preference enum without adding new semantics. Therefore the description adds little 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 finds the best available seats based on preferences, and explicitly mentions the output (ranked list and interactive seatmap), which distinguishes it from sibling tools like get_seatmap or get_seat_info. The verb 'find' and resource 'best available seats' are specific and unambiguous.

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

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

The description implies usage when the user wants seat recommendations matching preferences, but it does not explicitly contrast with alternatives like interactive_seat_finder or provide exclusion criteria. No explicit 'when to use vs. not' guidance is given, but the context is clear.

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

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

Annotations already declare read-only, so the description is not required to reiterate safety. It adds that the tool renders an interactive seatmap, which is a behavioral output beyond the annotations. However, it doesn't disclose data freshness or any other behavioral quirks.

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

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

The description is two sentences, front-loaded with the primary purpose and followed by the supplementary seatmap rendering note. Every word contributes 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?

For a read-only info tool without an output schema, the description lists key data categories (characteristics, cabin class, availability, pricing) and the seatmap rendering, giving adequate expectations. However, the overlap with the sibling get_seatmap tool is not addressed, which slightly reduces completeness.

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

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

The input schema already thoroughly documents all three parameters with examples and format specifications, achieving 100% description coverage. The tool description adds no additional parameter-level detail, so it remains at the baseline for well-covered schemas.

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 retrieves detailed information about a specific seat, enumerating characteristics, cabin class, availability, and pricing. This distinguishes it from sibling tools like find_best_seats, and the optional seatmap rendering is presented as an additional capability.

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

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

No explicit guidance is provided on when to use this tool versus alternatives. It does not mention that get_seatmap exists for seatmap-only queries or how this differs from find_best_seats. Usage is only implied by the description of the tool's functionality.

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 valuable behavioral context beyond annotations: it reveals the data source ('from our database') and the caching behavior ('Returns cached data'), plus the output format (text and interactive visual seatmap). It also implicitly communicates that OAuth is not required for this tool since the alternative requires it. 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 three sentences, each serving a distinct purpose: primary function, output details, and caching caveat with alternative. It is front-loaded, concise, and free of 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 read-only tool with no output schema, the description explains the return content (seats, cabin classes, characteristics, availability) and format. It also addresses data freshness and directs to an alternative. Minor omissions like error handling are not critical given the tool's simplicity and supporting 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 both parameters described. The description only mentions 'flight' generically, which adds little beyond the schema. It does not elaborate on the date format or flight number examples, but the schema already covers that. Baseline 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's function: 'Get the seat map for a flight from our database.' It specifies the resource (flight seat map) and the verb (Get), and distinguishes itself from siblings like get_seat_info and interactive_seat_finder by focusing on the whole seatmap with all seats, classes, and 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 provides explicit usage guidance: 'Returns cached data — for fresh/updated data, use search_flight (sign in via OAuth).' This tells the agent when to avoid this tool (when fresh data is needed) and names the alternative, which is excellent for decision-making.

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 read-only and non-destructive behavior. The description adds valuable context by stating 'Free — no auth required' and enumerating the returned fields (ratings, comments, seat number, cabin, helpfulness votes). 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, front-loaded with the core purpose, and no redundant words. Every sentence adds information—purpose, filter, return fields, and auth requirement.

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 is a simple read-only list with two parameters and no output schema, the description covers the return values and auth status adequately. It fully addresses what the agent needs to know for 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 description coverage is 100% for both parameters, so the schema already explains them. The description's mention of 'optionally filtered to a specific seat' adds no new meaning beyond the schema's seat_number description. Baseline score of 3 applies.

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

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

The description states a clear verb 'get' with a specific resource: 'user-submitted reviews for a flight'. It also notes the optional seat filter, which distinguishes it from sibling tools like get_seat_info or find_best_seats that serve different purposes.

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

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

The description clearly implies when to use this tool (when you need user reviews for a flight/seat), but it does not explicitly mention alternatives or exclusions. The context is clear but lacks explicit 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 already declare the tool as read-only and non-destructive. The description adds context beyond these by stating it 'renders an interactive seatmap,' which implies the output may be an interactive UI element. This is useful behavioral information not present in 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 only two sentences. The first sentence delivers the core purpose, and the second gives usage guidance. There is no redundancy or filler, making it highly concise and well-structured.

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

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

For a tool with a simple schema and read-only annotations, the description is largely complete: it explains what the tool does and when to use it. It does not explicitly describe the return format (e.g., HTML, JSON), but 'renders an interactive seatmap' conveys the outcome effectively.

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

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

The input schema provides 100% coverage for both parameters, including examples and format descriptions. The tool description does not add any additional parameter-specific meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: it recommends best seats and renders an interactive seatmap. This distinguishes it from siblings like find_best_seats (which may only recommend) and get_seatmap (which may only render a static map), making the purpose unambiguous.

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

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

The description provides a clear usage context: 'Good default when the user wants help finding a seat but hasn't specified preferences.' This tells the agent when to choose this tool over others, though it does not explicitly name alternatives or state when not to use it.

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

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

Descriptions adds meaningful behavioral context beyond annotations: 'Requires authentication' and specifics about returned data (seats, priority, days until flight, last check time). Annotations already declare readOnlyHint=true and destructiveHint=false, so the added context is valuable without overstepping. 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 three concise sentences, each adding essential information: the operation and scope, the output details, and the authentication requirement. It is front-loaded with the verb and resource, with no redundant phrasing.

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 parameterless, read-only list tool with no output schema, the description is complete. It explains what data is returned (seats, priority, days until flight, last check time), notes authentication, and covers the active/inactive scope. There is no missing critical information for an agent to invoke this 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?

The input schema has zero parameters, so the baseline is 4. The description clarifies that the list is scoped to 'your' seat alerts, which adds context about implicit user-based filtering. No parameter-level documentation is needed since there are none.

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 action verb ('List') and resource ('seat alerts'), and explicitly mentions it includes 'active and inactive' alerts. This distinguishes it from sibling tools like create_seat_alert and delete_seat_alert, making the purpose unambiguous.

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

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

The description implies when to use the tool ('List all your seat alerts') and requires authentication, but does not explicitly state when not to use it or mention alternative tools. Since it's a straightforward list operation, the intended use is largely implied without formal exclusion criteria.

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

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

The description discloses significant behavioral context beyond the annotations: requires OAuth sign-in, consumes a search credit, and offers paid-plan-only access to new flights. It also clarifies the output is an interactive seatmap. These details are valuable and consistent with the annotations (readOnlyHint=false and openWorldHint=true). 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 three sentences, front-loaded with the core purpose, then terse but informative notes on auth, entitlement, cost, and output. Every sentence contributes new information, making it appropriately sized and structured.

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

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

For a two-parameter search tool with no output schema, the description covers the key contextual needs: the result format (interactive seatmap), prerequisites (OAuth and an account), and resource cost (search credit). It is slightly incomplete because it does not position the tool relative to sibling tools, but overall the context is sufficient for an agent to invoke it safely.

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 schema already documents both flight_number and flight_date with meaningful descriptions. The tool description adds no parameter-specific details, so it does not enhance what is already in the schema. Taking the baseline of 3 for full coverage 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 identifies the action ('Search for a flight') and the expected deliverable ('fresh seatmap data' / 'interactive seatmap'). The verb 'search' and inclusion of 'fresh' distinguish it from sibling seatmap tools, though it doesn't explicitly compare to get_seatmap or find_best_seats.

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

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

The description implies the tool is for initiating a flight search and fetching new/live data, hinted by 'Paid plan users can fetch new flights not yet in our database.' However, it does not explicitly state when to use this versus alternatives like get_seatmap or interactive_seat_finder, and provides no exclusion criteria. This is more than no guidance but stops short of clear contextual direction.

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