Zarvo

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and idempotentHint=false; the description adds real value on top by disclosing slot rechecks, plan expiry, dual link types, and that no court is booked. It stops short of saying what happens if a recheck fails or how long the plan lives.

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 with the usage gate front-loaded and no filler. Each clause contributes a distinct fact: when to use, what it does mechanically, and what it does not do.

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 little explanation, and the description does flag the two link types. However, for a state-mutating tool with three required parameters and zero schema descriptions, the unexplained mode/age_confirmed/original_request inputs leave genuine gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning — it explains only the 'one to three selected court options' cap on slot_ids. The mode enum (choose_one vs book_all) is a genuine behavioural fork and age_confirmed and original_request are entirely unexplained, leaving required inputs ambiguous.

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 ('creates an expiring Zarvo plan') plus concrete outputs ('separate guest and private organiser links') and an explicit boundary ('does not book a court'). That boundary cleanly separates it from the booking-oriented siblings such as get_booking_handoff.

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?

Opens with an explicit gate: 'Use this only when the user explicitly wants to organise one to three selected court options with other people.' It implies the prerequisite of already-selected slots but never names the alternative tool (get_booking_handoff) or states what to do instead when the user does want to book.

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, open-world, so the safety profile is covered; the description adds non-obvious behavior instead: the limit is a total across all dates, results carry Zarvo club IDs when matched, and number_of_players affects pricing only. It does not mention pagination or truncation behavior when the limit is hit, which keeps it from a 5.

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

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

Front-loaded with the usage trigger, then the critical data-hygiene rule, then per-parameter caveats — every sentence carries operational information. It is dense for four sentences but no line is filler; a slightly tighter grouping of the parameter notes would improve scanability.

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 spelled out, and the description still flags the useful bit (Zarvo IDs when matched). For a 10-parameter, open-world lookup it covers the pitfalls an agent would otherwise hit, missing only guidance on choosing date vs. date_range and on limit truncation.

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 only 30% schema description coverage, the description compensates meaningfully: it clarifies that limit applies across the whole date range rather than per date, that number_of_players is price-only and singles_court is the capacity filter, and that provider/club_name must match a prior search result exactly. It leaves the date vs. date_range interaction and max_days behavior unexplained.

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 (get available courts for a named provider club) and scopes it to one date or a bounded range. It explicitly separates itself from search_courts and from the club-selection step performed by search_clubs.

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 positive trigger (user has selected a named club and wants availability), a hard exclusion ("Do not use for a broad nearby search; use search_courts instead"), and a data-provenance rule (copy provider and club_name from the search_clubs result, never infer provider). That is explicit when/when-not/alternative 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 cover readOnly, idempotent, openWorld, and non-destructive, so the safety profile is known. The description adds genuinely new behavior: the slot is revalidated at call time and can come back unavailable with a reason, and the user completes login/booking/payment on the provider site while Zarvo never reserves inventory. That is exactly the kind of external-side-effect context an agent 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?

Three tight sentences, front-loaded with the trigger and outcome statuses, and the scope limitation stated last. Every sentence carries information an agent needs.

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

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

The output schema and annotations already cover return shape and safety, so the description rightly focuses on workflow and the unavailable/available outcome. The one real gap is that neither parameters nor their constraints are explained anywhere.

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 description says nothing about slot_id or number_of_players, so the description fails to compensate. The number_of_players constraint (min 1, default 4, max 4) is especially opaque without explanation.

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 action (revalidate a provider slot, return handoff URL and current price) with clear scope: Zarvo does not reserve inventory or complete checkout. It doesn't explicitly differentiate from the sibling recheck_slot, which sounds like a near-identical operation.

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

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

"Use this directly after the user chooses a slot" gives a clear trigger condition, and the description implies this is the final step before handing off to the provider. It stops short of naming when NOT to use it, e.g. versus recheck_slot or get_availability.

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 read-only, idempotent, non-destructive and closed-world behavior, so the bar is low. The description still adds real value by warning that the result is static directory metadata rather than live availability, preventing an agent from treating it as a freshness source; it says nothing about behavior for an unknown or malformed ID.

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

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

Two sentences, no filler: the trigger condition and returned fields come first, and the scope caveat follows. 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?

With an output schema present, the description needn't explain return values, and the prerequisite plus the live-vs-static distinction cover the call decision. The only material gap is how to obtain a valid club_id, which the sibling search_clubs would supply.

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 the single club_id parameter, so the description must compensate. It signals that the value is a pre-existing "Zarvo club ID" rather than a free-text name, which is useful, but it never mentions the kebab-case slug format encoded in the schema pattern or where such an ID originates.

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 Zarvo padel club) and enumerates exactly what is returned — address, coordinates, facilities, racket rental, contact, website, socials — so the agent knows the payload without opening the output schema. It does not name the sibling that finds the ID (search_clubs), leaving the differentiation only partially 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 this after a Zarvo club ID is known" is an explicit prerequisite, and "returns directory metadata, not live availability" excludes the availability siblings. It stops short of naming search_clubs as the way to obtain the ID or get_availability as the alternative for live data.

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 readOnly, idempotent, non-destructive, open-world behavior; the description adds explicit negative guarantees (never books, holds inventory, takes payment, or returns checkout) that remove ambiguity about side effects. It doesn't say what happens when the slot is no longer available, or whether errors vs. a negative result are returned, leaving a gap for a verification tool.

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

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

Two short sentences, front-loaded with the optionality caveat and the sibling reference, then the side-effect disclaimer. 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?

Behavioral safety and output shape are adequately covered (an output schema exists, so return values needn't be described), and the routing guidance is complete. But with six undocumented parameters at 0% schema coverage, the description leaves the agent guessing how the constraint arguments interact with the recheck.

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 six parameters, and the description mentions none of them. For a 'recheck' tool it is unclear whether date, earliest_time, latest_end_time, duration_minutes, and number_of_players re-apply constraints or are ignored — that is the single most important semantic question here and it goes unanswered.

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 concrete operation (confirm a selected slot's availability) and explicitly frames it as an optional revalidation step, which separates it from the booking flow. It does not name the resource being rechecked as sharply as it could (the slot and the constraint parameters aren't mentioned), 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?

It gives an explicit when-to-use ('call this only to confirm availability without proceeding to handoff') and names the alternative that already covers this case (get_booking_handoff revalidates before returning a URL). The agent knows exactly when this tool is redundant, which is rare and valuable.

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 safety (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint), so the bar is lower, yet the description still adds real context: live data, prices only "when published", a provider booking page in the response, and an explicit no-booking/no-payment boundary. It does not cover freshness/caching, empty-result behaviour, or how the open-world provider scope affects reach.

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 triggering condition, then return values, then the behavioural boundary. Every sentence earns its place and 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?

The output schema means return values need not be detailed, and the description still summarises them usefully. But for a 10-parameter tool with zero schema descriptions and two enums, the absence of any parameter guidance leaves an agent guessing at how to set search_days, radius_km, player_level or availability 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 0% across 10 parameters, so the description carries the full burden, and it explains none of them. The activity examples partially mirror the category enum (social, coaching, training, intro, junior, competition) but omit league, tournament and other, and nothing is said about location, start_date, search_days, radius_km, availability, player_level (1-7 scale), earliest_time or limit.

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) and resource (scheduled PadelStars activities), then enumerates the categories of activity covered (coaching, training, intro, socials, junior, competitions). That enumeration implicitly separates it from search_public_games and search_courts, but no sibling is ever named explicitly, so an 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?

"Use this when a player wants scheduled PadelStars activities" gives a clean triggering condition, and the category list narrows the case further. It also rules out booking behaviour, which points at get_booking_handoff by implication, but no alternative tool is named and no when-not-to-use case is spelled out.

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 cover the read-only/idempotent safety profile, but the description adds behavior they cannot: results are directory metadata rather than live availability, and a provider hint conflicting with the directory may be overridden by the canonical provider during name resolution. The 'do not infer provider from a club name' rule is a genuine behavioral constraint beyond the schema.

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

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

Front-loaded with purpose and routing, then filter semantics, then the provider caveat and follow-ups — a sensible ordering. It is dense and runs long, with several constraints compressed into single sentences, but no sentence is filler.

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

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

With an output schema present, return values need not be described, and the description still flags that results are metadata rather than availability. For an 8-parameter tool the only uncovered area is pagination/result-ordering and the interplay of limit with radius_km.

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 only 13%, so the description must carry parameter meaning, and it does for the non-obvious ones: query is club-name wording only, location is added only when an area was supplied, court_type/racket_rental/facility map to specific user requests, and provider is an explicit-hint-only filter. limit and radius_km are left unexplained, though their names and defaults make them largely self-evident.

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?

Uses a specific verb and resource ('lightweight directory lookup to find clubs') and states the returned fields (club_id, club_name, provider). It also explicitly bounds scope ('Zarvo club metadata, not live court availability'), which separates it from get_availability and search_courts.

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 routing rules: use get_club for full metadata, get_availability for live slots, and search_clubs for name/landmark/description resolution. It also states the when-to-use condition for each filter (location when an area was supplied, court_type for indoor/outdoor/covered) and instructs to preserve filters across refinements.

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 cover read-only/idempotent safety, and the description adds substantial beyond-annotation behavior: provider result normalization, catalogue venue IDs and coordinates being added, the limit applying across all dates rather than per date, MATCHi's null anonymous price surfacing as price_details.basis unknown, and travel time being a straight-line heuristic with a 15% soft-filter tolerance near max_travel_minutes rather than live routing. These are exactly the traits an agent cannot see from the schema.

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

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

Seven sentences with no filler, and the use-case trigger plus the sibling exclusions are front-loaded. It is dense and information-packed, but the clause count is justified by the number of non-obvious behaviors crammed into a 15-parameter tool; the caveat about null MATCHi prices is slightly buried mid-paragraph.

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, yet the description still flags the one return field an agent would misuse (price_details.basis unknown under a price ceiling). Given 15 params, nested date_range, and open-world provider fan-out, 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 only 20%, so the description must compensate, and it does for the highest-risk params: limit is clarified as a global cap across dates, date vs date_range as single-date vs bounded range, number_of_players as price-only with singles_court as the real capacity filter, and max_travel_minutes as a soft filter. It leaves provider, radius_km, court_type, the time-window params, and duration_minutes unaddressed, so the compensation is partial rather than complete.

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 ('searches configured providers' for bookable padel courts) and bounds the scope to a UK location on one date or a bounded range. It explicitly separates itself from venue-only discovery and public games, which are represented by siblings like search_clubs and search_public_games.

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?

Opens with an explicit 'Use this when...' trigger, then names the two things not to use it for ('venue-only discovery or public games'). It also routes a sub-decision ('use singles_court to require explicit singles support') rather than leaving it 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?

Adds genuinely non-obvious behavior beyond the annotations: the 14-day UK default window, that results are anonymous match metadata plus a provider join page, and that it never acts on the user's behalf. Annotations already cover read-only/idempotent safety, so this is strong; only rate limits or cross-provider variability are unstated.

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 tight sentences, front-loaded with the trigger condition, then default behavior, then the negative case. 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 an 8-parameter tool with an output schema present, the description covers the trigger, defaults, and return shape (anonymous metadata + join page) well. The remaining gap is the undocumented provider enum and radius semantics, which neither schema nor description explain.

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%, so the description must compensate and only partly does: it names date/time/level/limit filters and the 14-day default, but never explains provider, radius_km, or the relationship (mutual exclusivity?) between date and date_range. Baseline would be 3 given the partial 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 with scope: an *existing public* padel game *with an open spot*. It also explicitly rules out the adjacent-but-different job (empty-court bookings), which cleanly separates it from search_courts.

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 when-to-use ('a player wants an existing public game with an open spot'), when-not ('Do not use for empty-court bookings'), and guidance on which filters to omit unless requested. Nothing is left to inference about the default query shape.

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