crosspad_build

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

Annotations declare destructiveHint=true, and the description reinforces this with specific behavior: clean 'wipes build dir', fullclean 'runs idf.py fullclean', and notes auto-fullcleans when new apps detected. It discloses build-type restrictions (build_type ignored for IDF, only honored on clean|reconfigure). The description goes beyond annotations by explaining exactly what gets destroyed and when, though it doesn't mention whether the destructive behavior is reversible or if there are additional side effects.

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 with platform bullets, a clear mode×platform compatibility matrix, and front-loaded purpose in the opening line. Every sentence earns its place — platform mappings, preference rationale, mode compatibility, and output conventions are all packed efficiently without padding. Uses bold for emphasis on precedence ('PREFFER THIS') and clear visual structure with bullets.

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?

This is a complex tool (3 platforms × 4 modes × build_type interactions) with an output schema. The description fully covers platform behavior, mode compatibility, the tricky build_type/IDF/sdkconfig nuance, CMakePresets for STM, and output artifact locations. With the output schema providing return structure and annotations covering destructiveness, the description is complete for agent decision-making and invocation.

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 100%, but the description still adds meaningful value. It explains the mode compatibility matrix in the body, provides the output artifact path for STM, documents that build_type maps RelWithDebInfo→Release for STM, and explains IDF ignores build_type (comes from sdkconfig). The description supplements rather than duplicates the schema's parameter descriptions.

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 the tool builds CrossPad for a given platform with specific verbs per platform ('CMake + Ninja host simulator', 'idf.py build for ESP32-S3', 'CMake + Ninja + arm-none-eabi for STM32G0'). It specifies the exact output artifact (build/<preset>/CrossPad_STM32_r20.elf), and the platform×mode compatibility matrix distinguishes it from siblings like crosspad_flash, crosspad_run, and crosspad_check.

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 gives explicit PREFER THIS guidance over raw commands (cmake --build, idf.py build) with justification (picks MSVC env, sources IDF env, parses errors). The mode×platform compatibility matrix explicitly states which modes work on which platforms, and mode usage rationale is given ('fullclean after adding new apps, reconfigure after editing CMakeLists/presets'). This is exemplary usage guidance.

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