laserfiche_task_update

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 explains the immediate-return behavior at 0, blocking until terminal/deadline at >0, the added 'timed_out' field, and that errors mirror underlying tools. It doesn't mention auth or rate limits, but for a poll/wait tool these are less critical; overall it gives a solid behavioral picture.

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, no wasted words, and the core purpose is front-loaded. Every sentence adds either behavioral distinction or usage routing. This is a model of efficient tool-description writing.

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 that an output schema exists (so return values are documented elsewhere), the description covers the essential behavioral context: the two modes, timeout semantics, and relationship to sibling tools. It might be slightly more explicit about when to prefer this over the individual task tools, but the description handles it well. Missing minor details like 'when not to use' are acceptable because the timeout mapping makes it obvious.

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 input schema already has 100% coverage with detailed descriptions for all three parameters, so the baseline is 3. The description adds minimal extra meaning—mostly restating that timeout_seconds=0 returns immediately and poll_interval_seconds is ignored at 0, which is already in the schema. It does usefully synthesize the two modes, but doesn't go beyond the schema significantly.

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 as 'Check or wait on an async operation' and explicitly distinguishes it from sibling tools by mapping timeout_seconds=0 to get_task_status semantics and >0 to wait_for_task semantics. This makes it easy for an agent to know exactly what this tool does and how it differs from laserfiche_task_get_status and laserfiche_task_wait.

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 usage guidance: use timeout_seconds=0 for single-poll behavior or >0 for blocking wait, and names the alternative tools whose semantics it mirrors. It also notes 'Same payloads and errors as the underlying tools,' covering error handling expectations. This is excellent when-to-use and when-not-to-use guidance.

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