show_framing

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

Annotations only give readOnlyHint and openWorldHint, so the description carries most of the behavioral load and does so well: it discloses that a visible browser window opens on this machine, that it persists until close_framing is called, and that the call returns a screenshot. It does not cover latency, what happens if the window is already open, or failure modes when the target cannot be resolved. Note: launching a persistent browser window is a side effect that sits uneasily with readOnlyHint, though the annotation most plausibly refers to data mutation.

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 core behavior is front-loaded in the first sentence and the rest is a compact parameter glossary with concrete examples, so little is wasted. It is dense to the point of terseness in places (e.g. the ra_h/dec_deg clause), but nothing is padding.

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?

With no output schema, the description correctly states what is returned (a screenshot of the framing) and how the session is torn down. For a 9-parameter tool with zero schema documentation, the coverage is good, but overlap_pct is unexplained and there is no note on resolution failures or what the screenshot looks like.

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 and largely does: it defines target as an object name resolved via the API versus a mere label when ra_h/dec_deg are supplied, gives the mosaic format ("COLSxROWS"), the rotation unit, and example formats for sensor_mm ("11.136x6.264") and sensor_px ("3840x2160"), and explains that the focal/sensor params override the default rig for this call. It leaves overlap_pct completely undocumented and gives only a minimal gloss for rotation.

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 specific verb (frame), a specific resource (a target), and the exact environment (Telescopius' Telescope Simulator with the configured rig in a visible browser window), plus the return artifact (a screenshot of the framing). It also names the sibling close_framing as the way to tear the session down, so an agent can distinguish it from the rest of the sibling set 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?

It establishes clear context: use this to frame a target and get a visual, the window stays open for hands-on adjustment, and close_framing closes it. What is missing is any explicit exclusion or routing statement, e.g. when to prefer target_info or search_targets over opening a live simulator window.

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