style_tree

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

With no annotations, the description carries the full burden and does so well: it discloses execution ordering (plain annotations → taxonomy → collapse), the --color-all limitation that prevents exact CLI reproduction when mixing color and color_all, multi-tree styling/export behavior, and that a warnings entry is emitted when split/all cannot be reproduced. Auth, rate limits, and failure modes are not addressed, but the operational semantics are notably rich.

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?

Purpose is front-loaded in the first sentence, followed by returns, then behavior. Prose is dense but each clause carries information. The 'Args: See the mapped parameter table...' sentence is low-value filler but not egregious.

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?

An output schema exists, so return-value explanation is not required (though provided). However, for a 52-parameter, zero-schema-coverage tool with no annotations, the description is materially incomplete: it neither documents the parameters inline nor supplies the enum-like value spaces (layout, order, multi_tree, collapse_style, etc.), leaving an agent unable to invoke it correctly without external docs.

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?

52 parameters at 0% schema description coverage, and the description explicitly defers to an external file ('See the mapped parameter table in docs/tools_reference_EN.md'), which an agent cannot reliably resolve mid-call. Only a handful of parameters (multi_tree, seed) get inline meaning; the remaining ~50 remain opaque from both schema and description.

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+resource clearly: styles a tree via the full FigTreeKit parameter surface and exports a FigTree-compatible Nexus file. The output artifacts (file, cli_command, config_json, per-operation records) are named. It does not, however, explicitly differentiate itself from single-operation siblings like highlight_clade, color_clade, or collapse_rank, which overlap in function.

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 implied rather than stated: the multi_tree semantics (first/last/random, seed for reproducibility) convey some when-to context, and 'every argument is optional' sets defaults. But there is no explicit guidance on when to choose this omnibus styling tool over the granular siblings (color_clade, collapse_rank, highlight_clade), nor any when-not conditions.

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