list_open_messages

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that only unhandled inbound guest messages are included, and that messages are captured by the webhook receiver. It also notes the prerequisite that the webhook receiver must be running and subscribed, which is valuable behavioral context. However, it doesn't mention whether the list is sorted by arrival time or if pagination is used beyond the limit parameter, but these are minor gaps.

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 concise and well-structured. It opens with a clear summary, then details what each entry contains, and ends with a critical prerequisite. Each sentence serves a purpose: the first defines the tool's function, the second aids in understanding output and usage, and the third provides necessary operational context. No unnecessary words or repetition.

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 a single optional parameter, no annotations, and an output schema (which likely describes the entry fields), the description is quite complete. It explains the tool's purpose, the content of entries (including thread_id for use with send_message), and the prerequisite for it to work. It could be more explicit about the 'limit' parameter's effect, but this is minor and the output schema likely covers the return format. Overall, an agent has sufficient information to correctly call the tool.

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 schema description coverage is 0%, so the description must compensate for the undocumented 'limit' parameter. While the description does not explicitly describe 'limit', the context signal shows a single integer parameter with a default of 50, and the description mentions 'each entry includes...' implying a list. However, the description does not explicitly state that 'limit' controls the maximum number of entries returned, so there is a slight gap. Nonetheless, the description's focus on the inbox concept and the fact that limit is optional with a default provides enough context for an agent to infer its purpose.

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 the tool's purpose: listing inbound guest messages that are not yet handled, and explicitly frames it as the user's 'open messages' inbox. This distinguishes it from siblings like list_messages and mark_message_handled, as the focus is specifically on unhandled inbound messages from the webhook receiver.

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 specifies when to use this tool (to view unhandled inbound guest messages) and provides actionable guidance: it requires the webhook receiver to be running and subscribed, and refers to create_webhook_subscription with category 'message' for setup. It also implicitly contrasts with sibling tools like list_messages (which likely lists all messages) by focusing on the open inbox.

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