bl_focus_element

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

With no annotations, the description carries the full behavioral burden, and it delivers: it warns that zooming can still leave the element hidden behind other geometry and explains how to use isolate to work around it. It also states the side effect on the viewport and that a restore step is needed.

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 first sentence front-loads the core operation and result, while the second paragraph adds only the crucial caveat and remediation. No filler or redundant restatement of the schema.

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 tool with no annotations and no output schema, the description covers the essential workflow, the main failure mode, and the cleanup call. It leaves minor gaps such as the format of the returned image/focus payload and the semantics of width/timeout, but the key usage context is complete.

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 description coverage is 0%, so the description must compensate. It explains guid through 'this GlobalId' and isolate through 'hide everything else', but width and timeout receive no semantic guidance beyond their schema titles and defaults.

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 names a concrete action sequence—select by GlobalId, zoom viewport, return image and focus target—which distinguishes it from siblings like bl_screenshot or ifc_get_element. The verb and resource are specific, and the return payload is stated.

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?

It gives clear operational context: the tool's zoom does not guarantee visibility, and the description tells the agent when to pass isolate=true and to follow with bl_isolate(restore=true). It does not explicitly spell out when to avoid this tool or prefer an alternative, so it stops short of a 5.

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