session_act

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly reveals that failed assertions do not end the session and are marked with a red frame in the video, a non-obvious behavior. It also discloses the return content (step result plus screenshot), which is useful for the agent to know what to expect.

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 compact—two sentences plus two examples—and front-loaded with the primary purpose. Every sentence earns its place: the first states what and returns, the second defines step via examples, the third conveys failure behavior, and the fourth points to get_schema for more detail. No 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?

Given the large, complex step union schema, the description cannot enumerate all step types, but it wisely references get_schema(kind="step") to fill the gap. It also notes the screenshot return, which is important for an agent that may need visual verification. It does not mention potential error conditions beyond assertions, but the schema and the get_schema pointer cover most of the missing context.

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?

The schema coverage is 0% at the top level, but the description partially compensates by explaining that 'A step is any action or assertion from the ticket schema' and giving two concrete step examples. However, it does not describe session_id beyond what the name implies, and the rich per-field descriptions inside the $defs of the schema carry most of the parameter 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 states a specific verb ('Execute'), a specific resource ('one step in an open session'), and a clear output ('step result plus a screenshot'). It provides two concrete examples that make the resource unambiguous aid distinguishes it from sibling tools like session_open (which creates a session) and session_screenshot (which only captures a screenshot).

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 states the precondition 'in an open session' and instructs the agent to call get_schema(kind="step") for all step types, which is a clear usage pointer for constructing the step parameter. It does not explicitly name alternatives or exclusions, but the session-related siblings make the context clear.

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