Filipe Santos Fotografia

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

Annotations already cover the read/write profile, but the description adds real value beyond them: no subscription, credits never expire, credits are added automatically on payment confirmation, a confirmation email is sent, and the accepted payment rails. It does not explain what happens on a failed or partial payment, which is the main remaining 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?

Purpose and pricing are front-loaded, and the closing sentence is the actionable call condition, so the ordering is sensible. It is a dense single paragraph that packs several clauses together, but nearly every clause carries operational 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 no output schema, the description usefully describes the post-purchase outcome (caricatures credited automatically, confirmation email). For a 6-parameter purchase with payments involved, it is nearly complete; only error/failure behavior and the raw enum values' mapping back to the tool remain 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 coverage is already 83%, but the description compensates where the schema is thin: it expands the payment_method enum ('MB WAY, Multibanco or card'), restates the 1-10 pass bounds, and clarifies that the email is the one the license was registered with. It adds meaning, though phone-required-for-MB-WAY is left to the schema.

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 ('Buys event passes for the ... license'), and names the exact product being purchased, making it clearly distinct from siblings like buy_gift_voucher and check_caricature_booth_credits. An agent can identify the operation and its counterpart tool 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?

It gives an explicit precondition: 'Only call after the user confirms the number of passes, total price and payment method,' plus required inputs (license key and registered email). It never names a sibling alternative (e.g. check_caricature_booth_credits for checking balances first), so it stops short of full when/when-not 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 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 cover the safety profile (read-only, idempotent, non-destructive, closed-world), so the description's added value is telling the agent the exact return content (remaining and used counts) plus the auth prerequisite of a registered email. With no output schema, that return-shape disclosure is genuinely useful, though it omits any failure behavior for invalid keys.

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, front-loaded with what the tool reports and followed by the inputs required. No filler or restated field names.

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 balance check with no output schema, the description covers purpose, inputs, and the shape of the result. It stops short of noting error cases (unknown key/unregistered email), a minor 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 coverage is only 50% (the email parameter carries no description), and the description compensates by clarifying that the email must be the one the license was registered with, which is semantic meaning beyond the format/pattern in the schema.

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 ('Shows') and resource (remaining/used AI caricatures on a vendor's Photobooth Caricatura license), so the agent knows exactly what data it returns. It never names the sibling buy_caricature_booth_credits, but the check-vs-buy contrast is inferable from the verb and sibling list.

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 gives a prerequisite ('Needs the license key and the email it was registered with') but never says when to call this versus buy_caricature_booth_credits or start_caricature_booth_demo. Usage 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds genuinely new behavior: the two-team model that gives 'limited' its meaning, the three possible outcomes, and the crucial caveat that the answer is indicative and the date is only reserved after proposal acceptance. It omits nothing an agent needs operationally for a read-only check.

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

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

Three compact sentences, front-loaded with the core verb and resource, then scope, then return states, then usage. The long parenthetical is dense but informative rather than redundant. No filler sentences.

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 supplies the return vocabulary (available / limited / fully_booked) and the non-binding nature of the result, which is what the agent needs to interpret output. It stops short of saying whether the optional service parameter narrows the availability computation, a minor open question.

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%, with the date format pattern and a fully documented service enum, so the schema carries the parameter burden. The description only loosely echoes the service categories ('weddings, baptisms, corporate events') without adding format or selection guidance beyond the schema, 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 and resource ('Checks whether the studio can still take an event on a given date') and immediately clarifies the scope of work covered (weddings, baptisms, corporate, on-location) plus the two-team constraint. It separates itself from request_quote by declaring it must run beforehand, so an agent can route correctly.

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 precondition and ordering rule: 'Use before request_quote when the user has a date.' This is clear when-to-use guidance tied to an alternative tool. It does not, however, address when this is superfluous or how it relates to get_studio_slots, so exclusions are absent.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds that the returned data is the *public* catalog (a scoping fact) but says nothing about return format, pagination, or localization. Moderate added value against an already-complete annotation set.

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

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

The purpose is front-loaded, but the first sentence is an overlong run-on enumeration of catalog sections that reads as keyword stuffing. It is defensible for retrieval matching, yet a list of sections would be tighter and easier to scan.

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 one optional parameter, no output schema, and rich annotations, the description is largely sufficient – it even enumerates the catalog contents, partially substituting for a missing output schema. It could still state whether results are exhaustive or paginated.

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 enum values are already self-documenting. The description only adds 'Optionally filter by category,' which is essentially a restatement of the schema's default 'all' behavior. Baseline 3 is correct when the schema does the heavy lifting.

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 ('Returns Filipe Santos Fotografia's public catalog with prices') and enumerates the exact catalog domains it covers. This makes it instantly separable from transactional siblings like request_quote, buy_gift_voucher, or check_event_date.

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 trigger conditions: 'Use when the user asks what the studio offers, how much something costs, or how booking works.' Clear usage context, but it never names the alternative (e.g. request_quote) for users who want an actual binding price quote rather than the public catalog.

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.

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

Annotations declare the safety profile (destructiveHint=true, idempotentHint=true, openWorldHint=true), and the description adds substantial behavior beyond them: a maximum of 2 reschedules, a 24-hour lead-time restriction, and a required user-confirmation workflow. These are real operational constraints an agent must honor and cannot 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?

Three tight sentences with the core action and the two most important constraints front-loaded. No filler, though the clause about the email used to book is slightly redundant with the subsequent sentence.

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 destructive-ish mutation tool with no output schema, the description covers prerequisites, reschedule limits, and the timing restriction well. It stops short of stating what a successful or failed reschedule returns or what happens to the original slot on failure.

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 33% — just new_start is documented, and even that mirrors the description's pointer to get_studio_slots. The description names booking reference and booking email as the identifying pair, adding mild meaning, but it never explains the FSF- reference format or the email constraints encoded in the schema patterns.

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 ('moves an existing studio booking ... to a new free time') plus the identifiers required. It is clearly distinguishable from siblings like cancel_studio_booking and request_studio_booking 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 explicit prerequisites ('check free times first with get_studio_slots for the same package'), a confirmation step ('confirm the new time with the user'), and a hard exclusion ('not possible less than 24 hours before the current session'). When-to-use, the alternative tool, and when-not are all 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 non-read-only, open-world, idempotent, non-destructive, but the description adds real behavioral detail beyond them: a license is created with 10 free caricatures, the key and guide are emailed, the studio follows up, and a repeat call returns the same license (concretizing idempotentHint). Side effects and the human follow-up step are disclosed.

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?

Audience and purpose are front-loaded, and the operational constraints (one demo per email, confirmation prerequisite) are placed at the end where they matter most. It is slightly padded with product-marketing phrasing about QR codes and frames, but the content is informative rather than repetitive.

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

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

For a five-parameter, no-output-schema tool, it covers audience, precondition, side effects, idempotency, and the delivery channel (email). It does not describe what the caller receives synchronously, but with no output schema the description's coverage of the outcome is adequate.

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 80%, so most parameters are already documented (email purpose, notes, phone, business_name). The description reinforces that business name and email must be user-confirmed but adds no format or syntax beyond the schema, so the baseline 3 holds.

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?

State a specific verb+resource ('starts a free demo of the Photobooth Caricatura software') and defines the audience (event vendors) and the artifact produced (a license with 10 free caricatures). It is clearly distinguishable from siblings like buy_caricature_booth_credits and check_caricature_booth_credits.

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 confirms the business name and email.' It also states the one-demo-per-business-email rule, which bounds repeat invocation. It stops short of naming an alternative tool for the credit-purchase path, so it is clear context without full alternative routing.

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