SimpleDock

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

Annotations already declare idempotent=true, destructiveHint=false and openWorldHint=false, and the description adds the non-obvious behavior that existing appointments are NOT cancelled and that the response counts them for follow-up. That is exactly the consequence an agent needs before calling a mutation, and it goes beyond what the structured fields convey.

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 the action and scope, followed by the side-effect warning. No filler or 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?

For a 3-param mutation with no output schema, the description covers the key effect (appointments preserved, counted in response) and timezone handling. The remaining gap is that the 'reason' parameter and any permission requirements are unaddressed, but nothing critical to calling it correctly is missing.

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

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

Schema description coverage is 0% (only the nested date item format is annotated), and the description adds no parameter detail: no format for dates, no meaning for locationId, and the optional 'reason' parameter is never mentioned at all. With 3 parameters and essentially no schema documentation, the description fails to compensate.

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: 'Close the whole location on specific dates', with scope qualifiers (whole location, local timezone). It is clearly distinguishable in practice from the inverse sibling remove_closure and from appointment-level tools, but it never names an alternative to route against.

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 use contexts ('holidays, shutdowns') that tell an agent when this applies, and the local-timezone note constrains interpretation. It stops short of any when-not condition or explicit pointer to remove_closure for undoing a closure.

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, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds the useful side-effect note that approval can also move the start time, but it does not disclose permission requirements, whether the customer is notified, or what happens to conflicting bookings.

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 zero filler; the core action comes first and the optional behavior is appended compactly.

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 two-parameter mutation with no output schema, the definition covers the core action and the optional time change. It omits operational context such as required permissions, error/conflict behavior, and post-approval effects, leaving gaps an agent may need.

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 50%: startTime carries an ISO 8601 description while appointmentId has none. The description contributes the semantic that startTime is optional and repurposes the appointment's start time, but says nothing about the appointmentId format or source.

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 ('Approve') and resource ('appointment') plus a precondition ('pending'), which implicitly separates it from reject_appointment, cancel_appointment, and reschedule_appointment. It does not explicitly name those siblings, so an agent must infer the boundary from the verb alone.

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 word 'pending' implies the applicable state, so usage is implied rather than stated. There is no explicit when-not guidance (e.g. 'for non-pending appointments use set_appointment_status') and no mention of the reschedule_appointment alternative.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the description adds nothing on safety, reversibility, idempotency or side effects. For a destructive mutation it should note what cancelling does to the appointment record, notifications, and whether it can be undone.

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?

Minimal two-word sentence, front-loaded and not padded, but it is under-specified rather than concise. It earns its place only as a bare label, adding nothing an agent could not infer from the name.

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?

A destructive, open-world mutation with no output schema, 0% param coverage and no annotations carrying behavioral detail needs more than 'Cancel an appointment.' Nothing about permissions, side effects, or the identifier is conveyed.

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 0% and the description never mentions appointmentId or its format. With one required, undocumented parameter the description should at least name it; it does not compensate for the coverage gap.

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 (cancel) and resource (appointment), which is clear. However, with many siblings that also mutate appointments (reschedule_appointment, set_appointment_status, reject_appointment, delete_*), the description does nothing to distinguish cancel from reject or status changes.

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

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

No guidance on when to cancel versus the alternatives (reschedule_appointment, set_appointment_status, reject_appointment). Two words give the agent no context to choose this tool over clearly related siblings.

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 write (readOnlyHint=false), non-destructive, and idempotent. The description adds genuine behavioral context on top: it does not cancel and does not start dwell time, and it is limited to confirmed appointments. It doesn't say what happens when the appointment isn't confirmed (error vs ignored), which keeps it from a 5.

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

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

Three tight sentences, front-loaded with the core action, followed by the confirmed-only constraint and the two routing exclusions. Every sentence earns its place with no 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?

For a write tool with no output schema and low schema coverage, the description covers the operation, scope constraint, and sibling routing adequately. It could still state behavior on unconfirmed appointments or the effect of estimatedDelay when status is ON_TRACK, but the essentials are present.

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

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

Schema description coverage is only 33%, so the description must compensate. It clarifies the status semantics (ON_TRACK vs RUNNING_LATE) and that estimatedDelay is minutes, matching the schema enum/description, but leaves appointmentId and the delay's requiredness unexplained. Partial compensation only.

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 (record) and resource (driver's check-in update on a confirmed appointment) with the exact status values. It explicitly distinguishes itself from cancel_appointment and mark_arrived, so an agent can select it without opening sibling schemas.

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

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

Gives explicit when-to-use (confirmed appointments only), when-not (never cancels, doesn't start dwell time), and names the correct sibling to use instead in each excluded case (cancel_appointment, mark_arrived). Nothing is left to inference.

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

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

Annotations already flag this as non-idempotent and destructive, but the description adds critical behavior they cannot express: the secret is disclosed exactly once ("returned only now; store it"), it is revocable via Settings → API, and creation is gated on a confirmed owner email. These are the details an agent needs to avoid leaking or mis-timing the key.

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 clauses ordered by importance: what it is, the one-time-secret caveat, where it lives/is revoked, then the prerequisite. No filler and nothing repeated from 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?

With no output schema, the description correctly covers the essential return semantics (key shown once). The remaining gap is scope defaults for the optional `scopes` parameter, which neither the description nor the schema addresses.

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 50%: `name` is documented with an example in the schema, but `scopes` has no description anywhere. The description says nothing about parameters, so it does not compensate for the gap, and it also leaves unanswered what scopes are granted when the optional `scopes` array is omitted.

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 ("Create a long-lived API key") and even the key format prefix (sd_live_…). No sibling tool in the list deals with API keys, so the resource alone discriminates it from the appointment/location/webhook tools.

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

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

Gives a clear use case ("for scripts and clients that can't refresh OAuth tokens") and a precondition ("Needs the owner's email confirmed first"). It stops short of naming an alternative mechanism (e.g. the OAuth flow) explicitly, so it is context without full when/when-not routing.

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=false, idempotentHint=false and openWorldHint=true, so the mutation profile is covered; the description adds the non-obvious failure semantics (off-slot times rejected with a conflict error, inactive appointment types returning not_found). It omits auth/permission requirements and any side effects such as notifications or double-booking protection, so it is good but not exhaustive.

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

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

Three tight sentences, front-loaded with the action, then the precondition, then the error cases. No filler and 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?

For a 14-parameter write tool with no output schema and near-zero schema documentation, the description covers the critical booking precondition and failure modes but leaves the bulk of the parameter surface and the return payload (e.g. created appointment id/status) undocumented. Adequate to call it correctly on the happy path, incomplete for the full surface.

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

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

Schema description coverage is only 7% (just startTime = "ISO 8601 datetime"), so the description must carry the load for 13 other parameters. It adds real meaning for startTime by constraining it to values from get_availability, but the 13 remaining fields (driverName, companyName, customFields nested object, poReference, etc.) get no explanation of format, optionality or effect in either the schema or the description.

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?

"Book a confirmed appointment" names a specific verb (book), resource (appointment), and resulting state (confirmed), which separates it from the approval/cancellation siblings like approve_appointment and cancel_appointment. An agent knows this is the creation entry point rather than a status-change tool.

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

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

It states a hard precondition that routes the agent to a sibling workflow: startTime must be a slot previously returned by get_availability for that type and date. That is clear context plus an implied pre-step, though it never states when NOT to use it (e.g. reschedule for existing appointments) or what to do if no slot is offered.

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 the safety profile (not read-only, not idempotent, not destructive, closed world). The description adds that the type governs booking behavior (length, load, direction, notice, buffers), which is useful framing, but says nothing about permission requirements, duplicate-name handling, or what a successful creation returns.

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 well-formed sentence that front-loads the verb and resource, then the configurable dimensions. No filler, though it is a bit list-heavy and could state the required fields more directly.

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

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

For an 8-parameter create tool with no output schema, the description conveys the domain purpose and the major configurable dimensions. The gaps are the two undocumented params (locationId, name) and success/failure behavior, but the core of what an agent needs to select and call it is present.

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 38%, so the description has to pull weight. It enumerates field categories that map to durationMinutes, loadType, direction, minimumNoticeMinutes, and the two buffer parameters, but never mentions locationId or name, and adds no units, defaults, or constraint context beyond what the schema already shows.

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 concrete verb and resource ("Add an appointment type") and even explains the domain concept — what a carrier picks when booking. It is clearly distinguishable from siblings like create_appointment or create_door, though it does not directly contrast with update_appointment_type.

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: you call this when setting up an appointment type for a location. There is no explicit guidance on when to use this versus update_appointment_type, nor any prerequisite (e.g., location must exist) beyond the schema's required locationId.

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 the write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds real behavioral context beyond that: where the answer is stored (customFields.{key}), the default key derivation, and that the key is immutable after creation. It stops short of documenting permissions, error behavior, or duplicate handling.

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 action, then three dense sentences covering key semantics, the DROPDOWN constraint, and isReference meaning. No filler; 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?

For a creation tool with no output schema, the description covers the important storage semantics and field requirements, and annotations carry the safety profile. It is reasonably complete, though it omits return values and failure/permission behavior.

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 11% across 9 parameters, so the description carries most of the burden. It meaningfully explains key (default + immutability), isReference, and the DROPDOWN/options dependency, but leaves label, helpText, required, locationId, and appointmentTypeId undocumented in both schema and description.

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 ('Add a question to an appointment type's booking form') and identifies the resource precisely, distinguishing it from siblings like delete_booking_question, update_booking_question, and create_appointment_type. The '(Pro)' qualifier further scopes it.

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?

Provides an implicit trigger (adding a question to a booking form) and a field-type precondition ('DROPDOWN needs options'), but never states when to prefer this over update_booking_question or list_booking_questions, or any prerequisites like plan/permission requirements.

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 this is a non-destructive create that is not idempotent. The description adds real behavioral context beyond them: default type coverage (all types, including future ones), default hours inherited from the location, and the mode-dependent behavior of limits. It omits failure behavior and permission requirements, but the domain semantics are well 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?

Three sentences, front-loaded with the core action, and every sentence carries distinct information (defaults, alternatives, mode caveat). Dense domain jargon (assignDoors, capacity mode) slightly reduces immediate readability 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?

For a 4-parameter create with no output schema, the description covers defaults, sibling routing, and mode-conditional semantics, and the annotations carry the safety profile. The remaining gap is what the call returns, which is minor given no output schema is declared.

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

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

Schema description coverage is only 25%, so the description must carry weight, and it does: it explains that appointmentTypeIds defaults to all types, that weeklyHours is optional and otherwise inherits the location's hours, and points to update_door for the alternative. It still doesn't describe the weeklyHours window shape, but the nested schema fields cover the format.

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 precise verb+resource ('Add a dock door') and immediately differentiates itself from siblings by naming update_door (modify limits/hours) and set_up_location (add types and doors together). An agent can pick this over the alternatives 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?

It gives explicit routing conditions: use update_door to change types/hours, set_up_location to add types and doors together by name, and it states that the door may be created before any types exist. It also flags a when-it-applies caveat (limits only matter under assignDoors, not in capacity mode), which is exactly the 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 already declare this is a non-read-only, non-destructive, non-idempotent mutation, and the description adds meaningful post-conditions beyond that: the location starts empty and requires set_up_location to become bookable, plus a payment_required failure mode on the Free plan. It does not describe auth requirements or what the response contains, keeping it short of 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?

Three tight sentences, front-loaded with the action, then the post-condition, then the constraint. No filler and no repetition 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?

Covers the workflow follow-up and the plan/error constraint well for a mutation tool with no output schema, but leaves the majority of input parameters unexplained. Adequate for the high-level flow, incomplete on the inputs the agent must supply.

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

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

Schema description coverage is only 17% (just the timezone IANA hint), and the description adds nothing about name, address, city, state, or zip. With five undocumented parameters the description should compensate for the coverage gap and does not.

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 ('Add a facility'), and it distinguishes itself from the similarly named set_up_location by framing that as the follow-up step. It does not contrast with update_location_details, but the create-vs-configure distinction is legible.

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 the agent: call this first, then follow up with set_up_location to build out hours, appointment types, and doors. It also names the plan gate ('Free plan allows one location; more need Pro (payment_required)'), which is real pre-call guidance. Missing only an explicit 'use update_location_details to change an existing location' counterpoint.

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 behavior beyond the annotations (which only say write/not-idempotent/open-world/not-destructive): a test event is POSTed first and the webhook is persisted only on a 2xx response, non-Slack payloads are signed with an X-SimpleDock-Signature header, and signingSecret is exposed only at creation time. The one-time-secret disclosure and the conditional-save behavior are exactly the kind of facts an agent cannot get from annotations.

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 dense sentences, each carrying distinct payload: purpose/plan, save semantics, signature verification, and input constraints. Nothing is restated from the schema or annotations, and the most decision-relevant facts (test event, signingSecret returned only now) come early.

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 mutation tool with no output schema, it covers creation semantics, security, failure mode (non-2xx = not saved) and input constraints well, and even names the one returned value the caller must capture. It stops short of describing the response payload shape beyond signingSecret or what happens on retries/duplicate URLs, which leaves a small 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 description coverage is only 20%, so the description must compensate, and it does: it explains the https:// requirement for url, the required hosts for ZAPIER/SLACK kinds, and the 'empty = every event / every location' defaults for eventTypes and locationIds. Only label (maxLength 80) is undocumented, and the schema already constrains it.

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: 'Send appointment events to a URL (Pro).' No sibling tool in the list touches webhooks, so there is zero ambiguity about which tool to reach for. The parenthetical '(Pro)' also flags the plan gate, which no sibling states.

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 preconditions and constraints rather than a vague 'use this to add a webhook': https-only URLs, host restrictions per kind, and empty-array semantics. It does not state when *not* to use it or name an alternative, but no alternative webhook tool exists among the siblings, 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds non-obvious consequence detail beyond that: existing answers persist on past appointments but lose their label. It doesn't mention permission requirements or error behavior for a missing/foreign questionId, keeping it short of 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?

Two tight sentences, no filler, with the destructive nature front-loaded and the alternative guidance placed last where it is most actionable.

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 two-parameter destructive tool with annotations covering the safety profile and no output schema, the description is nearly sufficient. The remaining gap is the absence of any parameter documentation or failure-mode guidance.

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

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

Schema description coverage is 0% and the description never mentions locationId or questionId, so neither parameter's meaning, format, or scoping role is documented anywhere. The names are largely self-explanatory, but the description does nothing to compensate for the coverage gap.

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 ('Remove a booking question') and immediately scopes it as permanent ('for good'), which clearly separates it from its add_/update_/list_booking_question siblings.

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 names the alternative ('set isActive to false with update_booking_question instead') and the condition that should drive the agent there (wanting to keep existing answers). This is a textbook when-to-use-vs-alternative statement.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds real behavioral context on top: which capabilities are blocked until confirmation (appointment emails/texts, directory listing, search indexing, invites, API keys) and the lifecycle consequence that unconfirmed agent-created accounts are deleted at deletesAt. That kind of consequence disclosure is exactly what annotations cannot convey.

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 core answer (confirmation status) and using a compact parenthetical list for the gated features. Slightly dense and the trailing booking-page-URL sentence reads as an add-on, 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?

There is no output schema, so the description carries the return-value burden and does so by enumerating the statuses and gated features it reports. It stops short of describing the actual response shape or field names, and does not explain why booking page URLs surface here rather than from get_booking_page.

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 tool takes zero parameters, so the baseline of 4 applies; there is no parameter syntax to explain. The description correctly implies the account is resolved from context rather than an argument.

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 precisely what the tool reports: email confirmation state, the features gated on confirmation, deletion timing, and location booking page URLs. It is a specific resource-status report rather than a tautology, but it never distinguishes itself from lookalike siblings such as get_booking_page or get_location_setup, so an agent must infer the boundary. The appended "Also lists each location's booking page URL" clause slightly blurs the single purpose.

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: the note about agent-created unconfirmed accounts being deleted at deletesAt suggests checking status after provisioning. It never says when to call this versus verify_email, resend_verification_email, or get_booking_page, which are the obvious adjacent actions. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds genuinely new constraints: a 30-day default window and a hard 366-day maximum range. It also discloses the return shape (counts by status and type), though it omits anything about permissions or how zero-result ranges behave.

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, both load-bearing: the first defines output scope, the second defines temporal constraints. Nothing is repeated from the title, schema, or annotations.

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 returns and does so adequately (counts by status and type). For a three-parameter read tool with full annotation coverage, this is close to complete; only error/permission behavior is left unstated.

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

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

Schema coverage is 67% (from/to documented as ISO 8601, locationId undocumented). The description compensates by clarifying that results are scoped per location and by adding the default and maximum range semantics that the schema does not express for from/to.

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 (per-location appointment summary with counts by status and type) plus the date-range scope, which distinguishes it from list_appointments and get_appointment. It does not name a sibling explicitly, so sibling routing 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?

The aggregation framing (counts by status and type, per location) implicitly signals this is for reporting rather than record retrieval, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative such as list_appointments.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured fields. The description adds nothing beyond that: no not-found behavior, no permission requirements, no return shape guidance.

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 zero waste, characteristic of a simple lookup tool. It is nearly at the limit of useful brevity, but it does not waste any words.

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

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

The tool is a one-parameter read with rich annotations and no output schema, so the essentials are covered. Still, an agent gets no signal about failure modes (invalid or unknown id) or what the fetched appointment contains.

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

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

Schema description coverage is 0%, so the schema contributes only the parameter name and type. The phrase "by id" vaguely maps to appointmentId and confirms it is a single identifier lookup, but it adds no format, source, or uniqueness detail beyond the name itself.

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

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

The description names a specific verb and resource ("Fetch a single appointment by id"), which distinguishes it from list_appointments and create_appointment by implication. However, it never explicitly contrasts with the closest siblings, leaving that inference to the reader.

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 statement of when to use this tool versus alternatives such as list_appointments or the update/cancel variants. The word "single" implies one-record lookup, but nothing states prerequisites or exclusions.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lowered. The description adds only the 'bookable' qualifier and repeats the date format; it says nothing about timezone handling, whether results are cached, or what a slot contains. No contradiction with annotations.

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 constrained inputs stated immediately; no filler, no 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?

There is no output schema, so describing the shape of a returned slot would have been useful, and the timezone semantics of 'date' plus any result limits are unaddressed. The description is minimally adequate for a three-required-parameter lookup but leaves an agent guessing about the return payload.

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

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

Schema description coverage is only 33%, leaving locationId and appointmentTypeId undocumented in the schema, so the description must compensate. It does list all three required filters in role order and confirms the date format, but 'for a location, appointment type, and date' largely restates the parameter names rather than adding format or constraint detail (e.g., ID source, timezone of the date).

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 ('bookable time slots') scoped by three named inputs, so an agent can distinguish it from list_appointments or get_appointment. It does not explicitly name a sibling it competes with, but the 'bookable time slots' framing is clearly narrower than the appointment-listing tools.

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 offers no when-to-use guidance, no mention that this is the discovery step preceding create_appointment, and no exclusions versus the many appointment-related siblings. The use case is only implied by the phrasing 'bookable time slots'.

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), so the description is free to add substance — and it does, explaining that acceptingBookings is false until weekly hours, an active appointment type, and an active door exist, and that problems reports what to fix. That is meaningful behavioral context about the returned state, though it stops short of the full response 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?

Two dense sentences with the resource identified first and the readiness conditions second; every clause carries information and nothing 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?

With no output schema, the description usefully explains the key returned fields (acceptingBookings, problems) and the prerequisites that drive them, plus the URL format. What it omits is any explanation of the locationId input it requires, though for a one-param read tool the omission is minor.

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

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

Schema description coverage is 0% for the single locationId parameter, and the description never explains the parameter, describing only a /book/{slug} link. It does not compensate for the missing schema descriptions, but with a single obvious required string id the ambiguity is limited.

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

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

The description names the concrete resource (the public booking link carriers use at /book/{slug}) and the specific state it reports (whether it can take bookings). That is a specific verb+resource an agent can act on, though it never explicitly contrasts itself with the near sibling get_location_setup.

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: an agent can infer this is the tool for inspecting booking-page readiness, and the conditions listed clarify when acceptingBookings flips true. However there is no explicit 'use this when / use X instead' guidance or any routing against get_location_setup.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds non-obvious return scope: 'including inactive ones' for appointment types, doors' 'own type limits and own hours,' and 'upcoming closures' — details an agent cannot get from the annotations or schema. It is a single-read aggregate ('in one call'), which is useful behavioral context.

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 one dense sentence, but it is front-loaded with the payoff ('Everything about how a location is set up, in one call') before the semicolon-delimited inventory. The enumerated groups all earn their place. The run-on density keeps it just short of 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?

There is no output schema, so the description must carry the return-value burden — and it does, listing each block of data returned. Combined with annotations covering safety and usage guidance covering timing, an agent has what it needs to call this correctly.

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

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

Schema description coverage is 0% and the description never mentions the locationId parameter by name or specifies its format (ID vs slug). The single required locationId is semantically self-evident from the tool name and the phrase 'how a location is set up,' so the risk is low, but the description does not compensate for the coverage gap as the rules require for low-coverage schemas.

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+resource (get/read the full setup of a location) and enumerates exactly which data is returned: name/address/timezone, scheduling settings, weekly hours, appointment types, doors, and closures. This clearly separates it from list-shaped siblings such as list_locations or list_doors. It stops short of naming an alternative sibling, so it lands at 4 rather than 5.

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

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

It gives two concrete invocation contexts: 'Read this before changing setup' and 'when diagnosing missing times.' That is real when-to-use guidance rather than implication. However, it names no explicit alternative (e.g. get_availability or list_doors) or exclusion, so it is not a full 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 declare mutation/destructive/openWorld traits; the description goes further by disclosing the failure mode ('past that the invite is payment_required') and a gating condition (owner email must be verified). It omits idempotency behavior (duplicate invites) and whether the invite expires, which the non-idempotent hint makes relevant.

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 compact sentences, front-loaded with the action, then roles, then prerequisites, then plan limits. No filler or restatement of the name.

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 two-parameter mutation with no output schema, the description covers roles, prerequisites, plan limits and the payment_required outcome, which is what an agent needs to call it correctly. Return/confirmation behavior and duplicate-invite handling are the only gaps.

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 0%, so the description carries the burden, and it does explain all three role enum values with their actual permissions (ADMIN includes billing, SCHEDULER books appointments, DOCK_STAFF marks trucks). The email parameter is self-evident; only format/validation details are 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?

States a specific verb and resource ('Email someone an invitation to join the organization') and no sibling tool competes for this action, so an agent can route to it unambiguously.

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

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

Gives a hard prerequisite ('Needs the owner's email confirmed first') and a plan constraint, which tells the agent when the call will succeed. It does not name alternatives or state when not to use it, but the prerequisites are explicit and actionable.

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/destructiveHint=false, so the safety profile is covered. The description adds context annotations do not carry: results are capped at `limit` rows and continuation is via `nextCursor`. It does not say what happens when filters match nothing or whether the cursor expires.

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, zero filler, and the filtering capability is front-loaded ahead of the return/pagination detail. Every clause carries information an agent needs.

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

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

With no output schema, the description does its job by sketching the return shape (bounded rows plus a `nextCursor`). For a 6-parameter read tool with annotations fully covering the safety profile, that is close to sufficient; only the undocumented `limit`/`status`/`locationId` semantics remain thin.

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 50%: `from`/`to` and `cursor` are documented inline, while `limit`, `status`, and `locationId` are bare. The description partly compensates by revealing that location, status and start-time range are filters and that `limit`/`cursor` drive paging, but it gives no format for the time range or bounds for `limit`.

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

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

States a specific verb+resource ("List appointments") and immediately names the supported filters, which is enough to separate it from the single-record sibling `get_appointment` and from the mutation siblings (`create_appointment`, `cancel_appointment`, `reschedule_appointment`). It never explicitly names those siblings, so it stops short of a 5.

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

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

The word "optionally" makes the filters discretionary, implying this is the broad enumeration tool, but the description never says when to prefer it over `get_appointment` or when to avoid a full listing. 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 declare this a safe, idempotent read. The description adds real context beyond that: only active types are returned, each carries custom field definitions, and those fields are binding constraints on bookings. It does not mention pagination or ordering, which keeps it short of 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?

Three short sentences, front-loaded with the action and scoping, followed by the dependency rationale and the alternative source. Every sentence 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?

Despite no output schema, the description tells the agent what comes back (types plus their custom field definitions) and how that output feeds downstream calls. For a single-parameter read tool this is sufficient to invoke correctly.

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

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

Schema description coverage is 0% and the single locationId parameter is undocumented in the schema. The phrase 'a location offers' implies locationId scopes the result, but no format or ID-source detail is given, so the description only partially compensates.

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 ('List the appointment types a location offers') and narrows the scope to active types with custom field definitions. This cleanly distinguishes it from get_location_setup, which holds the inactive ones.

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 prescribes ordering ('Call this first') and names why: create_appointment and get_availability both require an appointmentTypeId, and bookings must satisfy required fields. It also routes the agent elsewhere for inactive types, so both when-to-use and where-else are covered.

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 read-only, idempotent, non-destructive nature of the tool. The description adds useful behavioral context beyond that: it discloses that the data is returned in form order and includes which built-in fields each type hides or requires. It does not mention pagination or response shape, but that is a minor gap given the annotation coverage.

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 no filler. The core scope is front-loaded, and the second sentence adds distinct content about built-in field visibility rules.

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 list tool with no output schema, the description communicates the shape of the returned data well. However, it leaves gaps around when to use the tool, how the required locationId is used, and how the optional appointmentTypeId affects the result, which are important for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It implies appointmentTypeId filters by type but says nothing about the required locationId or whether appointmentTypeId is optional and what happens when it is omitted. The two parameters remain largely undocumented.

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 (booking questions) with additional scope: extra questions carriers answer when booking, per appointment type, in form order. It also distinguishes content by mentioning built-in field visibility rules, so an agent can tell it apart from the sibling create/update/delete_booking_question tools.

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 'per appointment type', but the description never explicitly says when to call this versus other list tools or what happens if appointmentTypeId is omitted. No alternatives or prerequisites are named, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context of its own — no pagination, ordering, auth requirements, or what constitutes a 'door' — so it earns little credit beyond what annotations provide.

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 no filler or repetition; the scope qualifier is placed immediately after the verb. It is efficient, though its brevity shades into under-specification rather than disciplined concision.

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?

This is a simple single-parameter read tool whose annotations cover the safety profile and whose sibling set makes the CRUD context clear, so the description is minimally adequate. It still omits what fields a door record contains and whether the result is paginated, which would matter to an agent planning a workflow.

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

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

Schema description coverage is 0% for locationId, so the description must compensate. Saying 'at a location' loosely maps the parameter to a location identifier, giving the agent a workable inference, but it provides no format, ID type, or validation guidance.

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 a specific resource (dock doors at a location), so an agent immediately knows this is a read of door records scoped to one site. It does not differentiate itself from siblings like create_door or update_door, though the verb makes the distinction largely self-evident.

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 phrase 'at a location' implies the call is scoped to one site, but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. Nothing tells the agent when this is preferable to get_location_setup or other location-related siblings.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description does add useful scoping context — enumeration is unfiltered ('all') and confined to the organization — but says nothing about result size, ordering, or paging.

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 sentence with no filler, and the resource plus scope are front-loaded. Nothing in it is redundant with the title beyond what is necessary to state scope.

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 zero-parameter, fully annotated read-only list tool, the description covers purpose, scope, and absence of filtering, which is nearly everything an agent needs. The minor remaining gap is the shape of the returned list (ordering, pagination), which the absence of an output schema leaves undocumented.

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 tool takes zero parameters, establishing the baseline of 4. The description is consistent with the empty schema: 'all ... in the organization' confirms there is no filtering argument, matching the schema's closure (additionalProperties: false).

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 pairs the verb 'List' with a specific resource ('dock locations') and a scope ('in the organization'), which distinguishes it from list_doors, list_appointment_types, and the other list_* siblings. It does not, however, explicitly contrast itself with retrieval tools like get_location_setup or list_doors, so an agent gets a clear purpose but no sibling routing.

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 when-to-use guidance, no prerequisites, and no named alternative. The only implicit signal is 'List all', which suggests enumeration but leaves the agent to infer when this is preferable to get_location_setup or get_availability.

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

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

Annotations already declare readOnly=false, idempotent=true and destructive=false, so the description does not need to restate safety. It usefully adds side-effect context the annotations lack: the arrival starts a dwell-time clock that ends only when the appointment is marked COMPLETED. It does not mention permission requirements or behavior when the appointment is already arrived, which keeps this short of 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?

Three sentences, each doing distinct work: definition, lifecycle/side effect plus undo, and sibling disambiguation. Front-loaded with the core action and zero filler.

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

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

For a two-parameter mutation tool with no output schema, the description covers the action, its side effect on dwell time, the reversal path, and the nearest sibling. What is missing is edge-case behavior (e.g. re-arriving an already-arrived appointment) and any authorization context.

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

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

Schema description coverage is only 50% (appointmentId is undocumented), so the description carries extra burden. It explains that arrived: false undoes a mistaken arrival, adding intent and rationale beyond the schema's terse 'false clears the arrival', though the appointmentId parameter remains unexplained.

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

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

States a specific verb and resource ('Record that a truck has physically arrived at the dock') and grounds it with a concrete example utterance. It also explicitly differentiates itself from the sibling check_in_appointment, so an agent can select correctly 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?

Gives the trigger condition (physical arrival at dock), the undo path (arrived: false), and an explicit exclusion: 'Not the same as check_in_appointment, which records the driver's own on-track or running-late update before arrival.' When-to-use, when-not-to-use, and the alternative are all present.

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, idempotentHint=true, openWorldHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the useful precondition that the appointment must be pending and that the reason is optional, but says nothing about side effects such as notifying the invitee or whether the state change is recoverable.

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 no filler. It is lean, though the brevity leaves little room for the guidance a mutation tool arguably needs.

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

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

For a destructive, non-read-only mutation with two undocumented parameters and no output schema, the description is thin. It omits what rejection actually does to the appointment and to the other party, which an agent needs before committing to an irreversible state change.

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

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

Schema description coverage is 0%, so the description must carry the semantic load. It only clarifies that 'reason' is optional; appointmentId and the format/acceptable content of reason are left entirely undocumented.

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 (reject) and resource (appointment) with the qualifier 'pending', so the operation is clear. It does not, however, distinguish it from close siblings like cancel_appointment or set_appointment_status, which an agent could easily confuse it with.

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 only usage signal is the word 'pending', which implies the precondition but is never stated as a rule. There is no when-to-use guidance and no mention of cancel_appointment or set_appointment_status as alternatives for different scenarios.

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, idempotentHint=true, readOnlyHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond the verb — no note on what reopening affects (existing appointments/bookings) or error behavior — which is acceptable but unenriched.

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?

One sentence, front-loaded with the action and resource, with the id-source parenthetical appended. Nothing extraneous.

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 low-complexity, 2-required-param tool with no output schema and annotations covering safety, the description covers purpose and the non-obvious id source. The only gap is locationId, whose meaning is left entirely to the schema.

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

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

Schema description coverage is 0%, so the description must compensate. It explains where closureId comes from (get_location_setup's upcomingClosures), adding real value for one of the two params, but says nothing about locationId's meaning or required format.

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 (reopen) and resource (a closure, addressed by id), which is clear enough for an agent to act. It also points to a related sibling (get_location_setup) for the id source, though it doesn't explicitly contrast with the inverse tool add_closed_dates.

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 operational context: the closure is reopened by id and those ids come from get_location_setup's upcomingClosures. No explicit when-not guidance or named alternative (e.g. add_closed_dates for the inverse), so it stops 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?

Annotations already declare destructive=true, idempotent=true, and openWorld=true, so the safety profile is partly covered. The description adds real value by disclosing the validation rule (new time must come from get_availability, own slot excluded) and the failure mode ('otherwise conflict'), which the annotations do not convey.

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 with the core action front-loaded and the constraint second. The parenthetical about the appointment's own slot is dense but earns its place by preventing a real error.

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 3-param mutation tool with no output schema, annotations cover safety/idempotency and the description covers the key validation and conflict behavior. Missing are auth/permission requirements and confirmation that the returned state is the updated appointment, but nothing critical to invoking it correctly is absent.

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% (only startTime is documented as ISO 8601). The description clarifies that doorId is optional and re-frames startTime as a movable start, which partially compensates, but appointmentId is never explained and the schema still carries most of the burden poorly.

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 (move/reschedule) and resource (a confirmed appointment) plus the two fields being changed (start time, door). It does not explicitly distinguish itself from the overlapping sibling update_appointment_details, but the 'confirmed appointment' scope and the get_availability linkage make the intent clear.

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: the agent can infer this is for changing the time/door of an already-confirmed appointment, and the description states the validity rule for the new time. It never says when to prefer this over update_appointment_details or cancel_appointment, and gives no explicit exclusions for non-confirmed appointments.

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, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: that prior links and codes are invalidated by the call, and a rate limit ('a few per hour'). That is useful disclosure beyond the structured fields, though the rate limit is vague and no auth requirements are mentioned.

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

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

Three short sentences, zero filler, and the core action is front-loaded ahead of the side-effect and rate-limit caveats. Every sentence 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?

For a parameterless mutation with no output schema, the description covers the action, the destructive side effect on existing tokens, and the rate constraint. Combined with annotations that carry the idempotency and openness flags, 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?

The tool takes zero parameters (100% coverage of an empty schema), so the baseline is 4. There is nothing for the description to disambiguate, and it correctly does not invent parameters.

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 combination ('Send the owner a new confirmation email') plus what the email contains ('link and code'). It is largely distinguishable from the sibling verify_email, though the description never names that counterpart explicitly to reinforce the resend-vs-verify distinction.

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 the verb 'resend' plus the warning that earlier links and codes stop working, which hints at when a caller would reach for it. However, there is no explicit statement of when to use this versus verify_email or any precondition (e.g. email must be unverified), so guidance stays at the implied level.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), but the description adds auth scope requirements that aren't in the structured data: COMPLETED/NO_SHOW need appointments:receive while CONFIRMED needs appointments:write. It does not explain side effects or what a destructive transition implies, so it stops short of 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?

Three compact sentences, front-loaded with the core action and enum, then permissions, then the sibling routing. Every clause carries distinct information with no filler.

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

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

Covers action, valid values, authorization scopes, and the cancel alternative, which is sufficient for a 2-parameter mutation with no output schema. It omits any statement about reversibility or side effects of the transition, which would be the remaining 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 description coverage is 0%, but the description restates the enum values already present in the schema and adds real meaning by mapping each status to its required permission. appointmentId is left entirely undocumented in both schema and description, so compensation for the coverage gap is partial.

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 ('Transition an appointment's status') and enumerates the exact target states, so its scope is unambiguous. It distinguishes itself from cancel_appointment by name, which is the nearest sibling that could otherwise be confused with a status change.

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 cancellation to cancel_appointment, giving one clear alternative for the most confusable operation. However, it does not address the neighboring state-changing siblings (approve_appointment, reject_appointment, check_in_appointment, mark_arrived), so an agent still has to infer whether those overlap with the CONFIRMED/COMPLETED transitions.

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 annotations' idempotent/destructive hints, it discloses transactional atomicity ('a bad entry changes nothing'), upsert-by-name semantics including reactivation of inactive entries, that omitted items are untouched, and the return payload (setup plus bookingPage.problems). This is substantial behavioral context the structured fields do not provide.

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?

Five dense sentences, purpose front-loaded, no filler. It is on the long side, but each sentence carries distinct operational information (atomicity, optionality, matching rules, referential naming, return 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?

For a 5-parameter nested composite tool with no output schema, it covers purpose, atomicity, upsert semantics, and return shape well. It omits authorization requirements and does not warn which inputs can destroy data despite destructiveHint=true (e.g. an empty windows list closing a day), and does not address an unknown locationId.

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

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

Schema description coverage is only 20%, so the description must carry more weight. It usefully explains name-based matching and the 'doors refer to types by name, so you don't need ids' relationship, plus omission semantics for types and hours, but says nothing about the settings sub-fields (assignDoors, doorCapacity, slotsPerHour, dwellTrackingEnabled, appointmentApprovalRequired) or the type fields like buffers and minimumNoticeMinutes.

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?

Names a specific verb ('Set up') plus the resource and enumerates the exact scope: scheduling settings, weekly hours, appointment types, and doors. The phrase 'in one call' distinguishes it from the sibling singletons (update_location_settings, set_weekly_hours, create_appointment_type, create_door) without the agent needing to open 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?

'Set up a facility in one call' combined with 'Every part is optional' and 'repeating the call is safe' tells the agent when this composite tool is the right choice over the granular siblings. It never explicitly names an alternative tool or a when-not-to-use condition, so it stops short of the top band.

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, idempotentHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds genuinely useful behavior beyond that: partial-replace semantics per day, empty-list-closes-a-day, and the rule that a booking must fit entirely inside one window, which determines how windows behave.

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 core replace semantics followed by the slot-building consequence. The worked 08:00–10:00 / 10:30–12:30 example is compact and directly actionable, and nothing 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?

For a destructive mutation with no output schema, the description covers the essential semantics: partial update scope, closure behavior, and window/booking interaction. It omits what happens to already-booked appointments when hours are replaced, which an agent would want given destructiveHint=true.

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 and nested objects involved, the description must carry the load, and it does: it explains the semantics of `days` (leaving one out leaves it unchanged) and `windows` (empty = closed), plus the booking-fit constraint that governs window values. It lacks detail on locationId and on how openTime/closeTime pairs relate to each other, keeping it short of a 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?

The first clause gives a precise verb+resource+scope: 'Replace a location's hours for the listed days.' An agent can distinguish this from siblings like add_closed_dates (closures) and update_location_settings 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?

The description clearly states the operating context: omitted days are unchanged and an empty windows list closes a day, plus a worked example of how to produce fixed slots. It does not name explicit alternative tools (e.g. add_closed_dates for one-off closures), so it stops short of full when/when-not routing.

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=false, idempotent=true, destructive=true, covering the safety profile. The description adds genuine PATCH semantics ('omitted fields are left unchanged') and a scope limit, but says nothing about what the destructiveHint means in practice or what happens to concurrently edited 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 sentences, front-loaded with the core action and scope, then the PATCH behavior. No filler; 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?

For a 10-parameter mutation with 0% schema description coverage and no output schema, the description is too thin. It omits per-parameter meaning, permission/state prerequisites, and any note on the destructiveHint, so an agent lacks enough to call it confidently.

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 0% across 10 parameters, so the description carries the full documentation burden. It only groups fields into carrier/driver/reference categories and does not map most parameters (notes, contactEmail, contactPhone, poReference) or explain formats, leaving half the inputs undocumented.

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 (Edit) plus resource scope (appointment's carrier/driver/reference fields) with a strong qualifier '(no time change)' that separates it from reschedule_appointment. It does not name siblings explicitly, but the scope boundary is clear enough for an agent to pick it 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?

The '(no time change)' clause implies that time modifications belong to reschedule_appointment, and 'omitted fields are left unchanged' clarifies the patch usage. However, no alternative tool is named and no prerequisites (e.g. permission or state requirements) are stated, leaving usage largely implied.

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=false, idempotentHint=true and destructiveHint=true, so the description's added value is the PATCH semantic that omitted fields are preserved and the deactivation path that avoids deleting history. It does not note the mild tension with destructiveHint=true or mention auth/rate-limit behavior, keeping it out of the top tier.

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 short sentences, zero filler, with the core action and the mutation semantics front-loaded before the deactivation tip. Every sentence adds information the structured fields do not carry.

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 with no output schema and low schema coverage, the description covers patch behavior and deactivation but says nothing about the enumerated fields (loadType, direction), the duration/buffer constraints, or what a successful update returns. Adequate but clearly incomplete for the tool's complexity.

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

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

Schema description coverage is only 30% across 10 parameters, so the description must compensate and it largely does not: only isActive is explained. Fields such as name, loadType, direction, durationMinutes and the two IDs are left entirely to the schema, which documents almost none of them.

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 ('Edit an appointment type'), which distinguishes it from the create and list siblings on the same resource. It does not explicitly contrast itself with update_appointment_details or other update_* tools, so sibling differentiation is only partial.

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 one concrete usage decision (set isActive to false instead of deleting) and implies patch-style usage via 'omitted fields are left unchanged'. However it never names an alternative tool or states prerequisites/permissions, so the guidance is implied rather than explicit.

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, idempotentHint=true, and readOnlyHint=false. The description adds meaningful context the annotations cannot: PATCH semantics, that questionId is immutable, and that isActive:false hides the question from the form while preserving past answers — clarifying that this particular "destructive" action is actually a soft-hide.

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, each earning its place, with the core edit semantics front-loaded before the isActive nuance. No filler.

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

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

For a mutation tool with a destructive hint and no output schema, the description covers patch behavior and the key isActive side effect well. But with 9 parameters at 0% schema coverage, it is not complete enough — the effect of changing fieldType (e.g., breaking existing answers) and the role of options/isReference are unaddressed.

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

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

Schema description coverage is 0% across 9 parameters, so the description must compensate. It only explains isActive (and the immutability of questionId); label, options, helpText, required, fieldType, and isReference are left entirely to the bare schema, leaving most parameter behavior undocumented.

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 ("Edit a booking question") and flags the Pro tier. It is clearly distinguishable from create_booking_question, delete_booking_question, and list_booking_questions by the update verb, though it never names these siblings directly.

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?

"Omitted fields are left unchanged" establishes partial-update (PATCH) semantics, which tells the agent to send only changed fields. However, there is no explicit guidance on when to choose this over delete_booking_question or create_booking_question, or on prerequisites/alternatives.

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 annotations (destructiveHint=true, idempotentHint=true), the description discloses meaningful behavior: partial-update semantics (omitted fields unchanged), that leaving days out of weeklyHours closes them for this door, that weeklyHours is clipped to the location's hours, that null reverts to location hours, and that isActive:false removes the door from service. This adds real destructive-effect context the annotations only flag generically.

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 but purposeful parameter semantics. The long compound sentence about weeklyHours is somewhat run-on, but each clause carries distinct information (clipping, omitted days, null revert) that 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?

For a mutation tool with annotations but no output schema and six parameters, the description covers partial-update behavior, key parameter semantics, and side effects adequately. It stops short of mentioning permission requirements or any response/return behavior.

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

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

Schema description coverage is only 17%, so the description carries the burden and does so for the non-obvious parameters: appointmentTypeIds ([] = every type), weeklyHours (clipping and null-to-revert semantics), and isActive. It does not address name or the two required IDs, though those are largely self-explanatory.

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 sentence gives a specific verb and resource ("Edit a dock door"), which clearly separates it from siblings like create_door, list_doors, and the location-level update tools. An agent can identify the target entity and operation 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?

Usage is only implied by the verb "Edit" and the note that omitted fields are left unchanged. There is no explicit statement of when to use this tool versus set_weekly_hours, update_location_settings, or create_door, nor any prerequisites or exclusions.

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, readOnlyHint=false), so the bar is lower. The description adds real beyond-annotation context: partial-update semantics (omitted fields unchanged), conflict behavior for duplicate slugs, and the destructive consequence that changing a slug breaks already-sent carrier links.

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

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

Three tight sentences, front-loaded with the editable fields, then partial-update semantics, then the slug constraint. Every sentence carries distinct information with no filler.

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

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

For a mutation tool whose annotations already carry the safety profile and with no output schema, the description covers update semantics, a key constraint (slug format/conflict), and a destructive side effect. The main residual gap is the undocumented city/zip/state parameters.

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

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

With only 25% schema coverage, the description must compensate. It richly documents slug semantics (3+ lowercase letters/numbers/hyphens, conflict on reuse, link breakage) and names name/address/timezone/README fields, but omits zip, city, and state entirely, leaving those undocumented in both schema and description.

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 (Edit) and resource (a location's name, address, timezone, booking-page URL). An agent can tell it apart from create_location and update_location_settings. It does not explicitly differentiate itself from the closely named sibling update_location_settings, which keeps it from a 5.

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

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

Usage is implied by the field list and the PATCH-style note that omitted fields are left unchanged, giving useful invocation context. However, there is no explicit guidance on when to use this versus update_location_settings or set_up_location, and no when-not 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description usefully adds partial-update semantics ('Omitted fields are left unchanged'), which tempers the destructive warning, but it doesn't explain what can be destroyed, permission requirements, or side effects of toggling flags like dwellTrackingEnabled.

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

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

Two short sentences, zero filler, with the core action front-loaded and the partial-update rule immediately following. Every sentence 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?

For a 6-parameter mutation tool with no output schema, the description covers the essential partial-update contract but omits scope boundaries versus update_location_details and any behavioral notes on the toggled scheduling flags. Annotations carry the safety profile, so the gap is moderate rather than severe.

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 83%, so the schema already documents nearly every parameter (including the enum values for slotsPerHour and the assignDoors/doorCapacity interaction). The description adds no per-parameter detail beyond what the schema provides, which meets the baseline but doesn't exceed it.

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 (Change) and resource (a location's scheduling settings), which is clear enough to act on. It does not, however, differentiate itself from the sibling update_location_details, so an agent must infer the boundary between the two.

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 guidance, no prerequisites, and no mention of the closely related update_location_details sibling. The only implied usage comes from the 'scheduling settings' framing, which is thin for a tool competing with several update_* siblings.

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 idempotentHint=true and destructiveHint=true, and the description adds real context on top: it discloses the clearing convention ('empty string clears it'), the per-field effects (carrier confirmation emails, driver check-in texts), and partial-update semantics for omitted fields. It does not contradict the destructive/idempotent hints, though it never frames the operation as a 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?

Four tight sentences, front-loaded with the scope statement, then one sentence per field, then the partial-update rule. Every sentence carries information, though the field-by-field cadence reads slightly list-like rather than prioritized.

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 the input semantics and the partial-update contract well. It omits what happens on an invalid locationId and whether changes are scoped to a team, but for a settings-mutation tool supported by idempotent/destructive annotations this is close to sufficient.

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

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

Schema description coverage is 0%, so the description carries the full load, and it does so for all three optional parameters: notifyEmail's purpose plus its empty-string sentinel, emailNotificationsEnabled's on/off meaning, and smsCheckInEnabled's driver-facing effect. Only locationId is left unexplained, which is acceptable for an obvious required key.

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 with a clear scope: 'Change who hears about bookings at a location.' That is unambiguous and far more informative than the title restatement. It does not explicitly differentiate itself from the sibling update_location_settings, which is the only missing piece for a 5.

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

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

The description explains per-field behavior but never says when to reach for this tool versus the related update_location_settings or update_location_details siblings, nor does it state conditions or prerequisites. 'Omitted fields are left unchanged' is a useful mechanic, but it is usage mechanics, not when-to-use 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?

Goes beyond the annotations by disclosing a failure/lockout threshold ('after five wrong codes the email stops accepting codes') and an operational constraint (must obtain the code from the user rather than guessing). Annotations already cover idempotency and non-destructiveness, and the described behavior is consistent with idempotentHint=true. It doesn't state what a successful confirmation unlocks or whether the code is single-use, which keeps it short of 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?

Three tight sentences with zero padding; the core action and its required input come first, followed by the handling instruction and then the failure escape hatch. Every clause carries information the agent needs.

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

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

For a one-parameter confirmation tool with full annotation coverage, the description supplies action, input source, lockout behavior, and the alternative path. The only gap is the absence of any statement about the result of success (no output schema exists to cover it), which is minor but not fully closed.

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 format ('Six digits, e.g. 042917') is already supplied structurally, giving a baseline of 3. The description adds genuine meaning beyond the schema by identifying the provenance of the value – it is the code emailed to the owner and is obtained by asking the user – which tells the agent where to source the parameter.

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 ('Confirm the owner's email') plus the artifact required ('the six-digit code SimpleDock emailed them'), so the agent knows exactly what this does. It is clearly distinct from the similarly named sibling resend_verification_email, which it explicitly points to for the alternate 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 when-to-use instruction ('ask the user for the code they received'), an explicit prohibition ('never guess one'), and names the alternative tool and the exact condition that selects it ('after five wrong codes ... use resend_verification_email'). Nothing about routing is left to inference.

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