Extralingo

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

Annotations cover safety (readOnly=false, destructive=false, openWorld=true). The description adds meaningful context beyond that: OAuth scope requirement, idempotency behavior, and the constraint that the contact email always comes from the verified account. It doesn't explain what happens on rejection or the shape of the response, but it goes meaningfully beyond what annotations provide.

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 compact sentences, each carrying distinct informational weight, front-loaded with the core purpose. 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?

Given a mutation tool with no output schema and only partial schema coverage, the description should do more. It leaves gaps on error behavior, the duplicate idempotency parameters, the auth_token field, and whether the question triggers notifications or creates a conversation thread. Adequate but with clear holes.

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

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

With schema coverage at only 29% for 7 parameters, the description compensates well: it clarifies that idempotency_key prevents duplicates on retry and that contact email is forced to the verified account email. It omits explanation of the auth_token parameter and does not clarify why the schema contains both idempotencyKey and idempotency_key. Solid but not complete given the low schema coverage.

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+resource: 'Send a question to the school'. The phrase 'without a full trip config' distinguishes it from heavier siblings like request_quote and create_booking. However, it doesn't explicitly contrast with request_discussion, which could also involve contacting a school.

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 context ('without a full trip config') but gives no explicit 'use when X, not when Y' guidance. With such a large sibling set that includes similarly named tools like request_discussion and email_trip, the absence of routing guidance is a real gap.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds that this is a *live* quote (real-time pricing) and reinforces that no reservation is created, but omits auth requirements, failure modes (unavailable dates/courses) and whether the quote is time-limited.

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 core identity and then the exclusivity and ordering. No filler, nothing repeated from the schema or annotations.

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, so the description would ideally hint at what a quote returns (total, currency, validity), and it says nothing. For a scope-less 7-parameter tool with a nested configuration object, the description covers the routing decision but leaves input requirements and the return shape to inference.

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 14% – only the nested 'configuration' object is documented. Six of seven parameters (locale, trip_id, currency, school_id, country_code, discountCode) have no meaning beyond name and type, and zero required parameters means an agent gets no signal about which inputs a quote actually needs. The description's mention of 'a configuration' is the only hint it gives.

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 resource ('live checkout quote for a configuration') and explicitly negates the neighboring write operation ('Not a booking'), so an agent can separate it from create_booking. It never differentiates itself from the similarly-named request_quote sibling, which is the one remaining ambiguity.

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?

'Call this before create_booking' gives an explicit ordering rule relative to a named alternative, and 'Not a booking' states when-not in effect. It does not address request_quote or request_discussion, which sit in the same quoting space and would need disambiguating.

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 well beyond the annotations: it discloses that the booking is unpaid, that the school still confirms, the 5-day down-payment deadline, the required OAuth bookings scope / legacy auth_token, that contact email is forced to the verified account email, and an explicit agent instruction never to claim confirmation or payment. This is exactly the behavioral context annotations (idempotentHint=false, destructiveHint=false) cannot 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?

Front-loaded with the core action and process, and every sentence carries operational weight (deadline, auth, idempotency, agent guardrail). It is dense and somewhat packed into one paragraph, but there is 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?

For a complex, 14-parameter, nested-object mutation with no output schema, the description covers the critical behaviors an agent needs (auth, idempotency, contact-email constraint, agent messaging guardrail). Remaining gaps are the semantics of the many untouched parameters, which 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 description coverage is only 43% across 14 params, and the description clarifies only a few: it confirms idempotencyKey and phone are required and that contact email is always the verified account email (matching the schema's rejection note). It says nothing about trip_id, school_id, currency, configuration, studentDetails, or specialRequests, so it only partially compensates for the coverage gap.

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 ('Makes a real unpaid booking with the school') and immediately clarifies the scope (unpaid, school still confirms). This clearly separates it from siblings like request_quote and email_trip, which do not create a 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?

Explains the surrounding process (school confirms availability, down payment due within 5 days via Extralingo) and states hard requirements (credential, idempotencyKey, phone). It does not explicitly name an alternative tool or state when NOT to use this versus request_quote, so it falls short of a 5.

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=false, idempotentHint=false, and openWorldHint=true, but the description adds non-obvious operational context: OAuth scope requirement, rate limiting, and the alternative flow when unauthenticated. It does not explain actual delivery behavior or whether the email is idempotent on repeat calls, leaving a small gap.

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 short sentences, front-loaded with the action and resource, followed by constraints and the fallback. No filler or repetition.

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 covers auth, rate limits, delivery target, and fallback, which is close to sufficient for a side-effecting email tool. The remaining gap is the unexplained secondary parameters (firstName, lastName, locale) that an agent may need to populate.

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 only 20% across 5 parameters, so the description must compensate and largely does not. It clarifies the recipient semantics (always the verified account email, matching the 'email' param), but firstName, lastName, and locale are undocumented in both schema and description, leaving the agent guessing how they affect the emailed link.

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 names a specific verb (email) and resource (continue_url for /s/{id}) and explicitly contrasts with booking ('This is not a booking'), which distinguishes it from the create_booking sibling. However, 'continue_url' is jargon that assumes the agent already knows what that resource is.

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 states the precondition (OAuth trips scope), the constraint (rate-limited), an explicit exclusion ('This is not a booking'), and the alternative path ('Without auth, share continue_url from save_trip instead'). When-to-use, when-not, and the fallback are all covered.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond that: no indication of what the returned details include, whether locale/currency alter output, or any limits. It contributes nothing the annotations don't already say.

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

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

A single, front-loaded sentence with zero filler. It is appropriately sized for a simple fetch tool, though it is arguably too terse given the undocumented parameters.

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 four parameters (three entirely undocumented), no output schema, and no explanation of what 'details' are returned or how locale/currency/startDate affect the response, the description is materially incomplete. The annotations cover safety but not the functional contract.

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 0% and three of four parameters (locale, currency, startDate) are undocumented in both schema and description. The description only echoes group_id, which is already the required field and its own name is self-explanatory. With no parameter meaning supplied for locale/currency/startDate, it fails to compensate for the coverage gap.

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 ('Details for one accommodation group id') and explicitly links to the 'list_accommodations' sibling that produces the id, so the agent can distinguish the detail fetch from the list fetch. It falls short of a 5 only because it doesn't clarify what 'details' comprises.

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 phrase 'from list_accommodations' implies the workflow — get the group_id from list_accommodations, then call this — which is useful routing context. However, there is no explicit when-to-use/when-not guidance against other siblings such as get_trip or calculate_trip_price.

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, idempotentHint, destructiveHint=false and closed-world, covering the safety profile. The description adds nothing beyond that: no note on caching, error behavior for an unknown course_id, or what the returned detail set contains, so it contributes no behavioral context of its own.

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

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

A single short sentence with no filler and the key dependency (the id comes from list_courses) front-loaded. It is efficient, though its brevity shades into under-specification rather than true crispness.

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

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

With 5 parameters, no output schema, and 0% schema description coverage, the description should explain both the parameters and roughly what details come back. It does neither, so an agent knows the entry point but not how to call it fully or what to expect in return.

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 0% across 5 parameters, so the description carries the full explanatory burden. It only accounts for course_id and leaves school_id (required), locale, currency, and startDate completely unexplained, which is a real gap for a two-required-parameter tool.

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 names the resource (a course) and the identifying key (course id), and points at the sibling that produces that id (list_courses), so the agent can tell it fetches a single course. However, "Details" is never unpacked, so what the tool actually returns remains vague, and no explicit contrast with list_courses is drawn.

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?

"from list_courses" implies the prerequisite workflow: list courses first, then fetch details for one id. That is useful implied guidance, but there is no statement of when to prefer this over list_courses or what happens if the id is unknown.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds return-content context and notes the hero image is a compressed JPEG for chat display, but omits auth needs or rate-limit 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?

Two tight sentences with the content summary front-loaded and the actionable instruction second. No filler, though it is terse enough to leave gaps.

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 detail tool whose annotations carry the safety profile and which has no output schema, the description conveys the returned fields and the key argument source. It still omits the locale parameter's meaning, leaving the definition adequate but not 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?

Schema coverage is 33%, so the description partially compensates: it tells the agent where school_id comes from ('from search') and hints at the hero-image flag. However, the locale enum and its purpose are left entirely to the schema, so it only partly fills the gap.

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 ('School briefing') and enumerates the returned content (profile, cancellation, reviews, image URLs, hero image). It does not explicitly contrast with siblings like get_accommodation_details or get_course_details, so it stops short of full 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?

'Pass school_id from search' implies the tool is a detail-fetch following a search, but gives no explicit when-to-use/when-not or named alternative. Usage is left to inference.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the closed-world hint implies a fixed local enumeration. The description adds that the values are the valid filter set for a specific search tool, which is useful, but it does not say whether the values are static or reflect live inventory, nor how they are returned.

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 compact sentence, front-loaded with what is returned and followed by the consuming tool and examples. Nothing is padded, though it is terse enough that it borders on under-specification rather than tightness.

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, so the description carries the burden of describing the return value; it partially does so by listing value categories, but says nothing about the shape (grouped by facet? flat list?) or the effect of the locale parameter. Adequate for a simple lookup tool, but with visible gaps.

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

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

Schema description coverage is 0% and the single parameter, locale, is not mentioned anywhere in the description. An agent cannot tell from the description that the returned filter labels/values are localized, which is the main semantic question for this parameter. The description does nothing to compensate for the coverage gap.

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 resource (valid filter values) and scopes it to a named sibling, search_language_schools, so an agent can tell it apart from list_courses, search_destinations, etc. It also enumerates the kinds of values returned (languages, cities, course types), which makes the output tangible. It lacks an explicit verb but the intent 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?

By naming search_language_schools as the consumer of these values, it implies the workflow: call this first, then pass the values as filters. There is no explicit when-to-use statement, no statement of whether it must be called before searching, and no exclusions.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: the call returns a continue_url for website handoff with the configuration restored, which tells the agent what to do with the result.

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 tight sentences with no filler; the load action and its key are front-loaded before the return-value note. Appropriately sized for a one-parameter tool.

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

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

For a simple read tool with no output schema, the description covers the action, the key, and the salient return value (continue_url for handoff), while annotations cover the safety profile. Only edge cases such as invalid/unknown trip_id handling are unaddressed.

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 0% and the single required parameter trip_id has no type, format, or example documentation anywhere. The description only echoes the parameter name ("by trip_id") and adds no syntax, source, or format detail to compensate for the schema gap.

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 ("Load a saved trip") plus the retrieval key (trip_id), which clearly separates it from the mutating siblings like save_trip, email_trip, and create_booking. It stops short of naming an alternative explicitly, so it is clear but not fully differentiated.

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?

Usage is only implied: the agent can infer this is the retrieval counterpart to save_trip once a trip_id exists, but there is no explicit when-to-use, when-not-to-use, or alternative tool named. No precondition (e.g. trip must have been saved first) is 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the fact that results are accommodation *groups* whose ids feed save_trip, which is real added context but nothing about filtering, pagination, or result shape.

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 short sentences with no filler, and the core resource statement is front-loaded before the save_trip hint. It is efficient, though the brevity comes partly at the cost of substance.

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 five-parameter, filter-capable list tool with no output schema and no parameter documentation, the description is too thin. It never explains what an accommodation group contains or how startDate/country_code narrow results, leaving the agent to guess at invocation semantics.

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 0% across five parameters, so the description carries the full burden — and it explains none of them. Only school_id is weakly implied by "for a school"; locale, currency, startDate and country_code are completely undocumented, leaving filters like date-range and country behavior opaque.

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 names the resource ("Accommodation groups for a school") but omits an explicit verb — listing is only implied by the tool name. It also does not distinguish this from the sibling get_accommodation_details, so an agent must infer which one returns the collection.

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?

"Use group ids in save_trip" gives a clear downstream workflow hint, which is genuinely useful for chaining calls. However, it offers no when-to-use guidance relative to get_accommodation_details or how it relates to search_language_schools/get_school.

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 annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so safety and mutation behavior are covered. The description adds that the catalogue is 'live' and returns ids, weeks, and prices, but does not cover auth needs, rate limits, pagination, or locale/currency 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 two front-loaded sentences with no wasted text. The key scope and downstream id usage are stated immediately and efficiently.

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, and the description only partially explains return values. With five parameters, 20% schema coverage, and multiple sibling tools, it omits meaningful parameter semantics and alternative-tool routing, leaving important invocation context 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 only 20%, so the description should compensate for undocumented parameters. It mentions output fields (ids, weeks, prices) but does not explain locale, currency, startDate, or country_code filtering, and only indirectly implies school_id through 'for a bookings_live school.'

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: a live course catalogue for a bookings_live school, with returned ids, weeks, and prices. It does not explicitly distinguish itself from sibling tools like get_course_details or list_starting_dates, so it falls short of a 5.

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 only usage guidance is 'Use these ids in save_trip,' which describes a downstream integration rather than when to choose this tool over alternatives. It gives no when-to-use, when-not-to-use, or sibling comparison 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 readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds useful domain context ('typically Mondays') but says nothing about return format, ordering, or whether dates are filtered by course or intake.

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 compact sentence with no filler, and the resource and scope are front-loaded. It is efficient, though perhaps too terse for the parameter burden it carries.

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, no parameter descriptions, and no usage guidance, the description leaves too much unstated for a tool whose result shape and locale behavior an agent must understand. The annotation-covered safety profile is the only well-specified aspect.

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 0% for two parameters. 'For a school' weakly implies school_id, but the locale enum (en/nl/da/sv) is completely unexplained in both schema and description, so an agent gets no guidance on when or why to set it.

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 names the specific resource (allowed course start dates) and scopes it to a single school, which is concrete enough for an agent to distinguish it from list_courses or get_course_details. It lacks any explicit sibling differentiation, but the resource itself 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?

There is no when-to-use guidance, no prerequisites, and no named alternatives. The agent must infer from the phrase 'for a school' that this is called before booking to discover valid start dates, but nothing in the text confirms that or rules out other tools.

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

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

Goes beyond the annotations by disclosing the required OAuth 'requests' scope, the retry/idempotency behavior, and the constraint that contact email must be the verified account email. Annotations only cover safety hints (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so these operational details are genuinely additive. It stops short of 5 because it does not describe side effects such as notifications sent or thread lifecycle.

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 compact sentences, front-loaded with the core action before the operational caveats. Every sentence carries information, though the 'Contact email is always the verified account email' line partly duplicates the schema's contact.description.

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 non-read-only, open-world mutation tool with 9 parameters, no output schema, and 22% schema coverage, the description covers auth and idempotency but says nothing about what the call produces or what happens after the thread is opened. Adequate but with clear gaps.

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

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

Schema description coverage is only 22% across 9 parameters, so the description has to compensate. It usefully clarifies contact email behavior and idempotency_key semantics, but leaves message, trip_id, school_id, currency, auth_token, and configuration unexplained. Partial compensation for a large coverage gap.

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: 'Open a trip discussion with the school.' This is clearer than a tautology and an agent can tell it is a communication/initiation action. It does not explicitly differentiate from close siblings like ask_school_question, request_quote, or email_trip, so it stops short of a 5.

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 never states when to use this tool versus ask_school_question or request_quote, both of which appear to be alternative school-contact flows. The only conditional guidance is about idempotency on retry, not about 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 real behavioral context beyond the annotations: the OAuth 'requests' scope requirement, the retry-safe idempotency key, and the rule that the contact email is always the verified account email. One nuance: idempotentHint=false sits oddly against the idempotency-key guidance, but the key-scoped replay semantics reconcile this rather than contradicting it.

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 short sentences, front-loaded with purpose and usage, then constraints. Every sentence adds something, though the auth-scope and email sentences 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 22% parameter coverage on a 9-param, nested-object tool, the description covers usage and the two highest-risk behaviors but leaves the majority of parameters opaque. Adequate to call correctly in the common case, incomplete for the full surface.

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 only 22% across 9 parameters, so the description must carry more weight than it does. It clarifies the contact/email constraint and idempotency_key semantics, but trip_id, school_id, currency, comments, configuration, and auth_token get no explanation in either place.

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 ('Ask the school for a personal quote'), which is clearly distinct from ask_school_question and create_booking in intent. It stops short of explicitly naming which sibling to use instead, so the differentiation is implied rather than stated.

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 condition: 'Use when bookings_live is false, or the student is not ready to book,' which effectively routes the agent away from the booking flow. It does not name create_booking as the alternative or state when-not to use it beyond that single condition.

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 the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the safety burden is lighter, and the description adds real value beyond them: it discloses the OAuth trips scope requirement, the Bearer token auth, that this is a non-committal draft ('Not a booking'), and the returned identifiers. Only rate limits and update-vs-create side effects are absent.

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, then return values, then the critical constraint ('Not a booking') and auth requirement. Every clause carries information; nothing is padding.

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 5-parameter tool with a nested object, zero required params, and no output schema, the description does useful work by enumerating return fields and stating auth needs. However it leaves the payload shape (configuration, locale, email) undocumented, which is the main thing an agent needs to invoke it 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 only 20% (just trip_id), so the description must compensate for the other four parameters. It explains none of them — email, locale, school_id, and especially the nested `configuration` object remain unexplained in both places, and the schema allows additionalProperties with no guidance.

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 first sentence gives a precise verb+resource ('Create or update a server-side trip draft') and explicitly distinguishes itself from the sibling create_booking with 'Not a booking.' An agent can tell this apart from create_booking, request_quote, and get_trip without opening any 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?

Usage is implied rather than stated: 'so the student can continue on Extralingo.com with selections restored' hints at the draft-then-resume workflow, and 'Not a booking' mildly excludes the create_booking path. There is no explicit when-to-use or when-not-to-use statement, nor a named alternative to call instead.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds scope (cities, countries, school names) but says nothing about result ordering, matching behavior, or how the limit applies.

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 short sentences with zero filler, and the resource scope is front-loaded ahead of the usage instruction. Nothing could be removed without losing 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?

No output schema exists, so the description should ideally indicate what a result contains (place ID, type, display name), which it does not. For a four-parameter search with no documented parameters, the definition is minimal but not misleading.

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 0% across four parameters, and the description mentions none of them — no meaning for query, limit, locale, or language. With zero coverage in both places, the agent must guess that 'locale' constrains output language and how 'language' differs from it.

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 concrete verb+resource ('Search cities, countries and school names'), so the agent knows it returns places, not schools. It gestures at the sibling relationship with 'before searching schools' but never names search_language_schools, so differentiation is implied rather than explicit.

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?

'Use to resolve a place before searching schools' gives a clear triggering context and positions the tool as a prerequisite step in a workflow. It does not state when this tool is unnecessary or what to do if the destination is already known.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by listing the returned fields and warning that prices are 'not a booking quote', but it omits auth requirements, rate limits, and pagination 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?

Three short sentences with the core action front-loaded and the return contract immediately after. The 'not a booking quote' caveat earns its place, though the field list could be tighter.

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 an 8-parameter search tool with no output schema and near-zero schema description coverage, the description should explain the filters and how they combine. It covers the return shape but leaves the parameter surface almost entirely undocumented.

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 only 13% (just the 'language' slug), so the description must compensate but instead adds nothing about the 8 parameters — city, cities, country, query, course_type, locale, limit are all undocumented. The return-field list describes outputs, not 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?

States a specific verb and resource ('Search and rank language schools') and names the returned fields, so the agent knows what kind of tool this is. It does not explicitly differentiate from siblings like get_school or get_school_filters, which keeps it from a 5.

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?

There is no when-to-use guidance, no mention of alternatives such as get_school or get_school_filters, and no prerequisites. The description only states what the tool does, leaving the agent to infer when it applies.

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