opentable_modify

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

Annotations already flag mutation (destructiveHint=true, readOnlyHint=false), so the description's job is to add context beyond that, which it does: it discloses that confirmation_number is preserved while reservation_id/security_token may be regenerated, that dining_area_id mismatch is refused, and that without client elicitation a first call returns preview+confirmToken and only a repeat call commits. These are non-obvious behaviors the agent cannot infer from annotations, and nothing contradicts the annotated hints.

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

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

The description is dense (~5 sentences) and front-loaded with purpose and prerequisites, with every sentence carrying operational facts not in the schema. There is mild redundancy — the identity trio appears twice and dining_area_id's optionality appears in both schema and description — but nothing is padding.

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

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

Given 12 parameters, 8 required, and no output schema, the description covers the full call protocol: mandatory preview, user-confirmation flow with confirmToken fallback, the return shape (opentable_book shape plus was_modified), and the Listing-type exclusion. The only indirection is pointing to opentable_book's shape rather than spelling it out, which is acceptable given sibling 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?

With schema coverage at 67%, the description compensates by grouping restaurant_id + confirmation_number + security_token as the 'existing reservation's identity', explaining why modify_token is mandatory with no no-token path, and clarifying that dining_area_id is optional because the token already carries the resolved area, with mismatch refused. party_size, restaurant_id, and security_token still lack explicit schema descriptions, but the identity-grouping covers the latter two.

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 — 'Modify an existing OpenTable reservation in place' — and immediately anchors the flow by naming opentable_modify_preview as a mandatory prerequisite, separating this submission step from the preview sibling. The isModify:true/confirmation_number details further distinguish it from opentable_book and opentable_cancel in the sibling list.

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

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

States when to use (modifying an existing reservation) and explicitly when not: 'For Listing-type restaurants there's no slot to lock — agents should check opentable_get_restaurant.bookable first.' It mandates the precondition (fresh modify_token from opentable_modify_preview) and the human-confirmation requirement before the call, leaving little ambiguity about the correct call sequence.

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