tree_brief

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

With no annotations, the description carries the full burden, and it does disclose real behavior: settled claims are counted in a trailer rather than emitted, superseded entries are omitted by default, and the output is vocabulary-blind. It never explicitly states that the call is a side-effect-free read, which is the main residual gap for an un-annotated tool.

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?

It is front-loaded with what the tool returns, then usage, then flags — a sensible order. But the prose is heavily woven and metaphor-laden ('the cost this exists to refuse', 'like every verb here'), and the closing debt remark costs the reader effort for little operational payoff.

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 zero-required-param read tool with an output schema, the description covers return content, filtering behavior, and the two view flags. Combined with the output schema it is sufficient to invoke correctly; only the absence of an explicit read-only guarantee keeps it from full marks.

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 0%, so the description must compensate, and it does for all three params: `under=PATH` restricts to one branch, `all=True` substitutes superseded entries for omission, `fat=True` appends word counts and sorts by them. Types and defaults come only from the schema, but the meaning and intent of each flag is fully supplied.

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 states the concrete return shape (one line per current entry: kind, path, name, declared links, ungrounded params, red rules) and explicitly frames the tool as a table of contents against tree_get as the chapter. That distinguishes it from its closest sibling. The metaphor 'the working set' is jargon, but the enumeration that follows grounds it.

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 gives an explicit entry condition ('START HERE on an unfamiliar tree') and names the alternative it replaces (tree_get('')) together with the reason (reading the whole history to find a dozen binding claims). There is no explicit 'do not use this when X' clause, but the conditional is strong enough for an agent to route correctly.

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