cocos_scaffold_audio_controller

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

With no annotations provided, the description carries the full burden and excels at disclosing behavioral traits. It details idempotency (playBGM('already-playing') is no-op), error handling (unknown clip names silently skipped), persistence (volumes stored to localStorage), implementation details (auto-attaches components, swallowed write failures), and return values. This provides comprehensive behavioral context beyond basic functionality.

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 appropriately sized and front-loaded with the core purpose. Each section (Runtime API, Inspector, Implementation details, Behavioral traits, Returns) adds valuable information without redundancy. While slightly longer than minimal, every sentence earns its place by providing essential context for a complex scaffolding tool.

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?

Given the tool's complexity (scaffolding a full audio manager), no annotations, 0% schema coverage, and no output schema, the description provides exceptional completeness. It covers purpose, usage patterns, implementation details, behavioral characteristics, error handling, persistence, and return format. This fully compensates for the lack of structured metadata and gives the agent everything needed to understand and invoke the tool correctly.

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 input schema has 0% description coverage, so the description must compensate. While it doesn't explicitly mention the two parameters (project_path, rel_path), it implies their purpose through context: generating AudioController.ts in a Cocos project. The default value 'AudioController.ts' for rel_path is mentioned in the description's first sentence, and project_path is logically needed for file generation. However, it doesn't fully document parameter formats or constraints.

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 generates an AudioController.ts file that serves as a singleton BGM + SFX manager. It specifies the exact resource (TypeScript file) and verb (generate/scaffold), distinguishing it from sibling tools like cocos_add_audio_source or cocos_add_audio_file which add different audio-related components rather than creating a comprehensive controller script.

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 context through runtime API examples and inspector properties, suggesting this tool is for setting up audio management in Cocos projects. However, it doesn't explicitly state when to use this vs. alternatives like cocos_add_audio_source or cocos_scaffold_ui_screen, nor does it mention prerequisites or exclusions. The guidance is present but not explicit about alternatives.

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