adl_commit_input

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

With no annotations, the description carries the full burden and does well: it discloses single-use semantics ('consume... once'), target re-verification, per-chunk focus checks, a capability restriction (clipboard and control keys unavailable from text), the return payload (acknowledgement plus fresh PNG), and critically that failures may report partial execution. The main omission is permission/authorization context and what state remains after a partial failure.

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?

Two dense sentences, front-loaded with the core action and followed by behavioral caveats. Every clause carries information (restrictions, return value, failure mode) with no filler, though the jargon-heavy phrasing ('bounded chunk', 'released-input acknowledgement') costs some readability.

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 mutation tool with no annotations, no output schema, and 0% schema coverage, the description does substantial work on behavior, return value, and failure modes. It still leaves the two required parameters unexplained and omits any authorization or confirmation-lifecycle details an agent needs to call it safely.

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 description coverage is 0%, so the description must compensate. It does clarify value semantics indirectly ('click or enter plain text' implies value presence selects typing vs. clicking) and links confirmation_id to the consumed confirmation, but session_id is never explained and the 4096-char bound and optionality of value are left entirely to the schema.

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 names specific verbs and resources: consuming an interactive_desktop confirmation, reverifying the hovered/focused target, and clicking or entering plain text. This distinguishes it functionally from the other adl_* siblings, though it never names adl_prepare_input or adl_act explicitly, so the pairing/ordering relationship must be inferred.

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?

'Consume an interactive_desktop confirmation once' implies this must follow a prior confirmation-issuing step (presumably adl_prepare_input), which is useful implied usage. However, there is no explicit statement of when to use this vs. adl_act/adl_execute, no preconditions (e.g., what happens if the confirmation is expired or already consumed), and no exclusions.

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