FlightByte MCP Server

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is already structured. The description still adds substantial behavior beyond that: per-plan quota counting, outbound POSTs to the user URL, refusal on ambiguous legs, pending state for flights up to seven days ahead, and the one-time signing secret. The one caveat is the idempotentHint=false annotation alongside the Idempotency-Key paragraph, which could read as tension even though it is really 'not idempotent by default'.

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 purpose is front-loaded and every sentence carries real information, but the block is dense and sentence-heavy for a 13-parameter tool. A short bulleted split between 'when to use', 'side effects', and 'response' would make it easier to scan without losing 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?

Given 13 parameters, nested objects, no output schema, and only sparse annotations, the description covers the high-risk behaviors an agent must know: quota, outbound requests, leg ambiguity, pending publication, and one-time secret handling. What remains thin is response shape and webhook payload contents, which are partly implied but not documented.

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 the baseline is 3. The description still adds cross-parameter semantics the schema cannot: `origin` is the disambiguator when a flight number operates multiple legs, `Idempotency-Key` changes retry behavior, and the generated `secret` is returned once and should normally be omitted unless the user supplies one. It does not explain the event-filter or delay-threshold parameters, but those are already well described 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?

Opens with a concrete verb+resource ('Watch a flight') and immediately explains the mechanism: FlightByte polls on an adaptive schedule and POSTs a signed webhook for every change. It is clearly distinguishable from the sibling read/management tools (list_subscriptions, update_subscription, delete_subscription) because it describes creating a new watched flight with an endpoint.

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?

States an explicit trigger ('only call this when the user asked to watch or be notified about a specific flight and gave the webhook URL') and warns about quota consumption (Free: 3 per month) and outbound requests. It also gives the concrete fallback for multi-leg flights: the call is refused with a leg list so pass `origin`.

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 flag destructiveHint=true and readOnlyHint=false, but the description adds critical context beyond that: polling and webhook deliveries stop, deletion cannot be reversed, and recorded events/deliveries persist for 30 days. This gives the agent concrete consequences needed before calling a destructive tool.

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 tightly written sentences, front-loaded with the core destructive action, followed by usage guidance and a data-retention note. No sentence is wasted or redundant.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, consequences, alternatives, and data-retention behavior. Combined with the rich annotations, an agent has everything needed to decide and 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 description coverage is 100% and the single `id` parameter is fully documented in the schema, including an example and source. The description adds no additional parameter meaning, so 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?

States a specific verb ('Permanently delete') and resource ('a subscription'), and distinguishes itself from sibling tools like pause_subscription by emphasizing permanence. The agent can immediately tell this is a destructive deletion 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?

Explicitly instructs to 'Confirm with the user first' and 'prefer pause_subscription if they may want it back', naming the alternative and the condition for using it. This directly routes the agent away from deletion when appropriate.

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, idempotent and open-world, so the safety profile is covered. The description adds genuinely new behavioral facts: no API key required, anchors are stripped, and "/docs" returns the full page index. It does not say what happens on an invalid path, but the added auth and normalization details are real value.

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 tight sentences, front-loaded with the core action and output format, followed by input forms and the useful "/docs" entry-point hint. The example paths are long but each illustrates a different accepted prefix.

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 read tool with no output schema, the description covers what it returns (Markdown), where valid inputs come from, and the auth situation. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% with one required string, so the baseline is 3. The description goes beyond the schema by explaining that anchors in URLs are ignored and by listing multiple accepted path shapes (docs, guides, glossary), which clarifies that the parameter is not restricted to /docs paths.

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?

States a specific verb and resource ("Fetch one FlightByte documentation page") plus the return format (Markdown), which is information the name alone does not convey. It also implicitly separates itself from search_docs by framing itself as the page reader rather than the finder.

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?

Tells the agent exactly what inputs are valid — a URL from search_docs with anchors ignored, or a path — and enumerates representative path families including the docs root. It does not explicitly say when to prefer search_docs over this tool, so routing is inferred rather than stated.

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

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

Annotations only say readOnly/openWorld, but the description adds real operational context: `refresh` bypasses cache and 'counts as a normal request' (a cost/rate signal), the `cached` flag, live-data coverage of a few days back to ~2 days ahead, and the full snapshot shape including `status.phase` enum values to branch on. Nothing contradicts the annotations.

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

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

Front-loaded with purpose and example, then escalates to return shape and edge cases; every clause is dense with information. It runs long as a single paragraph and the return-field enumeration is heavy, but with no output schema that content 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 7-parameter, open-world lookup with no output schema, the description covers input disambiguation, the returned snapshot structure (status phase, flags, times, alternates), caching behavior, and the subscription alternative. An agent has everything needed to call it correctly and interpret 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter selection logic the schema cannot express: which selector wins when a flight number operates multiple legs, why `origin` matters, and that `alternates`/`flightId` come from prior responses or error leg lists. It stops short of detailing `destination`/`refresh` interplay, but adds genuine value.

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

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

States a specific verb and resource ('look up the live status of one flight leg') and immediately grounds it with a concrete example (TK1848 → carrier/flightNumber/date). It is clearly distinguishable from siblings like search_flights (discovery) and get_flight_timeline (history) by emphasizing a single leg's live snapshot.

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

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

Explicitly tells the agent when to pass `origin` (user named a departure airport, flight number has multiple legs) and names the alternative for polling: 'create a subscription instead of calling this repeatedly.' The multi-leg default behavior is spelled out so the agent knows the consequence of omitting selectors.

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 openWorldHint, so the safety profile is covered; the description adds real behavioral detail beyond that — newest-first ordering, the wrapper shape, and that events are verbatim airline text. It does not state volume limits or whether history is truncated, which keeps it short of a 5.

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 identifying scope and return shape are front-loaded, and the routing sentence closes it cleanly. The first sentence is dense with opaque field names, but every clause carries information an agent needs.

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?

There is no output schema, and the description compensates by naming the envelope keys and the per-entry fields (`occurredAt`, `title`, `source`, `events`). Combined with full schema coverage and annotations, an agent has everything needed to call and interpret 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?

Schema coverage is 100% and each parameter has a detailed description, so the schema does the heavy lifting. The description only adds the notion of 'one flight leg', which indirectly motivates the origin/destination narrowing already explained in the schema. Baseline 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?

States a specific verb and resource (the airline's own change history for one flight leg) plus ordering (newest first) and the exact response envelope `{flightKey, count, data}`. It is clearly distinguishable from `get_flight`, which it explicitly names as carrying the same data.

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

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

Gives concrete triggering questions ('what changed', 'why is it late') and an explicit exclusion: call this only when the history alone is needed, since `get_flight` already contains it. That is a when-to-use and a when-not-to-use against a named sibling.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the secret field is masked on return, and it enumerates which state fields (status, counts, timestamps) come back — information not available from annotations and valuable 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?

One front-loaded sentence: the action comes first, then the returned fields. The long field list is dense but each item earns its place as return-value documentation, with no 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?

With no output schema, the field enumeration and masking note are exactly what's needed for an agent to use the result. Only the absence of explicit sibling routing keeps it from a 5.

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 `id` parameter already has a clear description with an example and provenance (create_subscription/list_subscriptions). The description adds no parameter-level detail beyond the schema, so the baseline 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?

Opens with a specific verb+resource ("Fetch one subscription") and then enumerates the fields returned, so the agent knows exactly what it gets. It implicitly contrasts with list_subscriptions but never names it, keeping it just short of full sibling differentiation.

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 single-item phrasing implies this is for retrieving one known subscription (the schema's `id` example confirms it), but the description never states when to use this versus search or list_subscriptions. Usage is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds non-obvious behavior on top: results are ordered newest first and records are pruned after 30 days. It does not say whether attempts are paginated beyond the limit cap or how failures are surfaced, but the retention and ordering facts are real added value.

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 tight sentences: what it returns and in what order, when to use it, and a retention caveat. The identifying information and the field list are front-loaded with no 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?

With no output schema, the description compensates by enumerating the return fields (eventId, attempt, status, httpStatus, error, durationMs, at, changeTypes), and it adds ordering and retention. For a two-parameter read tool with readOnlyHint set, nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, with both the subscription id format and the 1–100 limit bound (default 25) fully documented in the schema. The description only reinforces the subscription scoping and adds nothing about the limit parameter, so this is the baseline case where the schema does the work.

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?

States a specific verb and resource ('Recent webhook delivery attempts for a subscription') plus ordering and the exact fields returned, which is far more than a restatement of the name. It never names a sibling like list_events, so the reader must infer the deliveries-vs-events distinction rather than being told it explicitly.

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?

Gives a concrete triggering scenario: 'Use it to debug a receiver that is not getting webhooks or is answering with errors.' That is clear when-to-use guidance, but no alternative tool is named for adjacent tasks (e.g. checking whether an event was even emitted).

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 closed-world scope, so the safety profile is covered. The description usefully adds ordering (newest first) and the contents of the returned payloads (change list plus flight snapshot at the time), but 'recent' is undefined and there is no mention of retention, pagination, or what happens past the limit.

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 what is listed and how it is ordered, followed by the practical use cases. Nothing is wasted and nothing important is buried.

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, read-only listing tool with an annotation-declared safety profile and full schema coverage, the description covers returned content and ordering well. The main missing pieces are the relationship to list_deliveries and any indication of the retention window, which matter for choosing between the two tools.

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

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

Schema coverage is 100%, and the schema documents both the subscription id format and the 1-100 limit with its default. The description adds no parameter meaning beyond that, so the baseline 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 uses a specific verb and resource ('Recent events generated for a subscription') and adds concrete scope: newest first, with the exact webhook payloads that were sent. It does not name or contrast with the closely related sibling list_deliveries, so the distinction between 'events' and 'deliveries' is left implicit.

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

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

It gives two explicit use cases ('see what changed and when' and 'replay a payload into a local receiver'), which is clear usage context. It offers no exclusions or alternative routing, notably against list_deliveries, which an agent could plausibly pick instead for the same investigation.

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 openWorldHint=false, so safety is covered. The description still adds real value: newest-first ordering, the {total, data} response envelope, and that secrets are returned masked via secretHint — none of which the annotations convey.

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 tight sentences: scope and ordering first, paging/masking second, routing guidance last. No filler, and the most decision-relevant facts are 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?

No output schema exists, so the description supplies the return shape and ordering an agent needs to parse results, plus the secretHint masking caveat. Combined with the fully documented schema, nothing material is missing for a read-only list call.

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 every filter (date, status, carrier, flightNumber) and the paging params are already documented in detail. The description only restates that filters are optional and paging uses limit/offset, adding no format or behavior detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the subscriptions owned by this API key'), plus ordering (newest first) and return envelope {total, data}. The closing sentence names the downstream siblings (get, update, pause, resume, delete, log calls), so an agent can separate this from get_subscription or list_deliveries without opening a schema.

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 frames the tool as the id-discovery step before get/update/pause/resume/delete/log calls, and notes that all filters are optional with limit/offset paging. It doesn't state when-not to use it or contrast with search_flights, but the primary use case and alternative path are 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 annotations (non-destructive, idempotent, not read-only), the description adds the two facts that matter: nothing is lost and the pause is reversible via resume_subscription. It also notes the return value. Minor gaps remain, such as whether in-flight deliveries are aborted, but the essential behavioral picture is covered.

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 short sentences, front-loaded with the action and its key constraint, then reversibility, then the return value. No filler and nothing an agent must read twice.

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 mutation with no output schema, the description covers action, side effects, reversibility, and return value. The only unstated detail is edge-case behavior on in-flight deliveries, which is minor.

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, and the schema already documents it at 100% coverage with an example format and its origin (create_subscription / list_subscriptions). The description adds nothing parameter-specific, so the baseline 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?

States a specific verb and resource ('Stop polling and webhook deliveries for a subscription') and immediately scopes the effect ('without deleting it'), which cleanly separates it from delete_subscription and resume_subscription. An agent can pick this tool without opening the schema.

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

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

It gives a clear condition for choosing this tool over the destructive alternative and names resume_subscription as the inverse path. It stops short of an explicit 'use when X, do not use when Y' statement, but the routing is unambiguous.

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 that this is a non-read-only, idempotent, non-destructive mutation, so the description does not need to repeat that safety profile. The description adds useful behavioral context beyond annotations: the suspension cause, the receiver-fix prerequisite, the completed-state exclusion, and the fact that it returns the updated subscription.

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

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

The description is front-loaded with the core action, then covers the suspension edge case and excludes completed subscriptions in a few compact sentences. Every clause adds a distinct operational 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?

For a one-parameter tool with annotations covering safety, the description is complete enough: it states the eligible states, the blocking condition, the prerequisite check, and the return value. No output schema exists, so mentioning that it returns the updated subscription fills the gap.

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

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

Schema description coverage is 100%, and the single id parameter is already richly documented with format examples and where it comes from. The description does not add parameter-specific meaning beyond the schema, so 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 a specific verb and resource (resume a subscription) and distinguishes the eligible states from the ineligible completed state. It also names the sibling tools relevant to the exception path (send_test_event and create_subscription).

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 says when to use it (paused or suspended after 20 failed deliveries) and when not to use it (completed subscriptions require creating a new one). It also supplies the prerequisite to fix the receiver first and points to send_test_event for checking.

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 carry readOnly/idempotent/openWorld, so the bar is lower; the description still adds useful context by disclosing the return shape (title, URL, snippet) and the auth constraint ("Works without an API key"). It leaves out ranking behavior or whether results are always returned when nothing matches, which keeps it from a 5.

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

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

Three sentences, front-loaded with purpose and ending with the follow-up step; nothing is padding. The long parenthetical topic list (authentication through signature verification) is bulky but does real work as keyword priming for an agent forming a query.

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 read tool with no output schema, the definition covers what is searched, what is returned, that no API key is needed, and what to do next. There is no output schema to defer to, and the description compensates by describing the result fields directly.

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% and the schema itself documents both parameters, including the 1-10 limit range, the default of 5, and example query strings. The description adds no parameter-level detail beyond that, so the baseline 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?

States a specific verb and resource ("keyword search over the whole FlightByte documentation") and enumerates the corpora covered: docs, API reference, engineering guides, glossary. It also says what comes back ("best-matching sections with title, URL and a snippet"), so an agent knows exactly what this tool is versus the flight/subscription siblings.

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?

Gives an explicit trigger ("before answering questions about the API... or before writing integration code") and a concrete next step ("then read the full page with get_doc_page"), which is real workflow routing. It does not say when this tool is the wrong choice or name a competing search path, so it stops short of full when/when-not coverage.

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 openWorldHint, so the safety profile is covered. The description adds substantial behavioral context: the returned snapshot structure, branchable status fields, delay/cancellation flags, time representations, cache behavior, and alternate-leg handling.

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

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

The description is long but front-loads the most important information: equivalence to get_flight and usage guidance. The detailed return-field enumeration is justified because there is no output schema, though it is dense and could be tightened slightly.

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 and seven parameters, the description provides the necessary return-value context and leg-selection semantics. Combined with the 100% schema coverage and annotations, 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?

Schema coverage is 100%, so the schema already documents parameter formats and meanings. The description adds value beyond the schema by explaining the origin/destination leg-selection behavior and what the default leg and alternates mean when a flight number operates multiple legs.

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 specific lookup operation and explicitly distinguishes it from get_flight: same data, same parameters, but sent as query parameters to /v1/flights/search. An agent can identify the tool and its relationship to the sibling without opening either schema.

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

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

It gives explicit routing guidance: 'Use either one, not both' relative to get_flight. It also explains how to disambiguate multi-leg flight numbers using origin and destination, and what happens when no selector is provided.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, but the description adds the crucial fact that this is not a dry run — it goes through the real pipeline and is signed with the real secret, so an external receiver is actually hit. It does not mention rate limits, retries, or whether the test event appears in the subscription's delivery history except indirectly via list_deliveries.

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, no filler, with the delivery mechanism and the safety rationale front-loaded before the follow-up action. Every clause carries information an agent would otherwise have to infer.

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 one fully documented parameter and no output schema, the description supplies what is missing: a live side effect on an external receiver, the returned eventId, and the natural next call. Nothing an agent needs to invoke it safely is absent.

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 single `id` parameter already carries an example and points to create_subscription/list_subscriptions. The description mentions webhookUrl and eventId but adds nothing about the `id` argument itself, so the baseline 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?

States a specific verb and resource (send a signed subscription.test webhook), and pins down the mechanism: the real delivery pipeline, the subscription's real webhookUrl, its real secret, returning an eventId. That is far more distinct than the sibling subscription tools, none of which deliver anything.

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?

Gives an explicit when: prove the receiver and its signature check work before the first real change. It also names the follow-up step (call list_deliveries to see how the delivery went), so the agent knows both the trigger and the next call in the sequence.

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?

Goes beyond the annotations (which only declare idempotent/non-destructive/non-readOnly) by disclosing the replace-vs-merge semantics of `headers` and `metadata` and the immutability of the flight binding — behavior an agent cannot infer from the schema or annotations. Minor gaps remain: no mention of delivery-history effects or whether a new webhookUrl is re-verified.

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, zero waste: mutable fields first, patch semantics second, the hard constraint and its workaround last. Every sentence carries information not present elsewhere.

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 6-parameter mutation tool with no output schema, the description covers what can be changed, how to send changes, and the one immutable property. It would be complete at 5 with a note on validation/re-verification of a changed webhookUrl or on whether existing deliveries are affected.

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 already 100%, so baseline is 3; the description adds real value by clarifying that `headers` and `metadata` replace the stored maps rather than merge, and by framing the operation as a partial patch so unchanged fields are left intact. That nuance is not in 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?

States a specific verb (change) and resource (subscription) and enumerates exactly which fields are mutable (webhookUrl, events, delayThresholdMinutes, headers, metadata), which alone distinguishes it from create_subscription and get_subscription. The explicit statement that the flight is immutable further pins down the tool's scope.

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?

"Send only the fields to change" is a precise call pattern, and "create a new subscription for a different flight" names the alternative for the case this tool cannot handle. It stops short of routing the agent to pause_subscription/resume_subscription for temporary silencing, which would have earned a 5.

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