find_next_booking_for_resource

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

No annotations provided, so description carries full burden. It discloses that there is no server-side filter, so it fetches all booked resources and filters client-side, and warns about potential slowness. Describes fuzzy search logic for resource_name and inclusive from_date. Does not discuss error handling or side effects, but output schema covers return values.

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 extremely concise: three sentences covering purpose, parameters, and performance. Front-loaded with the core purpose, then parameter usage, then warning. No waste.

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

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

Given 3 parameters with no schema descriptions, the description adequately covers their usage and defaults. Output schema exists, so return values are handled. The performance warning adds important context. Minor gap: could clarify what 'next upcoming' means exactly (e.g., chronological order), but overall 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 coverage is 0%, so description must add meaning. It explains that resource_id and resource_name are alternatives (implied at least one needed), describes resource_name fuzzy search and exact match requirement, and provides from_date format (YYYY-MM-DD) and default. Does not specify if resource_id is a ChurchSuite ID or other, but provides enough context.

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

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

The description clearly states it finds the next upcoming booking for a specific resource, using verb 'Find' and resource 'booking'. It distinguishes from sibling 'find_next_booking_by_name' by focusing on resource rather than booking name, but does not explicitly differentiate from 'list_booked_resources' or 'list_bookings' which also deal with bookings.

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 clear guidelines: use either resource_id or resource_name, explains fuzzy search for resource_name and that it must match exactly one, and from_date format and default. Includes a performance warning about client-side filtering for large histories, which implicitly suggests caution. Does not explicitly mention alternatives among siblings.

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