audio_check_game_project

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description reinforces this ('Read-only: never modifies the project'). It adds real behavioral context beyond annotations: truncation limits (at most max_files files, first max_seconds each), the loop-seam exception using real loop points, and the res:// path semantics.

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?

Front-loaded with purpose, then progressively adds detail, return shape, then behavioral constraints. It is dense with parenthetical clauses and reads as a long run-on, but nearly every clause carries distinct information needed to call the tool correctly.

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 complex, non-destructive audit tool with four parameters and no output schema, the description covers the return structure (summary, per-category categories stats, issues sorted problem > warning > info, each with res:// file and fix), the parameter semantics, and the runtime limits. An agent has everything needed to invoke and interpret it.

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 0%, so the description must compensate, and it largely does: it explains the 'categories' override with glob examples ({"audio/stingers": "music", "*/click_*": "ui"}), and defines max_files/max_seconds as sampling limits, plus identifies project_dir via 'the folder with project.godot'. It stops short of a formal per-parameter enumeration, so 4 rather than 5.

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?

Specific verb and resource: 'Audit the audio of a Godot 4 project (the folder with project.godot)'. The scope is enumerated precisely (inventory, import settings, loudness consistency, per-file problems, res:// references), so an agent can distinguish it from generic analyzers like audio_analyze or audio_info without opening a schema.

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?

Gives clear context for when to use it (auditing a whole Godot 4 project's audio) and routes the agent downstream by emitting 'suggested_batch' for audio_batch_process and 'fix' entries as audio_process operations. It does not compare itself to audio_check_delivery or state exclusions, so no full 5.

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