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

The description adds significant behavioral detail beyond annotations: it notifies the provider, returns the booking as get_booking shows it, and refuses unavailable providers unless overridden. It does not explicitly state whether an existing provider is replaced (though destructiveHint=true implies mutation), but overall transparency is strong.

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 core action and scope, followed by behavioral details. Zero waste; every sentence adds value.

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

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

Given the mutation nature (annotations cover safety) and absence of an output schema, the description explains return shape, side effects (provider notification), and refusal logic. It is complete enough for an agent to call 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 100%, so the baseline is 3. The description adds meaning for even_if_unavailable (refusal logic) and implies whole_schedule scope ('or to its whole recurring schedule'), going beyond the schema's brief default descriptions.

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 (assign) and resource (provider or team to a booking), and explicitly extends scope to the whole recurring schedule. It clearly distinguishes the operation from siblings like create_booking or reschedule_booking.

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 clear context ('as Assign in the booking's sidebar does') and a key conditional behavior (refusal when unavailable unless even_if_unavailable is true). However, it does not explicitly compare to alternative tools or state when not to use it, though no direct sibling performs assignment.

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 destructiveHint=true and openWorldHint=true, but the description adds substantive behavior: no cancellation fee, store-rules precheck that injects an 'Other' reason with the caller's text, silence unless notify=true, and removal from list_bookings. These are exactly the side effects an agent needs before committing an irreversible action.

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

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

Four short sentences, front-loaded with scope and the key reassurance (no fee), followed by preconditions, effects, and post-state. No redundant restatement of the name or title.

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, non-idempotent mutation with no output schema and four params, the description covers preconditions, fee implications, notification behavior, and resulting visibility. Nothing material is left for the agent to guess.

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 baseline is 3; the description goes further by explaining the semantics of `reason` (auto-filled as 'Other' when the store demands a reason) and the consequence of `notify` (nothing is communicated unless true). That is meaning beyond the schema's plain field descriptions.

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 (cancel) plus resource (booking), with exact scope stated as 'one booking or its whole recurring schedule.' An agent can distinguish it from reschedule_booking and get_booking 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?

Gives clear context for use — checks the store's cancellation rules first, cancels like the sidebar button, no fee. It doesn't explicitly name alternatives (e.g. reschedule_booking for moving a booking) or state when not to use it, so it falls short of the top tier.

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 the safety profile (non-read-only, open-world, non-idempotent, non-destructive); the description adds the behavior that actually matters: the record lands as a draft, not a confirmed booking, and no notification is sent until it is booked. It also discloses the required UI handoff via form_url, which is not visible anywhere in 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 the core action, then the draft/notification consequence, then the form_url step — every sentence carries information. The parenthetical reference "Copies the booking as Duplicate in its sidebar does" is slightly awkward and could be tightened, but nothing 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?

With no output schema, the description still tells the agent what comes back (a draft found via list_drafts plus a form_url to complete the booking) and what state change occurred (nothing notified). For a one-parameter, open-world mutation tool this covers everything needed to invoke and follow up 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 100% and the single property is already documented as "Booking to copy, from list_bookings," so the baseline is 3. The description earns an extra point by enumerating exactly what is inherited from that id (customer, address, service, extras, price), telling the agent what the copy will contain.

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?

Opens with a specific verb+resource ("Start a new booking") and immediately scopes the mechanism: a copy of an existing booking carrying the same customer, service and price. It draws a direct analogy to the Duplicate sidebar action, which lets an agent distinguish it from siblings like reschedule_booking or cancel_booking 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?

Clearly states the trigger condition (you want a new booking that reuses an existing one's customer/service/price) and names the required follow-through: open form_url to pick a date. It points to list_drafts and list_bookings as the relevant companions. It stops short of stating when NOT to use it (e.g., an existing booking should be rescheduled rather than copied), so 4 rather than 5.

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 write, open-world, non-idempotent, and destructive hints. The description adds important behavior beyond annotations: an immediate password-invitation email, the need for a real email address, refusal of duplicate emails, the optional address becoming the default service address, and the return shape.

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

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

It is front-loaded and appropriately sized, with the creation action followed by side effects, constraints, and return behavior. There is some redundancy: the password-invitation email is mentioned in both the first and third sentences, and the phrase 'as Add Customer in the admin does' is awkward.

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 12-parameter mutation with no output schema, the description covers the action, key side effect, duplicate constraint, default-address behavior, and return shape. It does not address authentication, permissions, or reversibility, but it is otherwise complete enough to call 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 100%, so the schema already documents all 12 parameters. The description adds real semantic meaning for email (must be real because an invitation is sent; duplicates are refused) and address (becomes the default service address), which goes beyond 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 action and resource: 'Adds a customer as Add Customer in the admin does' and 'New customer in the store.' It references get_customer only for return shape, not as a sibling alternative, so sibling differentiation is limited.

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?

Usage is implied: use this when adding a new customer as the admin's Add Customer does. It provides a relevant constraint that an existing email is refused, but does not explicitly state when to use this versus get_customer, list_customers, or create_booking.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety bar is low. The description still adds real value beyond them: default date window (this month), inclusive end date semantics, which revenue states are reported (paid vs pending, earned vs unpaid), and that amounts are in the store's currency.

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 the one-line summary before the detailed enumeration. There is mild redundancy — the metrics listed in the first sentence are re-enumerated in the second — but the structured expansion into revenue/provider/booking/rating buckets is useful rather than wasteful.

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 carries the burden of describing return values and does so thoroughly across four metric families. Only minor gaps remain (per-item breakdowns, whether zero-activity dates appear), which are unlikely to affect an invocation decision for a two-optional-param read tool.

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

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

Schema coverage is 100% — both start_date and end_date already document the YYYY-MM-DD format and their defaults. The description's 'this month by default' merely restates the schema defaults and adds no new parameter-level detail, so the baseline 3 applies.

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

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

The description names a specific resource (store totals / admin Dashboard) and enumerates the metrics returned — revenue, provider pay, bookings, ratings, referrals — plus a breakdown into bookings, custom invoices and separate charges. That clearly separates it from the entity-listing siblings (list_bookings, list_charges, list_invoices), though it never names a sibling explicitly.

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?

Usage is implied rather than stated: 'Returns the figures of the admin Dashboard for the dates given (this month by default)' tells the agent it is a reporting call with optional dates, but there is no explicit 'use this when you want aggregates, use list_* when you want line items' guidance or any 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 already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered; the description earns credit by enumerating exactly what the response contains (arrival window, providers, price breakdown fields, provider pay). It does not mention permissions or rate limits, but for a read tool that is a minor 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?

Front-loaded summary sentence followed by one elaborating paragraph listing returned fields. Structure is good, though 'price breakdown' and provider pay are restated across the two sentences, a small redundancy.

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 carries the burden of explaining return content and does so thoroughly — customer, address, providers, service parameters, notes, price components and provider pay. It lacks an explicit pointer to list_bookings for enumeration, which is the only notable gap for a 1-parameter read tool.

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

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

Schema coverage is 100% and the single parameter already documents 'Booking id from list_bookings', so the schema does the heavy lifting. The description adds only 'by id' framing, which is already implied by the required booking_id field — baseline 3.

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

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

States a specific verb and resource ('Reads a booking by id') and the leading line 'One booking with its price breakdown...' makes clear this returns a single record, implicitly distinguishing it from list_bookings. It stops short of explicitly naming the list sibling as the alternative, so sibling differentiation is inferred rather than stated.

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

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

Usage is only implied: an agent gathers it should call this when it has a booking id. There is no explicit when-to-use, when-not-to-use, or naming of alternatives such as list_bookings for enumeration.

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, idempotent, open-world, and non-destructive behavior. The description adds substantial context beyond annotations: it itemizes returned fields, notes that uncharged bookings include past ones, and clarifies that times are in the store's time zone.

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

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

It is front-loaded with a one-customer summary, then useful detail. There is some repetition between the first sentence and the 'Returns...' sentence, and the second sentence is long, but there is no empty 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?

No output schema exists, so the description must carry return semantics; it does by listing contact fields, addresses, booking counts, uncharged bookings, gift cards, referral summary, and time zone. It stops short of describing the response shape or not-found behavior, so it is not fully exhaustive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not elaborate on customer_id beyond identifying the customer; the schema's 'from list_customers' is the only usage hint.

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 single customer and enumerates the profile content, so the resource and scope are unambiguous. The singular 'One customer' separates it from list_customers, even though no sibling is explicitly named.

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?

There is no explicit when-to-use or when-not guidance in the description, and no sibling tool is named for comparison. The required customer_id plus the schema note 'from list_customers' implies a lookup after listing, but the description itself gives no selection criteria.

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, openWorld and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: it explains the data scope mirrors the admin provider page, clarifies team-vs-member shape ('the team's members and lead (for a team) or the teams it belongs to'), and notes payment logs are raw BookingKoala records. It does not mention permission requirements or behavior for an invalid 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?

The summary clause is front-loaded before the detailed enumeration, so an agent skimming gets the gist immediately. The second sentence is long but every clause names a distinct returned data category. Minor redundancy between 'contact' in sentence one and 'contact details' in sentence two.

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 bears the burden of describing return content and does so thoroughly across contact, category, priority, permissions, team structure, reviews and payment logs. Gaps remain around review pagination or limits, error behavior for unknown ids, and whether payment logs are a truncated subset. Adequate but not airtight.

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%, documenting provider_id (including that it can be a team) and payment_logs_limit with its 1-50 range and default. The description adds only marginal reinforcement by reiterating that team members and payment logs are included. Baseline 3 applies since the schema carries the 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?

The opening line states a specific verb and resource ('One provider or team') and enumerates the facets returned: contact, category, team members, reviews, payment logs. It implicitly contrasts with list_providers by fetching a single entity, though it never names that sibling. An agent knows what the tool returns but must infer the single-vs-list distinction from the schema rather than the prose.

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?

Usage is implied by 'provider_id from list_providers' in the schema and by the singular 'One provider', so the retrieve-by-id-after-listing pattern is inferable. However, the description states no explicit when-to-use or when-not conditions and names no alternative such as list_providers for bulk retrieval. Minimum viable 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?

Beyond the read-only and idempotent annotations, the description discloses ordering ('newest schedule dates first within the filter'), returned content (customer, address, assigned providers, total, charged status), a key exclusion (cancelled bookings are not listed), and pagination behavior ('Page with next_cursor'). These are meaningful behavioral traits an agent needs in order to invoke and interpret the tool correctly.

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 description is compact and front-loads the resource scope before listing ordering, filters, exclusions, and pagination. The opening status fragment is slightly redundant with the schema enum, but it does not materially bloat the definition.

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 eight-parameter listing tool with no output schema, the description supplies enough context about what is returned, how results are ordered, what is excluded, and how pagination works. Combined with the annotations and fully documented schema, an agent has what it needs to call the tool 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?

The schema already documents all eight parameters at 100% coverage, including defaults, formats, and enum meanings, so the baseline is 3. The description reinforces the filter categories but adds little parameter-level detail beyond what the schema provides.

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 clearly states that this tool lists bookings and scopes the resource with statuses, ordering, included fields, filters, and an exclusion for cancelled bookings. It is distinguishable from mutation siblings like create_booking or cancel_booking, but it does not explicitly contrast itself with read siblings such as get_booking.

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?

Usage is implied by phrases like 'as the Bookings page shows them' and by the available filters, which tells an agent this is the list-oriented read tool. However, there is no explicit when-to-use guidance versus get_booking or other list tools, and no stated when-not-to-use conditions.

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

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

Annotations already declare read-only/idempotent, and the description adds genuinely non-obvious behavior: ordering ('newest first'), the absence of a total, and pagination termination semantics ('next_cursor is set while a full page comes back') — a quirk that would otherwise cause an agent to stop paging early. The empty-result precondition explains a confusing zero-row outcome.

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

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

Front-loads the resource and return shape, then filters, then pagination and empty-state caveats — a sensible order with essentially no filler. The second sentence is long and comma-chained, but every clause carries 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 carries the return-shape burden and does so well: nested payments with amount, tax, refunded amount and card, plus ordering and cursor semantics. It stops short of naming the response envelope or the per-page default, but nothing critical to a correct call 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%, so limit, cursor, search and the date bounds are already documented. The description only restates the filters in prose ('Filter by booking day and search by customer') plus the cursor hint, adding little syntax or edge-case detail beyond the schema; baseline 3 applies.

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

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

Opens with a specific verb and resource ('Charged bookings with their payments and refunds') and immediately scopes it to charged bookings only, which separates it from list_bookings and list_invoices. It also enumerates the sub-resources returned (charge, extras, tips, fees, refunds), so an agent knows exactly what kind of row this returns.

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 selection context: filter by booking day, search by customer, and an explicit empty-state condition ('empty until the store charges through a connected payment processor or marks bookings paid in cash'). It also routes to a sibling ('booking_id and payment_log_id go to refund_charge'), though it never explicitly contrasts with list_bookings or list_invoices.

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 the safety profile (readOnly/idempotent/non-destructive), while the description adds non-obvious behavior: results are newest-first, include both active and deactivated records by default, no total count is available, and next_cursor is only set when a full page comes back. That pagination-termination rule is exactly the kind of detail an agent cannot infer from the 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?

Two tight sentences, front-loaded with what is returned, then ordering and pagination caveats, then the sibling handoff. No redundant restatement of the title or 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?

There is no output schema, yet the description still conveys the return shape (customer records with email and phone), ordering, default status scope, and how paging ends. For a zero-required-parameter list tool that is 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 100%, with limit range, cursor source, search semantics and the status enum all documented inline, so the schema carries parameter meaning. The description only echoes the search fields and the active/deactivated notion, adding no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States the resource (the store's customers) and what it carries (email and phone), plus the search fields, which is a specific verb+resource framing. It also distinguishes itself from the get_customer sibling by naming the handoff key: "Use customer_id in get_customer."

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 routes downstream detail lookups to get_customer and explains the active/deactivated default, so the agent knows which tool to pick for a single record. It does not mention create_customer as the alternative for adding a customer, but that is a low-ambiguity gap for a list tool.

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 and non-destructive, so the description's added value is the field-level payload (customer, date set, total, quote flag) and the paging contract via next_cursor. It does not discuss ordering, date-range limits, or whether a search narrows across both drafts and quotes.

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 with no filler; the definition and scope come first, then contents, then paging. The leading noun-phrase fragment is slightly awkward as an opener but the information density is high.

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 list tool with no output schema, the description names the returned fields and explains how items arrive here, which is what an agent needs to decide to call it. Missing filtering semantics and ordering, but nothing that would cause a wrong 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 coverage is 100%, so limit, cursor and search are already fully documented in the schema. The description only echoes the cursor paging ('Page with next_cursor') and says nothing about the search parameter matching customer name or email, so the baseline 3 applies.

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

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

States a specific resource (draft bookings and quotes) and its scope ('saved in the store, not yet booked'), which separates it from list_bookings in the sibling set. A fragment opener followed by a concrete enumeration of the Drafts page contents makes the purpose unmistakable.

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 explains provenance ('create_booking leaves a draft here') and clarifies the not-yet-booked state, which implicitly routes booked records to list_bookings. It never names list_bookings as the alternative explicitly, so the exclusion is inferred 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 grant read-only, idempotent, non-destructive status, so the description adds the genuinely non-obvious parts: newest-first ordering, the default date window, and the 'BookingKoala gives no total: next_cursor is set while a full page comes back' pagination quirk. That last clause is exactly the kind of behavior an agent would otherwise get wrong.

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 one-line purpose, then a dense second paragraph covering return fields, filters and pagination. Nearly every clause earns its place, though the 'BookingKoala gives no total' phrasing is slightly opaque and the field list packs a lot into one 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?

With no output schema, the description carries the return-value burden and does so by enumerating the fields returned (number, customer, type, status, total, paid, amount due, dates). Combined with ordering, pagination and routing hints, an agent has enough to call it and to read the result, though edge cases like empty results go 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?

Schema coverage is 100%, so the schema already documents limit, cursor, dates, pay_status enum, customer_id and search. The description restates the default date window and search fields but adds no syntax or format detail 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?

Opens with a specific verb+resource and scope: invoices for the whole store or a single customer, with payment status, totals and amount due. That scope statement alone lets an agent separate it from list_charges and list_drafts 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?

Spells out the three filter axes (customer, payment status, issue date range), the free-text search targets, and the default two-year-back/one-year-ahead window, which is real usage guidance. It also routes the invoice_id it returns to resend_invoice. It stops short of naming when a sibling like list_charges is the better call.

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), and the description adds genuinely useful behavior: results come in priority order, BookingKoala returns no total, and next_cursor is only set while a full page comes back. It also discloses the returned relationship shape (a team lists member provider ids; a provider lists teams it belongs to and leads).

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 resource and ordering stated up front, followed by return shape and then pagination caveat. The opening is a noun fragment rather than a clause, a small readability cost, but no sentence 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?

With no output schema and five optional parameters, the description carries the return-shape burden well: it explains mixed provider/team results, team membership fields, ordering, and the missing-total pagination quirk. Only the absence of any guidance on the search/status filters in prose keeps it below complete.

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/limit/cursor/search/status semantics are fully described in the schema itself. The description only echoes the 'type team returns teams only' behavior already in the enum description, adding marginal value, 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 (list) and resource (providers/teams) with scope: 'the store's service providers ... single providers and teams together'. It also disambiguates the 'team' mode and routes the agent to get_provider, so it is distinguishable from siblings 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?

Gives clear context for use ('as the Providers page lists them') and names the downstream consumer ('Use provider_id in get_provider and when assigning a booking'). It does not explicitly say when NOT to use it versus another listing tool, but no sibling lists providers, so the gap is minor.

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 substantial context beyond the annotations: arrival time and price are preserved, the response matches get_booking, an invalid date returns the allowed-date list, one-time bookings are rejected, and no notification is sent unless notify is true. It also discloses the fee-charging-store refusal, which is operationally important for a destructive mutation.

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 core action, then dense supporting facts in short clauses: behavior, error case, eligibility, notification, and fee exception. No sentence is redundant.

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

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

Although there is no output schema, the description explains the return value ('the booking comes back as get_booking shows it') and covers the significant failure modes and side effects. For a mutation tool with three parameters, nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the date constraint and the notify default ('Nobody is told unless notify is true'), but adds little syntax or meaning beyond what the schema already documents.

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 precise verb and resource ('Postpone a visit of a recurring booking') plus the scope restriction (must move to a later visit date in the schedule). This is clearly distinct from siblings like cancel_booking, create_booking, or get_booking, and an agent can select it without opening the schema.

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

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

Gives clear conditions and exclusions: only recurring bookings, only dates already in the schedule, and fee-charging stores must use the panel instead. It does not explicitly name sibling alternatives (e.g., cancel_booking or create_booking) for the cases it rejects, which keeps it just short of a 5.

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

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

Goes well beyond the annotations (readOnly=false, destructive=true, idempotent=false, openWorld=true): it discloses that the invoice record itself is unchanged, that CC and billing addresses also receive the email, that delivery is immediate, that attach_pdf follows the invoice setting, and that some resends fail with a warning whose message is carried in the error. That is exactly the side-effect and failure information an agent needs before invoking an irreversible external send.

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 core action, then ordered from mechanism to side effects to failure modes; every sentence carries information. It is on the dense side and repeats a few schema defaults (email default true, attach_pdf default), which is minor waste.

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 covers side effects, timing, and error behavior well, but says nothing about what a successful response contains. Given the tool's simplicity and the presence of annotations, this is a small residual gap rather than a blocking one.

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 each parameter already documents its default, so the description's restatement of email/sms/attach_pdf defaults adds little. The one genuine addition is that the email also reaches CC and billing addresses, but that is about effect rather than parameter meaning.

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

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

States a specific verb+resource+mechanism ('Send an invoice to its customer again by email, text or both') and anchors it to the 'Resend button' behavior. It also identifies the source of the input ('an existing invoice from list_invoices'), separating it from sibling tools like send_quote and list_invoices.

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 clear context for when to use it (re-sending an already-existing invoice rather than issuing a new one) and notes that certain invoices, such as void ones, will be rejected. It does not explicitly name when to prefer a sibling tool or state exclusions beyond the void example, so it falls short of full routing guidance.

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

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

Beyond annotations, the description discloses the side effects: it saves the recipient and expiry date on the quote, emails the store template or supplied subject/message, and sends immediately. It also explains the failure mode for non-quote drafts. These details are consistent with readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=true.

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 description is front-loaded with the core action and remains reasonably concise. It repeats some schema-provided defaults, which is useful but slightly redundant.

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

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

For a mutating, non-idempotent email action with full schema coverage and no output schema, the description covers the important context: what is sent, what is saved, defaults, preconditions, and immediate delivery. 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 100%, so the schema already documents every parameter and its default. The description restates the key defaults for email and expires_on but adds little parameter meaning beyond what is already 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?

The description states a specific verb and resource: email a saved quote to the customer with a booking link. It also identifies the source collection, list_drafts, and distinguishes sendable quotes from plain drafts, so an agent can tell exactly what this tool does.

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 clear precondition: only drafts saved as quotes can be sent, and a plain draft is refused before confirmation. It does not explicitly compare against all sibling tools such as resend_invoice, but the quote-specific context is strong.

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