Filipe Santos Fotografia

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

Annotations declare a non-read-only, idempotent, non-destructive open-world call, and the description adds real context beyond them: payment is taken now via MB WAY/Multibanco/card, the buyer receives the voucher by email, the code is valid 12 months, and unused balance persists. It does not explain duplicate-purchase or failure behavior, which matters for a payment flow, keeping it out of the top band.

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 90 words in a single paragraph, with the core purpose front-loaded before the price/delivery detail. Dense but nearly every clause carries decision-relevant information; the parenthetical price list and delivery flow make it slightly run-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 no output schema, the description closes the loop by describing what the buyer gets (emailed voucher, printable/forwardable, 12-month code, balance carryover) and what must be confirmed before calling. For a nine-parameter payment tool, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 78%, but the description adds meaning the schema lacks: it maps prices to each package enum value (base 35€, completo 150€, equipa 250€, familia 200€, natal 159€) and states the exact permitted amounts (50/100/150/200/250), which corrects the schema's nonsensical ±9007199254740991 bounds on amount_eur. It also notes the phone requirement for MB WAY.

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 opens with a specific verb and resource ('Sells a digital gift voucher for the studio') and immediately scopes it to two purchase modes: a named session package or a fixed amount. The selling verb cleanly separates it from siblings like check_gift_voucher and cancel_studio_booking, which do not transact.

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 precondition: 'Only call after the buyer confirms what to buy, their name and email, and the payment method,' which maps directly to the three required parameters. It does not, however, name the alternative sibling (check_gift_voucher) for the status-checking use case, so the exclusion is not fully closed.

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 mark this destructive and idempotent, but the description goes well beyond them: no cash refunds, conversion to 12-month studio credit, the 24 h cutoff, and the distinct outcomes for unpaid pre-bookings and voucher-paid bookings. This is exactly the consequence detail an agent needs before a destructive call.

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?

Dense but front-loaded: identity of the booking first, then the mandatory confirmation step and the policy branches. Every sentence conveys a distinct rule (refunds, timing, reschedule, voucher/unpaid edge cases), though the policy block is long enough that a summary line would help scanning.

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

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

With no output schema, the description compensates by describing what each outcome produces (credit code, released slot, voucher return). Combined with the 100%-covered two-parameter schema, an agent has everything needed to call 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 already 100% for both parameters, so the baseline is 3. The description repeats the reference format example and clarifies that the email must be the one used at booking, but adds little beyond what the schema properties state.

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 ("Cancels a studio booking") plus the exact identification keys (reference and booking email). It is distinguishable from siblings like reschedule_studio_booking, which it effectively names as the alternative path.

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 preconditions (tell the user the policy, get confirmation), the hard constraint that cancellation under 24 h is not possible, and an alternative action (offer to reschedule, up to 2 times). An agent knows both when to call it and when to route elsewhere.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the return content (validity, balance, expiry), which is somewhat useful given there is no output schema, but it says nothing about behavior for an unknown/invalid code or any rate limits, so the added value is modest.

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

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

A single front-loaded sentence with the verb first and the payoff ('whether it is valid, its balance and expiry date') at the end — no wasted prose. The inline format example is slightly redundant with the schema pattern, which keeps it from being a 5.

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

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

For a one-parameter read tool with no output schema, the description supplies the essential missing piece — what the call returns — while annotations cover safety. The only gap is behavior on an unrecognized code, which is minor for a tool this simple.

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 0% schema description coverage, the description must carry parameter meaning, and it does name the format explicitly (FSF-XXXX-XXXX), matching the schema pattern in a human-readable way. It also clarifies that the single input may be a gift voucher or a studio credit code, which the schema does not distinguish; only a formal error-case explanation is missing.

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 ('Checks') plus the resource ('gift voucher or studio credit code') and enumerates what the check yields (validity, balance, expiry date). This clearly separates it from the sibling buy_gift_voucher, which creates rather than inspects a voucher.

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 use case is only implied: an agent infers it should call this to verify a voucher before redeeming or accepting one. There is no explicit when-to-use statement, no mention of prerequisites (e.g., that the booking flow may need this first), and no named alternative or exclusion.

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 establish that this is a non-destructive, closed-world read. The description adds substantial behavioral context beyond that: 21-day max range, Mon–Fri 10:00–18:00 Lisbon time, closure on Portuguese public holidays, and a 24-hour booking lead time. It does not mention rate limits, but the coverage is well above the annotation baseline.

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 dense sentences with zero filler; the core purpose is front-loaded and the constraints and return format follow in a logical order. 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 no output schema, the description correctly states the return format ('ISO 8601 with the Lisbon offset') in addition to the availability rules. Nothing an agent needs to invoke this correctly appears to be 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 package enum is documented in detail in the schema, so the schema carries parameter meaning. The description adds only one extra constraint, the 21-day maximum span between from_date and to_date, which is useful but marginal beyond the schema baseline.

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?

Specific verb+resource: 'Lists free start times at Estúdio 266 for a bookable package between two dates.' Scope and subject are unambiguous, and it is clearly the availability-query sibling of request_studio_booking / reschedule_studio_booking rather than a booking mutation.

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

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

The description implies usage (checking availability for a package before booking) and supplies the operating constraints, but it never explicitly states when to call this versus request_studio_booking or the other siblings. Guidance is implied rather than stated.

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

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

Annotations already declare it as a non-read-only, open-world, non-destructive write. The description adds real value beyond them: it creates a record in the studio's system, triggers a confirmation email, and promises a personal proposal within 24 hours. It does not address the idempotentHint=true annotation (duplicate-call behavior), which is the one remaining behavioral gap.

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

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

Three sentences, front-loaded with the action and the scoping rule before the outcome and the precondition. The long parenthetical enumeration of service types is dense but earns its place as disambiguation against the booking siblings.

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 10-parameter mutation tool with no output schema, the description covers the trigger condition, the side effects (system record, email, 24h proposal), and the required user confirmation. Nothing essential for correct invocation 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 90%, with enum values and per-field descriptions already fully documented in the schema. The description adds no field-level syntax, format, or default guidance beyond what the structured data provides, 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 verb+resource ('Sends a quote request to the studio') and immediately scopes it to 'anything not bookable directly', enumerating the covered service categories. An agent can distinguish it from request_studio_booking (direct bookings) and buy_gift_voucher without opening any schema.

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

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

Explicitly states the routing condition ('anything not bookable directly') and a hard prerequisite ('Only call after the user confirms the details and agrees to be contacted'). It does not name the sibling to use instead for directly bookable items, leaving that inference implicit.

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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real context beyond them: the slot is only held temporarily (hold_expires_at), confirmation happens on payment, and the idempotency key is specified (same email, package and time returns the same pre-booking). It stops short of describing failure/expiry outcomes, so not 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 purpose, then preconditions, then payment and pricing guidance; every sentence carries operational information. It is dense and multi-topic, but nothing is padding.

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

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

For an 11-parameter write tool with no output schema and no failure semantics, the description covers preconditions, payment routing, hold behavior, vouchers and idempotency. It could still say what the caller receives (booking reference, hold_expires_at) or what happens if the hold lapses.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds policy meaning not in the schema: MB WAY is preferred for instant payment and Multibanco is only valid >48 h out, and it frames extras/make-up as upsells. It largely repeats enum pricing already documented in the schema, which caps it below 5.

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 (pre-books), the resources it covers (portrait, family session, studio rental), the slot source (get_studio_slots), and the side effect (starts payment). An agent can distinguish it from siblings like get_studio_slots or request_quote without opening any schema.

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

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

Explicit precondition: 'Only call after the user has explicitly confirmed the package, the exact start time and their contact details.' It also gives alternatives and their constraints (suggest MB WAY first; Multibanco only for sessions >48 h away), which is exactly the when/when-not guidance an agent needs.

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