switchFrame

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 accurately discloses that the tool sets a stateful context affecting subsequent commands, resets with no arguments, and auto-resets on navigateTo. This adds meaningful context beyond the input schema.

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 two sentences and front-loaded. The first sentence defines the tool's purpose and affected operations; the second covers reset and auto-reset behavior. Every sentence carries high-value information without redundancy.

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?

The description covers key behavioral aspects (statefulness, affected commands, cross-origin use case, reset, and auto-reset) and is sufficient for an agent to select and invoke the tool correctly. It does not mention listFrames for discovery, but that is not essential given the schema and no output schema.

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?

Input schema coverage is 100% with detailed descriptions for both parameters (substring matching, mutual exclusivity). The description adds no additional parameter semantics beyond the schema, but 'Call with no args' reinforces that both parameters are optional, matching the schema.

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 uses a specific verb ('Set the active frame') and clearly identifies the resource (active frame) and scope (affects click/type/hover/analyzePage/find/executeScript/waitForElement). It distinguishes itself from sibling tool listFrames by focusing on setting rather than listing frames.

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 when to use the tool ('required to automate cross-origin iframes') and provides reset behavior ('Call with no args to reset to the main frame') and auto-reset on navigateTo. It does not name alternative tools explicitly, but the usage context is clear and actionable.

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