download_source

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds valuable behavioral context: requires TYPLEAF_SESSION, creates the directory if missing, and fails on non-empty directory unless overwrite=true. This goes beyond annotations by detailing the failure condition and the overwrite trigger. It doesn't contradict any annotation.

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 with zero fluff. The core purpose is front-loaded, followed by two critical behavioral constraints and a prerequisite. Every sentence earns its place, and the structure makes scanning easy.

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?

The description covers the key operational aspects: action, prerequisites, failure modes, and overwrite behavior. It doesn't describe the return value or what happens on success, but with no output schema and a destructive/idempotent annotation set, this is a minor omission. The detailed project_id guidance in the schema further fills context. Could mention success behavior but is otherwise complete.

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 description coverage is 100%, so the schema fully documents all three parameters. The main description adds no extra parameter semantics beyond what the schema provides. The project_id description is exceptionally rich, but that's already in the schema. Baseline 3 is appropriate because the schema carries the load.

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 a specific verb ('Download') and resource ('project source') with an explicit action ('extract it into a local directory'). It also specifies unique behaviors (directory creation, non-empty failure) that distinguish it from the sibling download_source_zip, which likely skips extraction. Purpose is unambiguous.

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 itself doesn't name alternatives, but the project_id parameter schema provides strong usage guidance: only for Typleaf projects, never for general local file I/O, prefer read/grep if a local copy exists, and always call list_projects when unsure. This embedded guidance covers when-to-use and when-not-to-use, though it doesn't explicitly contrast with download_source_zip. Slight gap in explicit sibling differentiation prevents a 5.

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