library_context_flush

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

The description explains the core behavior (waiting for embedding/indexing) and mentions the 'durable outbox' and 'watermark', which give some insight into side effects. However, it does not mention timeout behavior (despite a timeout_seconds parameter), potential failures, or what happens if the operation is interrupted. It is consistent with the idempotent annotation, but lack of detail on blocking semantics limits transparency.

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, concise sentence with no redundant wording. It is well-structured and front-loaded with the primary action ('Wait until'), making it easy to parse. No other tools are referenced, keeping it focused.

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?

The description is too terse for the apparent complexity. It does not define key terms like 'durable outbox' or 'recorded watermark', nor does it mention return values, errors, or timeout behavior (which is directly relevant given the timeout_seconds parameter). Given the existence of many sibling context operations, this level of detail is insufficient for an agent to know when and how to use it effectively.

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 description adds no information about the three parameters. The schema already provides a description for 'collection' and obvious defaults for the others, but 'session_id' and especially 'timeout_seconds' lack explanation (e.g., what does timeout do? what is a session id?). With low schema coverage (33%), the description should compensate but does not, so parameter understanding is left incomplete.

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 action (wait until) and the resource (the thread's durable outbox) with a specific outcome (embedded and indexed through its recorded watermark). It distinguishes itself from siblings by indicating a blocking/waiting operation, though the exact meaning of 'flush' is not directly explained.

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 no guidance on when to use this tool versus the many sibling context operations (e.g., prepare, commit, release). It does not mention scenarios such as needing to ensure persistence or consistency, nor does it state the tool is appropriate after mutations. The usage context is entirely absent.

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