stm32_list_projects

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the core behavior (recursive scan) and what is returned, but omits potential edge cases like error handling for nonexistent directories, performance implications of scanning large trees, or whether the scan is read-only. It does not contradict any annotations (none exist), but it leaves room for assumptions about side effects or failure modes.

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 exactly two sentences: the first states the action and scope, the second lists the return values. It is front-loaded with the main purpose and contains no fluff or redundant phrasing. Every word earns its place.

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 simple listing tool with a single parameter and an output schema (which presumably documents the return structure), the description covers the essential points: what it scans, what it returns. It does not address edge cases like empty results or how STM32 projects are detected, but these are likely minor given the tool's straightforward nature. The presence of an output schema reduces the need to explain return types in the description.

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?

The schema defines only 'root_dir' with no description (coverage 0%), so the description must compensate. It adds meaning by clarifying that root_dir is a 'workspace or root directory' to be scanned. This establishes the parameter's type and purpose, which is a meaningful improvement over the bare schema. However, it doesn't specify path format (absolute vs. relative) or whether the directory must exist, leaving minor ambiguity.

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 recursively scans a directory to discover STM32 projects, and enumerates the exact return data (names, paths, MCUs, .ioc presence). This distinguishes it from siblings like stm32_create_project or stm32_import_project, which operate on projects rather than listing them. The verb 'scans' and resource 'STM32 projects' are specific and 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 implies usage: you use this when you need to enumerate existing STM32 projects in a directory. It does not explicitly name alternatives or exclusions, but the context is clear enough that an agent would know to invoke it for discovery tasks. Since no sibling tool performs the same listing function, explicit routing isn't critical, though a mention of 'use when you need to know what projects exist' would strengthen it.

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