check_state

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

With no annotations, the description carries the behavioral burden, and it discloses non-waiting behavior, exception-free behavior, and the count timeout semantics. It does not state the return value for the other check modes, which is a meaningful gap for a check tool.

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 front-loaded and uses a compact Args list, but the count-waiting behavior is explained twice: once as 'Unless setting count...' and again in the detailed 'For count' passage. This redundancy makes it less tight than it could be.

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 simple read-only check with no annotations or output schema, it covers parameter meanings and exception/timeout behavior well. However, the lack of a return-value contract for non-count checks means an agent cannot fully predict what the tool will produce.

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?

Since schema descriptions cover 0% of the parameters, the description compensates by explaining all three: check values, selector as a CSS selector, and text used for text_visible. It also notes the dependency that text_visible requires text, though it does not precisely define 'present' versus 'visible'.

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 first sentence names a specific operation, 'Check the current state of the page or an element', and the Args list enumerates concrete state types: present, visible, count, text_visible. It also contrasts with wait_for, making the intended use clear.

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 explicitly says 'this never waits' except for count and 'Never raises exceptions — use wait_for if you want to wait for a state', which is strong routing to an alternative. However, it does not address when to use sibling tools like assert_that or find_elements, so the guidance is not fully exhaustive.

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