session_click_selector

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

With no annotations, the description carries the full burden and does it well: it discloses the session precondition, the return value ({ok: true}), and the exact failure modes with status codes (409 not-open, 404 missing identity, 502 no match/timeout). It leaves out what happens on multiple matching elements and whether the click waits for navigation, which are meaningful gaps for a browser click.

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?

Front-loaded with the core action, then prerequisites, then parameter meaning, then return/error contract. Sentences are short and every one adds information an agent needs, with no restatement of the title or filler.

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 two-parameter browser action with no output schema and no annotations, the description covers preconditions, error codes, and the return shape, which is nearly everything needed. The remaining hole is behavioral on the happy path: no statement about which element wins when the selector matches several, or whether a click that triggers navigation is awaited.

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 0%, so the description must compensate, and it does: `name` is defined as the identity name exactly as profiles_list reports it (a real semantic constraint, not just a type), and `selector` is defined as CSS with concrete examples and explicit non-examples (not XPath, not role/name). This adds substantial meaning beyond two bare strings.

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 (click) and resource (an element on the session's current page) plus the locating mechanism (CSS selector). It explicitly contrasts itself with XPath and role/name lookups, which are what sibling tools like session_snapshot or role-based helpers would provide, so an agent can identify it without opening the schema.

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?

Gives a clear precondition ("Requires a session opened with profile_start first") and redirects the agent to session_snapshot when it needs to discover an element. It doesn't state when to prefer an alternative over clicking, e.g. session_eval for scripted interactions or session_fill_selector for inputs, but the usage context is otherwise unambiguous.

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