Extralingo

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

Annotations already declare non-read-only, open-world, non-destructive behavior, so the safety profile is covered. The description adds a genuinely useful non-schema fact — the required OAuth "requests" scope — plus the availability of an idempotency key, though it says nothing about what happens downstream (whether the school is emailed, expected response latency, rate limits).

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

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

Three short clauses, front-loaded with the action and scoping constraint, then auth, then the idempotency note. Nothing is padded, though the trailing idempotency_key mention largely duplicates the schema and slightly dilutes the front-loading.

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?

An output schema exists, so return values need not be described, and the schema fully documents the complex nested configuration. But for a tool with 8 parameters, nested objects, and relationships to save_trip/trip_id, the description does not explain how trip_id or configuration interact with the "without a full trip configuration" framing, leaving a meaningful 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%, so the schema already documents all 8 parameters including the nested configuration object. The description only restates that idempotency_key is optional, adding no semantics beyond what the schema provides — the correct baseline of 3.

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

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

States a specific verb and resource ("Send a question to the school") and adds a scoping qualifier ("without a full trip configuration") that separates it from booking/quote flows. It does not name a sibling explicitly, so differentiation is inferred 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?

The phrase "without a full trip configuration" implies this is the lightweight path when no trip exists, which hints at when to prefer it over create_booking or request_quote. However, no alternative is named and no when-not conditions are given, so the agent must infer the routing against 16 siblings.

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 usefully reinforces that this is not a booking, but adds no detail on rate limits, auth, or the fact that a quote may be persisted when trip_id is supplied (which sits in the schema, not the description).

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, front-loaded sentences with zero filler; the disambiguation and the ordering constraint are stated immediately and nothing is 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?

With a rich nested input schema and an existing output schema, the description need not explain returns or fields. It supplies the workflow context an agent needs; only a note on quote persistence/rate behavior would improve it further.

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 parameter including the nested configuration is already documented in the schema. The description adds no parameter-level meaning beyond the word 'configuration,' so the baseline 3 is appropriate.

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

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

The description states a specific operation (a live checkout quote for a configuration) and explicitly distinguishes itself from create_booking with 'Not a booking.' It clarifies scope and non-mutation, though the word 'quote' alone leaves slight ambiguity about whether it computes prices or retrieves a previously stored one.

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 concrete sequencing guidance: call before create_booking and before quoting a final price to the student. That is strong context, but it does not mention an alternative for non-live/exploratory pricing or reference siblings like request_quote.

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: discloses OAuth bookings scope/Bearer token requirement, the school-confirmation email and 5-day down-payment flow, an explicit instruction never to tell the user they are confirmed or paid, and 24-hour idempotency replay semantics. This is exactly the operational context annotations 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-loads the core action in the first clause, then layers workflow, warning, auth, and idempotency in tight sentences with no filler. Every sentence carries distinct, actionable 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?

With an output schema present and 100% schema coverage, the description's job is to supply the non-structural context, and it does: auth requirements, downstream timeline, user-facing messaging constraint, and idempotency behavior. Nothing an agent needs 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%, so the schema already documents every parameter thoroughly, including the nested configuration object. The description only restates idempotency behavior that the schema's idempotency_key description already covers, adding no new parameter-level meaning.

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 ('Submit an unpaid booking for a bookings_live school') and anchors it to a known workflow ('same path as the website Book now flow'). This is clearly distinguishable from sibling tools like request_quote or save_trip.

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 clear context for when this tool applies (live school booking, school still must confirm availability, trip_id can link a saved draft), but never names an alternative or a when-not condition, e.g. request_quote vs create_booking or what to do if the school is not bookings_live.

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

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

Annotations already mark this as a non-read-only, non-idempotent, open-world action, and the description adds real context: OAuth trips scope requirement, rate limiting, and that the link always goes to the verified account inbox regardless of the email field. It does not describe failure modes when the scope is missing, but the disclosure goes meaningfully beyond 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?

Four short, front-loaded sentences with no filler; the core action leads and constraints follow. The telegraphic '/s/{id}' and 'OAuth trips scope' phrasing is dense but still parseable, costing only a little readability.

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?

An output schema exists, so return values need no explanation here. For a 5-parameter, non-idempotent side-effecting tool, the description covers auth, rate limits, recipient constraint, and the non-booking caveat well; only error/retry behavior is left 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 100%, so the baseline is 3; the schema already documents email, locale, lastName, firstName and trip_id sources. The description adds only indirect meaning (the payload is continue_url, the inbox is the verified account) without clarifying parameter behavior beyond what the schema states.

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 ('Email continue_url (/s/{id}) to the verified account inbox') with the exact recipient and payload. An agent can distinguish this from siblings like save_trip or create_booking without opening any schema, and the '/s/{id}' detail pins the artifact being sent.

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

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

Provides an explicit exclusion and a decision rule: 'Not a booking; you can share continue_url without emailing.' This tells the agent when not to call it and implies a no-email alternative workflow. It stops short of naming the specific sibling tool to use instead of emailing.

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 the safety profile is covered. The description adds a genuinely non-obvious behavioral caveat: week prices are indicative only and a real checkout total requires calculate_trip_price. It does not cover auth/permission needs or response volume, so it stops 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?

Two tight sentences, front-loaded with what is returned, then the sequencing and the price caveat. Every clause carries information; no filler or restatement of the name.

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?

An output schema exists, so return-structure explanation is unnecessary, and the description still supplies the one thing outside structured fields an agent needs: trust level of prices and where to get the authoritative total. Combined with 100% schema coverage, nothing material 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%, so 3 is the baseline. The description goes slightly beyond it by tying specific parameters to output semantics ('week prices for startDate and currency'), clarifying that startDate and currency key the price figures returned. No extra syntax or format detail (e.g., valid date range) is added.

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 (get) and resource (details of one accommodation group) and enumerates the returned facets: type, room_types, board options, distance, amenities, age/min-stay rules, week prices. It explicitly positions itself as 'One group from list_accommodations (group_id)', distinguishing it from the sibling that lists many.

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 explicit sequencing: 'Use after list_accommodations, before save_trip or calculate_trip_price, or to answer questions about one option.' It names both the prerequisite sibling and the downstream siblings, plus the disambiguating condition (questions about a single option).

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 structurally. The description adds a small amount of content context (that pricing rows and supplements come back), but says nothing about auth needs, rate limits, or behavior when the id is invalid.

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 compact sentence with the identifying scope ('one course id') front-loaded and the returned content types in a trailing parenthetical. Nothing is wasted, though the fragment style makes it slightly clipped rather than fully self-explanatory.

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 an output schema covering return values and annotations covering the safety profile, the description only needs to fix scope and provenance, which it does. It is marginally thin on whether optional parameters like startDate or currency change the result, but nothing essential 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% and an output schema exists, so locale, currency, course_id, school_id and startDate are already fully documented, including the Craft CMS vs CRM id distinction. The description adds no syntax, default, or format detail beyond 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?

Names the resource (course details) and ties it to the sibling that supplies the id ('one course id from list_courses'), which separates it from list_courses and the other detail tools. It also enumerates the payload (pricing rows, supplements, metadata), though the verb 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?

The phrase 'from list_courses' implies the prerequisite step of enumerating courses first, and 'one course id' signals single-item scope. There is no explicit when-not guidance or comparison to alternatives such as get_trip or calculate_trip_price, so usage is only inferred.

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, non-destructive, closed-world behavior, so the safety burden is covered. The description adds context the annotations lack: the optional chat-UI hero image behavior and the instructional booking flag, which matter for how the result is consumed.

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 zero filler; the returned payload is front-loaded and the prerequisite follows. Nothing is redundant or 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?

An output schema exists, so return shape need not be spelled out, and the description still enumerates the payload for quick routing. Only minor absence is any note on permissions or failure modes, which is acceptable given the complete annotations and output schema.

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

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

Schema description coverage is 100%, so all three parameters (locale, school_id, include_hero_image) are fully documented in the schema, including the Craft CMS id sourcing and hero-image stripping. The description repeats the school_id requirement rather than adding syntax or format detail beyond it, 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 the resource (school briefing) and enumerates exactly what it returns: profile, cancellation policy, reviews, image URLs, bookings_live flag, and hero image. Distinguishes it from sibling getters like get_course_details and get_accommodation_details by naming school-specific content.

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

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

Explicitly states the prerequisite sourcing: 'Requires school_id from search_language_schools,' which tells the agent it must call the search tool first. No explicit when-not or alternative-tool routing is given, but the ordering guidance is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful context that this is a filter-value lookup for a specific search tool, but does not add behavioral details such as auth needs or caching/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?

One tightly written sentence with no filler, front-loading the tool's purpose and the sibling it supports.

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

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

Given the simple one-parameter schema, rich annotations, and an existing output schema, the description is nearly complete. It could be slightly stronger by explicitly saying to call this tool before search_language_schools, but an agent has enough information to select 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 100%, and the single locale parameter is fully documented in the schema. The description does not add any parameter-level meaning beyond the schema, so the 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: provides valid filter values for search_language_schools, and enumerates the facets (languages, countries, cities, course types). This distinguishes it from search_language_schools, which performs the actual search.

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

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

Clearly ties the tool to search_language_schools as the source of filter values, giving strong implied context for when to call it. However, it does not state exclusions or explicitly instruct an agent to call this before search_language_schools.

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 establish the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuine context beyond them: the return payload is a continue_url intended for website handoff with configuration restored, telling the agent what the call actually yields and why.

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, zero waste, with the primary action and its key output front-loaded. Every clause 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?

An output schema exists so return-value documentation isn't strictly required, yet the description still flags the continue_url handoff, which is the practically important part. Nothing critical is missing for a one-param, read-only, idempotent retrieval tool.

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

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

Schema coverage is 100% and the description's only parameter statement ("by trip_id") merely restates the schema's own "trip_id returned by save_trip." With a single well-documented parameter, baseline 3 applies; no added syntax or format detail.

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 ("Load") and resource ("saved trip") and ties it to the producing tool, save_trip, so an agent can distinguish it from the save_trip sibling. It stops short of differentiating itself from the other get_* siblings, but the pairing with save_trip makes the purpose unambiguous.

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

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

"by trip_id from save_trip" implies the round-trip workflow (save first, then load), which is useful implied usage guidance. However there is no explicit when-to-use/when-not statement and no named alternative for a similar retrieval need.

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 the scoping fact that results are per-school and that the ids feed save_trip, but says nothing about pagination, filtering, or how many groups to expect. With annotations carrying the safety burden, this is an adequate 3.

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 padding, and the resource is stated before the downstream integration tip. It is appropriately sized, though the first sentence is a fragment rather than a complete statement of what the call returns.

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 an output schema present and 100% schema coverage, the description does not need to describe return values or parameter formats. What is missing is the when-to-use boundary against sibling tools like get_accommodation_details and how this fits with get_school, leaving the definition adequate but not complete for a 17-tool catalog.

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 every parameter (school_id, locale, currency, startDate, country_code) is documented in the schema, including cross-tool references like search_language_schools and list_starting_dates. The description adds no parameter-level information whatsoever, 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?

The description names the resource ('Accommodation groups for a school'), which is enough to distinguish it from get_accommodation_details (single accommodation details), but it never states the action verb. It's a noun phrase where 'list' is only implied by the tool name, so the purpose is clear but not crisply 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?

The second sentence is a downstream usage hint: 'Use group ids in save_trip configuration (accommodationGroupId).' That tells the agent why/when to call this (to obtain ids for save_trip), which is genuinely useful. However, it gives no exclusion or comparison against get_accommodation_details or get_school, so the routing guidance is only partial.

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 a closed world, so the safety profile is covered. The description adds that the catalogue is 'live' and lists the returned fields, but says nothing about pagination, filtering behavior, or auth needs.

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, zero filler, with the resource and its returned fields front-loaded before the chaining instruction. Every sentence earns its place.

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

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

With an output schema present the description need not explain return values, and the schema fully documents all five parameters. The only missing piece is how this list relates to get_course_details, which the description leaves implicit.

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 parameter is documented in the schema (locale, currency, school_id source, startDate, country_code). The description adds no syntax or format meaning beyond what the schema already provides, 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 ('Live course catalogue for a bookings_live school') and even names the fields returned (course ids, weeks, prices). It does not explicitly distinguish itself from the sibling get_course_details, so it falls just 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?

Gives explicit downstream context: the returned course ids are meant to be fed into save_trip configuration, which tells an agent when this tool belongs in a workflow. It names no exclusion or alternative (e.g. get_course_details for a single course), so it is clear context without routing 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=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered without the description. The description adds only the 'typically Mondays' domain caveat; no auth, rate-limit, or pagination details are given.

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 resource definition and the 'typically Mondays' caveat front-loaded before the downstream consumption hint. 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 simple read-only lookup with a fully documented 2-param schema and an output schema, the description covers purpose, value semantics, and cross-tool usage adequately. Only minor gaps (e.g., ordering of returned dates) remain.

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

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

Schema description coverage is 100%, and the schema already explains locale enum values and that school_id is the Craft CMS entry id (not the CRM UUID). The description adds no parameter meaning 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?

States a specific verb+resource ('Allowed course start dates ... for a school') and scopes it to a single school, which cleanly distinguishes it from the broader sibling list_courses. The cross-reference to where these values are consumed makes the tool's role 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?

Explicitly tells the agent what to do with the result: 'Use startDate values in list_courses and configuration.startDate,' which is real chaining guidance. It does not, however, name an alternative tool or state when *not* to call this one.

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, it discloses meaningful behavior: the school receives the config, Extralingo emails the verified account and coordinates replies, and the call returns kind/newBookingId/redirectUrl and is 'not a booking'. That 'not a booking' clarification is exactly the kind of side-effect context annotations don't 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?

It is compact but written as a string of colon-delimited fragments that are hard to parse and not front-loaded around the primary action. Every clause carries some information, but the telegraphic structure reduces readability.

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, nested-object tool with an output schema, the description covers the modes, side effects, key return fields, OAuth scope, and idempotency. The main gap is the unresolved overlap with the ask_school_question/request_quote siblings.

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

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

Schema coverage is 100%, so the schema already documents every parameter; baseline is 3. The description adds only the 'trip_id or school_id+configuration' either/or relationship, which the schema does not express, but it omits the message/contact/currency semantics and does not compensate meaningfully.

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 concrete action (send a discussion/message to a school) and enumerates the input shapes for its modes (trip_id, or school_id+configuration, plus message). However, it overlaps awkwardly with sibling tools ask_school_question and request_quote by describing those modes inside this tool rather than cleanly distinguishing request_discussion from them.

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 partial conditions ('ask_school_question: question without a trip', 'request_quote: personal quote (comments) when not booking'), which imply when each mode applies. But it never states when to call request_discussion versus the standalone ask_school_question/request_quote siblings, so routing 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 declare the mutation/safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), and the description usefully adds the OAuth 'requests' scope requirement, which annotations do not convey. Idempotency-key behavior is deferred to the schema, so it adds only moderate extra behavioral context.

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

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

Two sentences, no waste, and the critical call condition is front-loaded before the incidental scope/idempotency notes. Nothing needs trimming.

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 an output schema present and full schema coverage on 8 parameters, the description only needs to carry the when-to-call and auth context, which it does. It is slightly thin on how the quote is delivered or whether the request is free/side-effecting, but not enough to mislead.

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 every parameter, including the nested configuration object, is documented richly in the schema. The description adds nothing beyond noting idempotency_key is optional, 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+resource ('Ask the school for a personal quote') and immediately bounds the scenario ('when bookings_live is false or the student is not ready to book'), which distinguishes it from the booking/creating siblings. An agent can tell this apart from create_booking 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?

Gives a clear trigger condition (bookings_live false, student not ready to book) rather than terse context. It stops short of naming the closest siblings it should be chosen over — request_discussion, ask_school_question, create_booking — so the boundary with those 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 the non-readOnly, non-idempotent, non-destructive, closed-world profile, and the description adds real context on top: the required OAuth trips scope (Bearer token) and that anonymous drafts can use an email instead. It does not say whether an update replaces or merges existing selections, which is the main behavioral ambiguity left for an upsert.

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, then the return contract, then the auth requirement. Nothing is redundant or padded.

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 a full output schema, complete annotations, and 100% schema coverage, the description only needs to supply the auth scope, the non-booking boundary, and the restore-on-Extralingo purpose — all of which it does. Nothing an agent needs to call this 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% and the parameters are richly documented (school_id provenance, courseId from list_courses, startDate format), so the schema does the heavy lifting. The description adds no parameter-level detail of its own, which is the expected baseline of 3 at full 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 and resource ('Create or update a server-side trip draft') and immediately scopes it against the obvious sibling with 'Not a booking', so an agent can distinguish it from create_booking and get_trip 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?

Gives the create-vs-update rule via trip_id and an explicit exclusion ('Not a booking'), which routes the agent away from booking tools. It does not, however, name a specific sibling to use instead or state prerequisites beyond the OAuth scope, so it stops short of a full when/when-not/alternative statement.

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 the safety profile is covered. The description adds the useful hint that output is intended as slugs for a downstream call, but says nothing about result format, empty-query behavior, or ranking beyond what the schema states. Adequate, not rich.

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, zero waste, with the primary purpose front-loaded and the sequencing hint second. Nothing to trim.

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?

An output schema exists and the input schema is fully documented, so return values and parameter meanings need not be restated. The description covers what it searches and when to call it; only minor context (e.g. how many slugs to resolve or that locale controls response language) is left implicit.

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 all four parameters (query, locale, language, limit) are already documented in the schema, including the empty-query fallback and the language-slug filter. The description adds no parameter detail, 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?

States a specific verb (Search) over concrete resources (cities, countries, school names), and explicitly distinguishes itself from the sibling search_language_schools. An agent can tell what this does 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?

Gives an explicit ordering rule: use this before search_language_schools to resolve place names to slugs. Names the alternative tool and the condition that selects it, so the routing decision 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 readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered by structured data. The description adds value by disclosing the return fields (school_id, url, indicative from-price, reviews) and the critical caveat that prices are not a booking quote. That caveat is genuinely useful behavioral context not present in annotations. Still, it doesn't cover pagination, ranking logic, or empty-result 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 front-loaded sentences with zero waste: the first declares purpose and return shape, the second delivers the critical pricing caveat and points to the correct sibling. Every sentence earns its place.

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

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

With an output schema present, the description correctly avoids re-explaining return structure, and the annotations cover safety hints. The pricing caveat and sibling routing are the key missing pieces an agent needs, so the essential behavioral guidance is there. Minor gaps remain around filter-selection strategy given the eight optional parameters, but nothing critical for correct invocation 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%, so every parameter already has a description in the schema, including city vs cities preference and limit bounds. The description adds no filter syntax, slug source, or example usage beyond what the schema provides. Baseline 3 is appropriate when the schema does all the parameter 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+resource (search and rank language schools) and immediately distinguishes itself from the related pricing sibling by disclaiming that prices are not a booking quote and directing to calculate_trip_price. An agent can tell exactly what this tool does relative to get_school, list_courses, and calculate_trip_price.

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

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

The description routes the agent to calculate_trip_price for totals, which is a clear when-to-use-nothing-else signal. However, it does not explain when to prefer this tool over get_school or search_destinations, nor how city vs cities vs query filters should be chosen. Usage is implied but not fully specified.

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