fill_form

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

With no annotations at all, the description carries the full burden, and it does disclose two genuinely useful traits: it aborts at the first failed field and performs a single UI-tree dump rather than one per field. It does not say whether a partial failure prevents submission, whether already-filled fields persist after the abort, or anything about permissions/visibility requirements, so the failure-handling picture stays incomplete.

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?

Three short sentences, the batch capability and the submit option are front-loaded, and each clause carries distinct information (capability, failure behavior, performance characteristic). Nothing is repeated or padded.

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?

An output schema exists, so return values need not be explained, and the core batch/failure behavior is covered. However, for a tool whose only required parameter is a nested array of selector/value pairs, the description leaves the array ordering, the meaning of `return_ui`, and post-failure submit behavior unaddressed.

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 and it largely does not: `fields` is never described as an ordered selector/value list, and `return_ui` is never mentioned anywhere in the schema or the description. Only `submit` gets any gloss via "optionally submit", and the Selector $defs itself does the heavy lifting for matching semantics.

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 opens with a specific verb and resource ("Fill several fields ... and optionally submit in one tool call"), which immediately distinguishes it from the single-field input_text and gesture/act siblings by making the batch nature explicit. It stops short of naming an alternative tool outright, but the purpose is 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?

"in one tool call" and "One tree dump total, not one per field" give a clear context signal: use this instead of repeated per-field filling when multiple fields must be set. "Optionally submit" tells the agent the trailing submit action is conditional. No explicit exclusions or edge conditions (e.g., when not to batch) are stated.

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