eda_sys_header_menu_insert_system_header_menus

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 does this exceptionally well: it warns that inserted menus cannot be effectively deleted and require restarting the EDA software, that the interface is '暂不开发' (not yet developed), that it requires external interaction permission or it will always throw an Error, and that it's a non-public interface with no parameter documentation and potential breaking changes. This is far beyond what annotations would typically provide.

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 compact and front-loaded with the function signature, then delivers critical behavioral warnings in a scannable bullet-like format. Each line earns its place: the '暂不开发' warning, the deletion/restart caveat, the menu placement constraints, the permission requirement, and the non-public interface disclaimer. Slightly verbose due to the non-public interface disclaimer, but every piece is operationally relevant.

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 mutation tool with no annotations and no output schema, the description covers the critical operational context: what it does, where it can be applied, what will fail, and what the consequences are. The main gap is that it doesn't describe the return value (void is in the signature) or provide an example of the ISYS_HeaderMenus structure, but the explicit disclaimer about no parameter documentation makes this a known limitation rather than an oversight.

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 documents both parameters (args array and windowId). The description adds the function signature showing the expected parameter type ISYS_HeaderMenus, which gives some context about the args structure. However, it explicitly states '不提供参数的额外文档' (no additional parameter documentation), so the description doesn't add much beyond the schema. 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 clearly states the tool inserts system header menu items (sys_HeaderMenu.insertSystemHeaderMenus) and adds submenus under existing first-level menus. It distinguishes itself from sibling header menu tools (insert_header_menus, remove_header_menus, replace_header_menus) by specifying it inserts system header menus and cannot modify first-level menus. However, the Chinese '暂不开发' (not yet developed) creates ambiguity about whether the tool is actually usable.

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 provides explicit usage constraints: it can only add submenus under existing system first-level menus, cannot add/modify first-level menus, cannot add submenus under the '高级' (Advanced) menu, and new submenus are appended at the end. It also warns about the external interaction permission requirement. It doesn't explicitly name alternative tools for when this one shouldn't be used, but the constraints are clear enough for an agent to decide.

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