cocos_constants

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 states the tool returns constants, implying it's a read-only operation, but doesn't disclose behavioral traits like whether it requires authentication, has rate limits, or what format the return values take. The description adds some context about the types of constants (e.g., layer bitmasks), but lacks details on output structure or potential side effects. With no annotations, this is a moderate gap.

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 extremely concise and well-structured: two sentences that directly state the purpose and benefit. Every sentence earns its place by clarifying the tool's function and utility without any redundant information. It's front-loaded with the main action and efficiently uses examples to illustrate scope.

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 has no parameters, no annotations, and no output schema, the description provides basic completeness by stating what constants are returned and why to use it. However, it lacks details on the return format, potential errors, or how the constants are structured (e.g., as a list, dictionary, or specific data types). For a tool with zero structured data, the description is adequate but leaves gaps in behavioral and output context.

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 parameters with 100% coverage, meaning no parameters are documented in the schema. The description doesn't mention any parameters, which is appropriate since none are required. It adds value by explaining what constants are returned (e.g., layer bitmasks), but since there are no parameters, the baseline is 4 as it compensates for the lack of parameter documentation with semantic context about the output.

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's purpose: 'Return commonly used Cocos Creator constants.' It specifies the resource (Cocos Creator constants) and provides examples (layer bitmasks, blend factors, alignment enum values), which helps distinguish it from sibling tools that perform actions like adding components or building projects. However, it doesn't explicitly differentiate from potential sibling tools that might also return constants, though none are listed.

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: 'Saves you from looking up layer bitmasks, blend factors, alignment enum values, etc.' This suggests it should be used when needing these constants to avoid manual lookup. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., if other tools provide similar constants or if there are specific scenarios where it's preferred). No exclusions or prerequisites are mentioned.

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