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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and repeat-call profile is covered structurally. The description adds only the target of the mutation ('Saved Restaurants list') and says nothing about auth requirements, behavior when the restaurant is already saved, or error cases.

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 efficient sentence with the action front-loaded and no filler. It is well-formed but so terse that it forgoes easy opportunities to add routing or parameter context.

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 mutation with rich annotations and no output schema, the minimum needed to call it correctly is nearly present, but the origin and valid range of restaurant_id and the result of a duplicate add are left unexplained.

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 gives no information about restaurant_id — not its format, not where to source it (e.g. from opentable_search_restaurants or opentable_get_restaurant). For a tool whose only parameter is an opaque numeric ID, the description should compensate 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?

The description states a specific verb ('Add') and resource ('a restaurant') plus the destination ('user's Saved Restaurants list'), which cleanly separates it from opentable_remove_favorite and opentable_list_favorites. It stops short of naming those siblings, so differentiation is implicit rather than explicit.

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

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

There is no guidance on when to use this tool versus alternatives such as opentable_remove_favorite, nor any prerequisite (e.g. obtaining a valid restaurant_id via opentable_search_restaurants). Usage is only inferable from the tool name.

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 destructive/non-idempotent/open-world, and the description adds substantial context beyond them: the two-phase confirmation flow (preview + confirmToken vs elicitation), auto-fetch of user profile, the returned confirmation_number + security_token that are required to cancel, refusal behavior when booking_token is missing, and the surfaced cancellation policy. This is exactly the extra behavioral detail annotations cannot carry.

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 primary action and its input dependencies, then flows into confirmation, returns, and edge cases in a sensible order. It is dense and long, but nearly every clause (token expiry, Listing restaurants, database_region caveat) carries actionable information rather than filler.

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

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

No output schema exists, yet the description states the return payload (confirmation_number + security_token and that they are needed for cancel), documents the confirmation handshake across both client modes, and covers the non-slot Listing path. For a 12-param destructive tool, nothing an agent needs to invoke 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 coverage is 83% (baseline 3), but the description adds workflow meaning: it explains why dining_area_id is optional (auto-resolved so find_slots → book needs no get_restaurant), when booking_token becomes mandatory, and how experience_ids/experience_id interact with preview. Some points duplicate the schema descriptions (confirmToken, database_region), keeping it from 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?

Opens with a specific verb+resource ('Book an OpenTable reservation') and immediately distinguishes itself from siblings by naming the upstream tools (opentable_find_slots, opentable_book_preview) and the failure modes that route to them. An agent can tell this apart from opentable_modify/opentable_cancel without reading any schema.

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

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

Gives explicit when-to-use mechanics: requires a fresh slot_hash + reservation_token, warns they expire within minutes so find_slots must be called just before, and states dining_area_id may be omitted because it auto-resolves. It also names preconditions for CC-required slots (booking_token from opentable_book_preview) and the Listing-type edge case (check opentable_get_restaurant.bookable instead).

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, destructiveHint=false, openWorldHint=true, idempotentHint=false. The description adds critical behavioral context beyond annotations: holds the slot for ~60-90s, token is short-lived, safe to call for standard slots, refuses charge-at-booking cases, and cannot fetch slots for Listing-type restaurants.

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 purpose, then dense but valuable details. Every sentence carries actionable information. Slightly paragraph-heavy; could be structured with bullets, but no wasted 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?

Given 10 parameters and no output schema, the description covers return content (cancellation policy, payment card, booking_token), timing constraints, dependencies, failure modes, and alternatives. An agent has all it needs to call correctly.

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

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

Schema description coverage is 80%, so baseline is 3. The description adds meaning for the experience_id/experience_ids parameters by tying them to find_slots booking_type=experience_mandatory and the Experience slot-lock routing. It also clarifies the cross-tool token flow, though it does not document every parameter, so not 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?

States a specific verb and resource: 'Preview an OpenTable booking BEFORE committing.' Explicitly names the sibling it differs from (opentable_book) and describes the token handoff. An agent can distinguish it without opening 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?

Provides explicit when-to-use conditions (required for CC-required slots, safe for standard slots), when-not-to-use cases (Listing-type restaurants, deposit/prepaid experiences), and names alternatives (opentable_book, opentable_get_restaurant.bookable, phone/URL). No inference needed.

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 destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it documents the two-phase confirmation flow (preview + confirmToken, only a repeat call proceeds), the elicitation-capable client path, the MCP_CONFIRM_MODE dependency, and the cross-restaurant refusal rule. That is the operational reality an agent must plan around for a destructive call.

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

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

Purpose is front-loaded and nearly every clause carries information, but the second half is a single long run-on sentence packing confirmation flow, refusal rule, and prompt contents together. It remains readable, though a break or two would improve scannability.

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 takes responsibility for describing the return behavior — the phase-1 'confirmation-required' preview and confirmToken — which it does. Combined with the schema's confirmToken and database_region notes, an agent has everything needed to call this destructive tool correctly.

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

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

Schema description coverage is only 40%, so the description must compensate — and it does for restaurant_id, confirmation_number, and security_token by stating they all originate from opentable_list_reservations or opentable_book. The remaining detail (confirmToken lifecycle, database_region shard caveat) is carried in the schema descriptions themselves, so the split leaves no parameter truly 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?

Opens with a specific verb+resource ('Cancel an OpenTable reservation') that an agent can distinguish immediately from sibling mutators like opentable_modify or opentable_book. It also states the three required inputs and their provenance, so the agent knows exactly what this tool needs.

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 parameter sourcing to opentable_list_reservations or opentable_book, and spells out the confirmation precondition and the one case where the call is refused (confirmation_number belonging to a different restaurant). The when-to-use and when-not-to-use conditions are both 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?

Goes well beyond the readOnly/openWorld annotations: token expiry pressure, that book auto-resolves the dining area, why the numeric dining-area id isn't in the availability response, and a specific error message with a concrete retry recipe. This is exactly the operational context annotations cannot carry.

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

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

Front-loads the core action, then layers workflow and troubleshooting detail. It is dense and on the long side, with a parenthetical about OpenTable internals that borders on tangential, but nearly every sentence carries actionable 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 read-only listing tool with no output schema, it covers the return payload (reservation_token, slot attributes, types), cross-tool handoff, expiry semantics, region caveats via schema, and a known failure mode with recovery steps. 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 67%, so date, time, view, and database_region are already documented in the schema. The description clarifies output-side vocabulary (slot attributes and type values) and cross-references reservation_token/slot_hash, but adds little about the two undocumented parameters (restaurant_id, party_size) beyond their names. Baseline 3 is appropriate.

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 available reservation slots') plus scope ('at a specific OpenTable restaurant for a date + party size'). It is clearly distinguishable from siblings like opentable_book and opentable_get_restaurant, and even names the sibling it feeds into.

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

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

Gives clear context for the workflow: use the reservation_token with opentable_book, book promptly because tokens expire, and skip a separate opentable_get_restaurant call. It doesn't explicitly frame when to reach for this versus a hypothetical alternate availability tool, but the routing is largely unambiguous.

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 readOnlyHint and openWorldHint, yet the description adds substantial behavior: menus return bounded pages of whole items, external menu_url links are returned but never fetched, and prices are OpenTable's published values rather than a live quote. It also enumerates the status outcomes (available, menu_not_found, external_only, not_available), which no annotation conveys.

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

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

Dense but every clause carries information, and the caveats about external links and non-live prices are valuable. It is slightly mis-front-loaded: the opening sentence covers a pagination edge case rather than stating the tool's core purpose.

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

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

For a read-only lookup with no output schema, the description supplies the return envelope (available_menus, status), the field inventory, pagination contract, and identifier flexibility. There is no output schema, yet the return shape is still communicated, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds footing by stating that pagination must reuse the same menu_name/section_name filters and that view=full without paging is uncapped, which the schema does not say. The rest (menu_name case-insensitive matching, section_name selecting one section) largely restates the schema.

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

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

States a specific verb+resource (get published menus for a restaurant) and enumerates the payload (sections, dishes, prices, variations, currency, provider, timestamps). It further distinguishes itself from siblings by noting it accepts the same identifier as opentable_get_restaurant, so an agent can route without opening a schema.

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

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

Gives clear operational context: how to resume via pagination.next_offset with the same filters, when section_name/menu_name should be supplied, and that view=full without paging is uncapped. It never explicitly contrasts with a sibling (e.g., find_slots for availability), but the usage conditions are well specified.

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 and openWorldHint=true, so the safety profile is covered. The description adds useful value by explicitly guaranteeing that 'Payment and credit-card details are never exposed', which is a privacy constraint not conveyed by the 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?

Two tightly written sentences with zero waste. The field list is front-loaded, and the privacy note is a valuable addition 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 simple read-only profile getter with no output schema, the description lists the returned fields and adds a key privacy guarantee. Combined with rich annotations and full schema coverage, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, and the single 'view' parameter is fully documented in the schema, including its enum values and effects. The description adds no additional meaning about the parameter; baseline 3 is appropriate when the schema does all the work.

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 ('Get') and resource ('authenticated OpenTable user's profile'), then enumerates the returned fields (name, email, phones, loyalty points and tier, home metro, member-since date). This clearly distinguishes it from all sibling tools, which handle reservations, favorites, restaurants, menus, and health.

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 does not provide any when-to-use guidance, prerequisites, or alternatives. It states what the tool fetches but never says when an agent should call it versus another tool or in what workflow context it is appropriate.

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 and openWorldHint, so safety is covered. The description adds real behavioral value: it discloses the availability_token field is used internally for booking and explains id-resolution behavior, including legacy /{slug} venues. Auth and rate-limit behavior remain unstated.

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

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

Front-loads purpose before the input-format detail, and every sentence carries information. The second sentence is dense but earns its place by disambiguating id forms; minor redundancy with the schema description keeps it from 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?

With no output schema, the description usefully enumerates the returned fields, and the id-resolution paragraph covers the main calling ambiguity. Nothing critical is missing, though permissions or failure modes for unresolvable ids are not mentioned.

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

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

Schema coverage is 100% and the restaurant_id schema description already documents the accepted id/slug/path/URL forms and legacy resolution, so the description largely repeats structured data. The view parameter (compact/full) is left to the schema. Baseline 3 is appropriate.

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 (get) and resource (single OpenTable restaurant) and enumerates the exact payload returned (cuisine, price band, address, hours, features, rating, availability_token). This clearly distinguishes it from siblings like opentable_get_menu and opentable_search_restaurants.

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?

Establishes the workflow context by naming opentable_search_restaurants as the source of the URL to pass in, and explains that any id form resolves. However, it does not explicitly state when to prefer this over siblings such as opentable_get_menu or opentable_get_profile.

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 readOnly, openWorld, and idempotent, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: what the diagnostics reveal (bridge role, port, version, extension link states, round-trip time), the plain-English hint taxonomy, and the explicit statement that booking is never probed. It doesn't describe timeouts or error-return behavior in detail, keeping it at a 4.

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 progressively discloses return contents, hints, and constraints. It's a long sentence chain but each clause adds information (what is returned, what the hint distinguishes, what is explicitly not tested). Slight redundancy in enumerating link states and hint categories.

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 0-parameter, no-output-schema diagnostic tool, the description is complete: it explains the mechanism, the returned diagnostics, the hint taxonomy, the read-only/no-auth constraint, and the explicit non-goals (no booking probing). An agent has everything needed to call it correctly and interpret results.

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?

Zero parameters, so the baseline is 4; however the description compensates by describing exactly what the tool returns (diagnostic fields and hint categories), giving the agent full understanding of the call's shape without a schema.

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

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

The description states a specific action (round-trips /robots.txt through ContextMint Bridge for diagnostics) and clearly distinguishes itself from every sibling tool, which all concern reservations, restaurants, menus, or favorites. An agent can immediately see this is a connectivity/diagnostic tool, not a data-fetch 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?

The description explains the scope clearly: 'Tests bridge transport only' and explicitly rules out booking ('booking is never probed'), plus notes that search/menus/availability are only reported from observed real reads. It doesn't explicitly name which sibling to use for actual data, but the exclusions give strong routing signal.

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 and openWorldHint, but the description adds a genuinely useful behavioral caveat — restaurant_id can be null 'when OpenTable omits it' — which an agent must handle. It does not mention result limits, ordering, or pagination.

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 verb+resource followed by the field list in one dense sentence; every clause carries information. The nested parentheses around the id caveat make it slightly harder to parse but nothing is wasted.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating fields and flagging the null-id case. Missing only secondary details like list length, ordering, or behavior when the user has no favorites.

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

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

Schema coverage is 100% and the single 'view' parameter is fully documented in the schema, including the compact/full semantics. The description never references 'view', so it adds nothing beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('List the user's saved restaurants from OpenTable (Saved Restaurants list)') and enumerates the returned fields. The parenthetical scoping to the Saved Restaurants list separates it from opentable_search_restaurants without needing 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 implied rather than stated: the description notes the id is 'the same id opentable_get_restaurant, opentable_find_slots and opentable_remove_favorite take,' which routes the agent onward but never says when to call this instead of search_restaurants or add_favorite. No explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral context beyond them: the default scope resolution and the fact that each entry carries the security_token required to cancel or modify, which is a downstream workflow hint. It omits pagination, result caps, and any auth/permission nuance.

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, no filler, front-loaded with the core action and followed by the default and the token handoff. 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 read-only list tool with annotations covering safety and no output schema, the description covers purpose, default scoping, and the key returned artifact (security_token). Missing only return-order/pagination details, which are minor for this shape.

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

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

Schema coverage is only 50%: 'view' is fully documented in the schema, but 'scope' carries no schema description at all. The description compensates for that gap by stating the default value and the meaningful enum alternatives, which is more than the schema alone conveys.

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 authenticated user's OpenTable reservations") with clear scope. It is unambiguously distinct from the action siblings (book, modify, cancel) and from the favorites/search tools, so an agent can route to it from the name plus first sentence 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?

It sets the default behavior ("Defaults to upcoming") and explains how to broaden with scope="past" or scope="all", which is exactly the decision an agent must make. It stops short of naming an alternative tool or an explicit when-not-to-use condition, but no sibling competes for this retrieval job.

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 mark this as non-idempotent and destructive, but the description adds substantial context beyond them: the confirmation prompt flow, the two-step confirmToken fallback for non-elicitation clients, the CC re-hold, cancellation-policy drift, and that confirmation_number is preserved while reservation_id/security_token may be regenerated.

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

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

Front-loaded with purpose and requirements, and nearly every sentence carries actionable detail. However it is a single dense paragraph mixing API internals ('Submits /dapi/booking/make-reservation') with agent-facing guidance, which costs some readability.

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

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

For a 12-param mutation tool with no output schema, the description covers the return contract (same shape as opentable_book plus was_modified: true), the confirmation semantics, and the preview prerequisite. Nothing an agent needs to invoke 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 67%, and the description supplements it by grouping the identity triad (restaurant_id + confirmation_number + security_token), reinforcing modify_token as required with no no-token path, and explaining that dining_area_id is optional and refused on mismatch. It adds little for the still-undocumented restaurant_id/party_size fields, so not a full 5.

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

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

States a specific verb and resource ('Modify an existing OpenTable reservation in place') and immediately distinguishes it from the preview step and the other siblings. An agent can tell this apart from opentable_book / opentable_modify_preview without opening any schema.

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

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

Explicitly declares the precondition (a fresh modify_token from opentable_modify_preview is mandatory, with the reason) and routes the agent via named siblings. It also flags the Listing-type restaurant edge case and points at opentable_get_restaurant.bookable as the check.

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 (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) cover the safety profile, and the description goes well beyond them: it discloses the return payload (new cancellation_policy, CC re-hold details, modify_token), the internal /booking/details URL construction with isModify=true, and the Listing-type failure mode. It is a preview that yields a token rather than performing the change, which is clearly conveyed.

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

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

Purpose and the identity-vs-new-slot split are front-loaded, then constraints (dining_area_id optional, required-before-modify, Listing-type block) follow. It is dense and slightly repetitive on provenance, but nearly every sentence carries operational information and nothing is filler.

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

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

For a 12-parameter, no-output-schema tool, the description supplies what is otherwise missing: the returned artifacts (cancellation_policy, CC re-hold, modify_token), the workflow position (must precede opentable_modify), and the non-NA database_region caveat is documented in the schema. Nothing an agent needs to call this 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 67%, and the description adds real meaning beyond it: it groups the params conceptually (existing identity vs NEW slot args) and explains origin/staleness ('from a fresh opentable_find_slots call'). It also reinforces dining_area_id as optional with auto-resolution. Some of this (slot_hash/reservation_token provenance) is already in the schema, so it is additive rather than filling a large 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+resource ('Preview a MODIFICATION to an existing OpenTable reservation') and explicitly distinguishes itself from siblings opentable_book_preview ('Mirrors opentable_book_preview, but...') and opentable_modify ('modify_token that opentable_modify consumes'). An agent can tell why this preview exists versus a plain booking preview without opening any schema.

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

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

Gives explicit when-to-use ('REQUIRED before opentable_modify — no shortcut path') and where each input originates (identity from opentable_list_reservations or opentable_book, new slot args from a fresh opentable_find_slots call). Also names a when-not case: Listing-type restaurants can't proceed and you should check opentable_get_restaurant.bookable first.

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, destructiveHint=false, and openWorldHint=true, covering the mutation and repeat-call profile. The description adds nothing beyond the name's implication: it does not state what happens if the restaurant is not saved, whether auth is required, or how to confirm success.

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 no wasted 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?

For a simple one-parameter removal with annotations covering safety and idempotency, the description states the essential purpose. However, it omits the error/edge behavior when the item is not favorited and any success signal, which leaves gaps for an agent deciding whether the call succeeded.

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 single parameter is undocumented, so the description carries the burden. It only implies that 'a restaurant' is identified, without explaining that restaurant_id comes from search/get_restaurant results or giving any format detail. The self-explanatory parameter name keeps this from being worse than a bare minimum.

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

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

The description gives a specific verb ('Remove') and resource ('restaurant from the user's Saved Restaurants list'), making the operation unambiguous. It does not explicitly name the sibling it contrasts with (opentable_add_favorite), but the verb alone is distinctive enough to route an agent 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?

There is no guidance on when to use this versus alternatives, nor any precondition (e.g., the restaurant must already be in the list). The agent must infer usage entirely from the name and description.

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 and openWorldHint, so safety is covered. The description adds valuable behavioral context by enumerating the returned fields (cuisine, neighborhood, price band, rating, description, URL) and the key negative — no bookable slot tokens. It omits pagination/rate-limit behavior, so not a 5.

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

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

Two sentences, front-loaded with purpose, then return contents, then the sibling routing caveat. 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?

No output schema exists, so the description reasonably carries the return-field burden via its enumeration. It covers the key exclusion (slots) and most return fields, though a full field list or pagination note would be more complete.

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

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

Schema coverage is 78%, high enough that the schema documents most parameters (date, term, time, view, location, metro_id, party_size). The description adds no parameter syntax beyond what the schema provides, including the important note that date affects ranking but not returned slots. Baseline 3 is appropriate.

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

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

States a specific verb (Search) and resource (OpenTable restaurants), and lists what comes back. It explicitly distinguishes itself from opentable_find_slots by declaring it does NOT return bookable slot tokens.

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

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

Gives explicit routing: use opentable_find_slots for a specific venue to check availability, implying this tool is for discovery. The exclusion of slots is stated directly, so the agent knows which sibling to pick.

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