tree_scope

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

With no annotations provided, the description bears the full burden of disclosing behavior. It discloses that the tool does not read file content, skips hidden files and VCS dirs, and returns a JSON array with specific fields. There is no mention of side effects or destructive actions, which is appropriate for a read-only scan. The output structure is thoroughly explained.

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 description is well-structured: a summary sentence, then output format details, usage guidance, and parameter descriptions. It is front-loaded with the main purpose. While somewhat lengthy, each sentence adds value and is clearly organized. Minor redundancy could be trimmed, but overall it's efficient.

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?

Given that an output schema exists, the description still provides detailed explanation of the return value, including field names, types, and semantics. It covers scanning behavior (skipping hidden files, depth limit) and usage context. No critical information is missing for an agent to select and invoke this tool correctly.

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?

Since schema description coverage is 0%, the description must compensate. It explains root_path as an absolute path, root_title as the title for the root entry (with default behavior: empty uses directory name), and max_depth as maximum nesting depth with default 10. This adds meaning beyond the schema types and defaults.

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 clearly states that the tool scans a directory and returns compact telemetry without reading file content. It distinguishes itself from sibling tools like inject_directory_to_mindmap by specifying its use case as a precursor for node count validation.

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?

The description explicitly recommends using this tool before inject_directory_to_mindmap to obtain a reference count of expected nodes and after injection to validate totals. It also notes that hidden files and VCS directories are skipped. However, it does not provide explicit 'when not to use' guidance, but the context is clear enough.

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