wait_app_logs

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 reveals the blocking nature and the in-memory pool, but lacks critical details such as timeout behavior (empty result vs. error), whether it returns single or multiple entries, and whether entries are consumed. This is a notable gap for a wait operation.

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 a single, front-loaded sentence with no redundant words. It efficiently conveys the core purpose and a key distinguishing feature (no cursor).

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 tool with no output schema and moderate complexity (5 optional parameters, blocking behavior), the description is incomplete. It does not explain what the tool returns when a match is found or on timeout, and the singular 'entry' potentially conflicts with the 'limit' parameter. Given this ambiguity, a score of 3 is appropriate.

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 adds minimal parameter-related value—it mentions 'matching entry' and 'no cursor' but does not elaborate on interaction between parameters (e.g., query vs. level) or return semantics. The schema already documents each parameter adequately.

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 action ('Wait for a new matching entry') and the resource ('current app run's in-memory DebugBridge log pool'). It distinguishes itself from sibling tools like read_app_logs by emphasizing the waiting and new-entry behavior, making its purpose unambiguous.

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 clear context: it is a blocking operation for new log entries, and explicitly notes that no cursor is required or returned, which guides usage. However, it does not explicitly name alternatives (e.g., read_app_logs) or state when not to use this tool, so it falls short of a full 5.

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