编辑器实例

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

Beyond the readOnlyHint=true annotation, the description adds a relevant behavioral guarantee: no authentication credentials are returned, and the instances are already open. This extra constraint helps an agent avoid expecting credentials, though output shape and empty/error behavior are not covered.

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?

One concise sentence states the purpose and adds a relevant caveat. There is no filler, and the important credential warning is placed at the end without hurting readability.

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 one-parameter read tool, the description is acceptable, but there is no output schema and the description does not outline the returned content or an empty/failure case. This is not critical but is a clear gap given the complete absence of output schema details.

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 gives projectId as a string, but its description coverage is 0%. The tool description merely says 'the specified project,' which does not materially explain the meaning of projectId, its possible identifiers, or how it is obtained. The description does not compensate for the low schema coverage.

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 states a specific verb and resource: it lists opened Creator instances for a specified project. It is clear operationally, but it does not differentiate from cocos_runtime_instances except through the tool name and title, so sibling distinction is left to inference.

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 phrasing implies use when the agent needs to see already-open Creator sessions for a project. However, there is no explicit when-to-use versus the runtime sibling, and the 'specified project' parameter is not developed into whichever timing or alternative context.

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