qobrix_list_viewings

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses the return shape with pagination details, confirms only 'PropertyViewingViewing' include is verified, and describes the data linkage (property, contact, agent). However, it does not mention auth requirements or rate limits, which is a minor gap for a read-only listing tool.

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 information-dense and well-structured, starting with purpose, then lifecycle context, return format, include verification, and workflow patterns. It is longer than minimal but every sentence earns its place. There is slight redundancy with the schema's include description, but it does not detract significantly.

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 complex tool with 5 parameters and no output schema, the description provides return format, pagination, workflow patterns, and cross-tool references. It is complete enough for an agent to select and use correctly, though it could explicitly contrast with qobrix_search_viewings and qobrix_get_viewing for even better sibling differentiation.

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?

Input schema coverage is 100% and all 5 parameters have detailed descriptions. The description adds no parameter-specific meaning beyond what the schema already provides; its search example (created >= THIS_WEEK) is already covered by the schema's THIS_WEEK shortcut. Thus, the baseline of 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?

The description clearly states 'List property viewings (RESO ShowingAppointment)' and positions it as the 'Showing/Viewing Lifecycle tool', giving a specific verb+resource and a clear role. This distinguishes it from siblings like qobrix_search_viewings and qobrix_get_viewing, as it emphasizes the listing and lifecycle aspect.

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 provides explicit workflow patterns: 'This week's viewings: search with created >= THIS_WEEK', 'Property's showing history: qobrix_get_property...', 'Meetings linked to viewings: qobrix_list_meetings...'. These give concrete when-to-use guidance and name alternative tools, fulfilling the criteria for explicit usage guidelines.

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