tree_app

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

With no annotations, the description carries the full burden and does disclose the key non-obvious behavior: this opens an interactive UI (a side effect beyond a data read), returns the root slice, and the UI subsequently routes edits through the same tree_* tools. It omits whether the UI requires a live user session, whether it blocks, or what permissions are 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?

Two sentences, front-loaded with the action and resource, followed by the interaction model. The parenthetical field list (kinds, params with provenance, links, rules) is compact and informative rather than 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?

Output schema exists, so return values need not be spelled out, and with zero params the schema needs no explanation. The description covers purpose, return, and cross-tool interaction, leaving only session/permission behavior unstated.

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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly introduces no parameter concepts.

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?

"Open the Quern navigator — an interactive view of the tree and its semantics" gives a concrete verb and resource, and the closing clause clarifies that this launches a UI rather than performing a data operation like the tree_* siblings. The term "Quern navigator" is undefined jargon, and the distinction from siblings is left implicit rather than named.

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?

Usage is only implied: the description notes the UI lets the user "browse and coedit," suggesting a human-in-the-loop scenario, but it never states when to choose this over tree_get/tree_find/tree_brief or whether it should be called only on explicit user request. No exclusions or preconditions are given.

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