select_iframe

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

Without annotations, the description carries full burden and discloses key behaviors: it returns a new session ID, the parent session remains active, and the returned session must be closed. It does not mention error cases (e.g., iframe not found, nested iframes), but overall it provides sufficient transparency for typical use.

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 concise (three sentences) and front-loaded with the main action. Every sentence adds value: the first explains what the tool does, the second gives usage instructions, and the third explains the necessity. No wasted words.

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 tool's moderate complexity and the absence of an output schema, the description covers purpose, usage, return value, cleanup, and rationale. It lacks error handling details but is complete enough for an agent to use correctly. The presence of many sibling session tools makes the distinction valuable.

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% with both parameters described. The description adds meaning by clarifying that session_id is the parent session ID and that the tool returns a new session ID for the iframe. Though it does not explicitly reiterate schema fields, it integrates parameter roles into the narrative, providing context beyond 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 clearly states the tool's purpose: switching into an iframe and returning a new session ID scoped to that iframe's content. It uses specific verbs and resources, and distinguishes itself from sibling tools like open_session or navigate_session by explaining the iframe-scoping behavior.

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 provides explicit guidance: use the returned session for elements inside the iframe, keep the parent session for page-level actions, and close the returned session when done. It also explains why this tool is necessary (cross-frame content unreachable via parent selectors), helping the agent decide when to use it over alternatives.

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