assert_state

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

Beyond the readOnlyHint annotation, the description discloses two decisive behaviors: assertions 'come back passed/failed with what was actually observed' (return semantics), and 'a false assertion is a result, not an error' — telling the agent a failed check is a normal outcome, not a thrown error. The 'honest/evidence' framing adds integrity context no annotation carries. No conflict with readOnlyHint; asserting is a read-only 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?

Three sentences of roughly 50 words, purpose front-loaded in the first clause. Sentence 2 delivers the load-bearing result-vs-error semantic; sentence 3 enumerates the argument options. Every sentence earns its place and adds new information — no padding or restatement of the name.

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 moderate-complexity read-only tool (5 optional nested parameters, no output schema), the description covers what an agent needs: when to call (task end), what to pass (one of the five), and what happens (passed/failed with observed evidence, never an error). It compensates for the missing output schema with clear return semantics. Minor gaps remain — exact multi-parameter behavior and precise response shape — but the routing and invocation choices are adequately covered given the sibling set.

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% — the schema already documents each parameter (e.g., text_present requires OCR visibility, widget_exist targets AT-SPI). The description adds the key semantic beyond the schema: 'Give any of: ...' clarifies these are alternative single assertions, a constraint the all-optional schema leaves implicit. It does not say what happens when multiple are passed at once, but the schema carries the per-parameter detail.

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?

States a specific verb + resource: 'Prove the desktop is in a state' — an assertion/verification tool over desktop state. The five assertion types are enumerated (window_exists, window_focused, text_present, widget_exist, clipboard_contains), and 'the honest way to END a task' positions it against action/search siblings like wait_for and ui_find. An agent can tell what this tool is for without ambiguity.

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?

Provides a clear usage context — use at the end of a task to verify the final state with evidence, and a failed assertion is a valid result. However, it does not explicitly name alternatives (e.g., wait_for for polling until a condition becomes true) or state when not to use it, so the routing guidance is context-only, not exclusion-based.

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