plainhub_open

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

With no annotations, the description carries the full burden and does add real behavioural context: the browser self-authenticates, the saved token is passed only when noAuth is false, the target URL defaults to app.plainhub.dev unless PLAINHUB_APP_URL is set, and the token is scoped to the production URL only. It does not state whether a browser window is opened as a side effect, whether the call blocks, or what happens on an invalid repo/path.

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 primary action is front-loaded in the first clause, with the settings mode, usage trigger, auth caveat, and example following in a logical order. The long parenthetical list of settings keys is dense and could read as schema duplication, but no sentence is purely 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?

For a 13-parameter, side-effecting tool with no annotations and no output schema, the description covers the two invocation modes, authentication handover, environment-driven URL, and a concrete example. What remains unstated is the observable outcome of the call (window opened, no return payload, or error behaviour for a bad repo).

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 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the settings parameters (theme, fontSize, preview, sidebar, lineNumbers, whitespace, header) only take effect when repo and path are omitted, a mode relationship the schema cannot express. The worked example further anchors repo/path/preview usage.

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?

States a specific verb and resource ("Open a file from a GitHub repository in the PlainHub browser editor") and explicitly identifies the overloaded second mode (editor settings when called without repo and path). The dual behaviour is disambiguated by the parameter condition, so an agent can distinguish it from siblings like plainhub_browse or plainhub_diff 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?

"Use it when the user wants to see or edit a file in the browser" gives a clear triggering context, and the parenthetical defines the settings-only invocation path. It does not contrast against sibling tools or state when not to use it (e.g., versus plainhub_browse for browsing repos), which keeps it 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.