cocos_set_start_scene

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

No annotations are provided, so the description carries the full burden. It mentions the tool modifies a project configuration file ('project.json'), implying a mutation, but doesn't disclose critical behavioral traits: whether this requires specific permissions, if changes are reversible, potential side effects (e.g., breaking existing builds), or error handling. The description adds minimal context beyond the basic action.

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 with two concise sentences. The first sentence states the action and target, while the second explains the runtime impact. It's front-loaded with the core purpose, and every sentence adds value without redundancy. However, it could be slightly more structured with bullet points for parameters.

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 (mutation with 2 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't cover parameter details, error cases, return values, or behavioral nuances. For a configuration tool that modifies project settings, more context is needed to ensure safe and correct usage.

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 for undocumented parameters. It adds no information about the two required parameters ('project_path' and 'scene_uuid'), such as their formats, examples, or constraints (e.g., UUID format, valid project paths). The description fails to provide meaningful semantics beyond what the bare schema titles imply.

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 action ('Set the project's start scene') and the target resource ('in settings/v2/packages/project.json'), with a specific purpose ('The engine loads this scene first at runtime'). It distinguishes from sibling tools by focusing on project configuration rather than scene/content creation or modification. However, it doesn't explicitly differentiate from similar configuration tools like 'cocos_set_design_resolution' or 'cocos_set_physics_2d_config'.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing scene UUID), exclusions (e.g., not for runtime changes), or related tools (e.g., 'cocos_create_scene' to create scenes first). The context is implied through the file path, but explicit usage instructions are absent.

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