visualize_branch_tree

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose two useful traits — the output is Mermaid ``flowchart TD`` text and the tool is gated behind Kiln Pro — but the bulk of the second paragraph ('preserve this version so you can branch, restyle, compare outcomes') describes version-preservation behavior, not visualization, and never states read-only status, pagination semantics of max_commits, or what the returned diagram covers.

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 front-loaded first sentence is excellent and self-contained. Everything after it is boilerplate: a paywall upsell sentence that does not describe this tool's behavior, followed by a URL. Roughly half the text fails to earn its place and actively distracts from the operational sentence.

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 4-parameter tool with no annotations and no output schema, the description leaves real gaps: the required artifact_id has no description anywhere, 'detail: rich' is unexplained, and max_commits (a pagination control) is never mentioned. An agent would have to guess at argument values and cannot tell how large a tree it will get back.

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 75%, so the baseline is 3. The description adds marginal value by listing the three artifact kinds (design / preset / feature), which effectively documents the allowed values of artifact_type even though the schema provides no enum; it says nothing about artifact_id, detail levels, or max_commits.

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 first sentence names a specific verb (Render), a specific resource (design / preset / feature branch tree) and even the output format (Mermaid ``flowchart TD``), which an agent can act on directly. It does not explicitly distinguish itself from close siblings such as show_branch_history, show_design_lineage or compare_branches, and the second paragraph drifts into unrelated 'preserve this version' marketing copy that blurs the purpose slightly.

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: it renders a tree, so presumably you call it when you want a visual of branch structure. There is no guidance on when to pick this over show_branch_history, show_design_lineage, or compare_branches, though the 'Requires Kiln Pro' line does at least signal a tier precondition.

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