BridgeDays

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

Annotations already declare readOnlyHint and openWorldHint, yet the description adds substantive context beyond them: bridge days are defined (one or two days of leave joining a holiday to a weekend), offers may be returned, and sponsored: true offers are paid placements that must be labelled as sponsored. That last point is a genuine disclosure an agent could not infer from structured fields.

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?

Roughly three sentences, front-loaded with what is returned before the usage trigger. The middle sentence is dense but each clause (holidays, offers, sponsored flag) carries distinct information, so little is wasted.

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 documented, yet the description still tells the agent what categories of results arrive and how to treat sponsored offers. Combined with annotations covering the safety profile, nothing an agent needs to select or call this tool 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 country and year are already documented in the schema, including the 2-letter-or-English-name format and the current-year default. The description only restates the country/year framing ('in a country for a year') without adding format or edge-case 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?

The description names a specific verb and resource ('Lists every long weekend in a country for a year') and enumerates the payload: leave-free long weekends, bridge days, nationwide public holidays and travel offers. The scope wording ('every ... for a year') implicitly separates it from the singular sibling next_long_weekend, but no sibling is named explicitly, so it falls 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?

It states clearly when to reach for it: 'Use it when someone asks about public holidays, long weekends, bridge days or the best days to take off.' That is a genuine trigger list. It does not say when NOT to use it or point to alternatives such as next_long_weekend for a single quick answer or plan_annual_leave for leave planning.

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

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

Annotations only declare it as a safe read (readOnlyHint, openWorldHint); the description adds non-obvious behavior no annotation conveys: results are ordered with paid placements first, flagged sponsored: true, and must be rendered as 'Sponsored' with the link passed through verbatim. This is exactly the kind of commercial/results-shaping context that annotations can't express.

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

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

Three sentences, front-loaded with what the tool returns, then when to use it, then handling rules. Every sentence carries weight, though the country phrase slightly duplicates the schema.

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, open-world search with an output schema present, the return shape needn't be explained, and the description still adds the critical commercial-ordering and presentation contract. Nothing an agent needs to call and correctly render this tool 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 all three parameters (country, from, to) are already fully documented, including the 2-letter-code-or-English-name format. The description's 'for travellers from a country' restates the schema without adding format or edge-case 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?

It states a specific verb+resource: travel offers (stays, trips) from businesses constrained by a date range and origin country. The scope is sharper than the generic sibling names (find_long_weekends, start_planner), though it never explicitly contrasts itself against 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 a concrete triggering situation ('when someone has dates for a break and asks where to go or what is on offer'), which is enough for an agent to pick this tool over a planning tool. It stops short of naming an alternative or an exclusion 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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful scope constraint that annotations do not convey: only countries with holiday data are returned, not every country.

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 noun phrase with no filler; everything in it 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 fields do not need explaining. The description supplies the key semantic (which countries and what the codes are); only the precise code standard (ISO alpha-2) is left unstated.

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?

Zero parameters, so there is nothing to disambiguate and the baseline is 4. The description's note about 2-letter codes is return-value semantics rather than parameter semantics.

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?

Identifies the resource precisely (countries with public holiday data) and the payload shape (2-letter codes), which is enough to distinguish it from the long-weekend/planner siblings. The verb is only implied by the title 'List', so it is clear but not maximally 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?

No explicit when-to-use, prerequisites, or alternatives are given. Usage is only implied: an agent would infer this is a reference lookup whose codes feed other BridgeDays 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-data exposure are covered. The description adds genuine behavioral detail beyond that: the window is computed relative to today, exactly three weekends are returned (nearest plus two after), and each carries a leave-required flag.

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 padding, and the return window leads the sentence before the usage examples. Every clause carries information the agent can act on.

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, return-value detail is not required, yet the description still summarizes the payload (dates, days away, leave needed, two following weekends) and the 'from today' computation basis. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single 'country' parameter is fully documented in the schema, including accepted formats (DE or Germany). The description adds nothing about the parameter, so 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 resource and scope: the nearest upcoming long weekend in a country, counted from today, plus the two following it. The singular 'next' framing implicitly distinguishes it from the plural sibling find_long_weekends, but no sibling is named so the agent must infer the boundary.

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

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

Gives concrete trigger phrasings ('when is the next long weekend?', 'any time off coming up?') that map user intent directly onto the tool. It stops short of stating when NOT to use it or pointing to find_long_weekends/plan_annual_leave as the alternative.

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 cover read-only and open-world behavior, and the description adds real context beyond them: travel offers may accompany breaks, an offer with sponsored: true is a paid placement that must be presented as sponsored, and payment never alters the plan. Those are policy/disclosure obligations an agent could not infer from the schema, though pagination or rate-limit behavior is not mentioned.

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

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

Three sentences, front-loaded with the return payload before the offer/sponsorship caveat and the usage cue. Dense but each sentence carries information; the closing usage sentence could have been folded into the first without loss.

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?

Because an output schema exists, the description is not obliged to enumerate return fields, yet it covers the plan outputs, the adjacent travel-offer behavior, the sponsorship rule, and the call trigger. Nothing needed to invoke the tool 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 every parameter (days, year, months, country) is already documented in the schema. The description only echoes the two required inputs ('Given a country and a number of leave days') without adding format or constraint detail, so the baseline of 3 is correct.

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 gives a specific verb and resource ('returns the breaks that give the most days off in a row, the exact dates to request as leave, the totals, and a link'), so an agent knows exactly what comes back. It implicitly separates itself from single-weekend siblings like find_long_weekends by framing the result as a year-long plan, but it never names a sibling explicitly, which keeps it 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?

It states clear trigger conditions: 'Use it when someone asks how to get the most time off from their holiday allowance, or to plan their vacation days for a year.' That is a genuine when-to-use clause, but there is no when-not guidance and no pointer to the alternative tools (find_long_weekends, start_planner) for adjacent requests.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful behavioral context: a form appears inside the conversation, the resulting plan renders in the same card, and the agent should not ask for missing fields in text. It does not cover failure modes or whether the form can be cancelled.

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

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

Three sentences, front-loaded with what the tool does, followed by precise routing rules. Every sentence earns its place: the form fields, the output behavior, the call-order instruction, the pass-through rule, and the sibling alternative.

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 explained. Given the annotations, full schema coverage, and sibling tool set, the description supplies everything an agent needs: purpose, call order, exclusion condition, and how to handle already-mentioned parameters.

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 days, year, and country. The description still adds meaningful semantics by saying to pass along anything the user did mention, which clarifies that these are optional pass-through hints rather than required inputs.

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

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

The description states a specific verb and resource: it opens a form inside the conversation for planning time off, then shows the plan in the same card. It distinguishes itself from sibling plan_annual_leave by explaining exactly when to use each.

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

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

It gives explicit when-to-use guidance: call FIRST when the user wants to plan a holiday and has not already given both a country and a number of leave days. It names the alternative path (plan_annual_leave directly) and instructs not to ask those questions in text.

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