generate_code

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

With no annotations, the description carries the full burden; it does disclose what is written (application code only, excluding drivers and IDE files) and that `mode` applies a layout before generation. It is silent on overwrite behavior for existing files, whether the project must be open/saved first, and what the tool returns, which matters for a filesystem-mutating 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 tight sentences with the core behavior front-loaded and the layout caveat second. The parenthetical CLI syntax (`generate code <dir>`) is slightly cryptic shorthand but costs little.

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?

A file-generating tool with no annotations and no output schema should say more about side effects (existing directory contents, prerequisites on project state) and about how the result is reported. The exclusion of drivers/IDE files is the main completeness win, but key operational context is missing.

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%, so the baseline is 3, but the description adds real meaning by explaining that `mode` forces the all-in-main or one-file-per-IP layout 'first', an ordering effect not conveyed by the enum values. `output_dir` and `project_id` remain as the schema describes them.

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?

States a specific verb and resource: generate CubeMX application code into a directory, with an explicit exclusion (no drivers/IDE files). It does not distinguish itself from the very similar siblings project_generate and standalone_generate, leaving an agent to guess which generator applies.

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 scope note ('only application code, no drivers/IDE files') implicitly tells the agent when this is the right tool, but there is no explicit when/when-not or reference to the alternatives project_generate / standalone_generate. Usage must be inferred from the scope phrasing alone.

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