create_redpitaya_project_rtl

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

No annotations exist, so the description carries the full burden. It usefully discloses fail-fast semantics and a structured return payload, but says nothing about duration (this is a multi-minute FPGA build), whether it overwrites or requires an empty directory, whether it needs a running Vivado session, or whether partial artifacts are left behind on failure. That is a large gap for a mutating, long-running 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?

Two sentences, front-loaded with 'One-shot composite' followed by the stage order, then fail-fast behavior. There is essentially no waste; the only cost is that the arrow chain is dense and could have carried parameter meaning.

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?

With no annotations and no output schema, the definition needs to explain both the environment prerequisites and the 11 parameters, and it explains neither. The pipeline sequence and failure behavior are genuinely helpful, but an agent still cannot safely call this without guessing at directory, timeout, and xdc_variant semantics.

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 only 9 percent across 11 parameters (only board has a default note in the schema), so the description needed to compensate and does not. It never mentions name, directory, top_module, verilog_files, xdc_variant, jobs, timeouts, synth_flags, or extra_xdc_files, leaving required and optional parameters equally opaque.

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 spells out a concrete pipeline (create project -> add HDL sources -> apply XDC -> synth -> impl -> write_bitstream -> .bit.bin), which makes the composite nature unmistakable and implicitly distinguishes it from the single-stage siblings like create_project, run_synthesis, and generate_bitstream. It never names those siblings as alternatives, keeping it just short of a 5.

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?

'One-shot composite' implies this replaces chaining the individual stage tools, and 'stops on the first failing stage' hints at a fail-fast use case. However, there is no explicit statement of when to prefer this over the granular tools, and no mention of prerequisites such as an open session or a valid board target.

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