android_install_toolchain

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

With no annotations at all, the description carries the full burden, and it does disclose two genuinely useful traits: everything lands under the root directory and the operation is idempotent/re-runnable. It is silent on the heavier implications of an install tool — network downloads, disk/time cost, admin or license acceptance requirements, and whether it mutates environment variables or existing SDK state.

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, front-loaded with what is installed and scoped by the parenthetical, then the optional build behavior. No filler and nothing repeated from the schema.

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 6-parameter installer with no annotations and no output schema, the definition covers what is installed, where, and idempotency. It leaves out prerequisite/failure conditions and what the agent should do with the result, which matters for a heavyweight environment-mutating tool.

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 already explains root, profile, buildAfter, buildTools, sdkPlatforms and gradleVersion with examples. The description only echoes the root-directory placement and the optional build, adding little beyond the structured fields; baseline 3 is appropriate.

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 gives a specific verb and resource set: installs JDK17, Gradle and the Android SDK for a named project, with an optional source pull plus build. That is clearly distinct from android_build, android_get_build_result and android_list_profiles, though it never names those siblings to route the agent explicitly.

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 implies the setup-then-optionally-build flow via '可选顺便拉源码并构建一次' and the buildAfter parameter, which hints at when this precedes a build. It never states prerequisites, when not to use it, or that android_build is the alternative for later builds, so usage is only implied.

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