cocos_add_styled_text_block

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: color sourcing from UI theme, text wrapping/overflow behavior, conditional divider rendering (only when body is present and show_divider=True), alignment application, and return value structure with nulls for absent pieces. It doesn't mention error conditions, performance characteristics, or mutation effects on the scene.

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 efficiently structured with zero wasted sentences. It opens with the core concept, explains the rationale, details implementation behaviors, and concludes with return values. Every sentence adds essential information about tool behavior, constraints, or outputs.

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 UI creation tool with 8 parameters, 0% schema coverage, no annotations, and no output schema, the description provides substantial context about behavior, constraints, and return values. It explains the conditional logic, styling defaults, and output structure. However, it doesn't cover error cases, scene modification effects, or provide examples of typical usage patterns.

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?

With 0% schema description coverage for 8 parameters, the description compensates exceptionally well. It explains the semantic meaning of title, subtitle, body, and show_divider parameters, clarifies the conditional relationship between body and divider, describes alignment options, and implies width controls block dimensions. It provides crucial context missing from the bare schema.

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: it creates a styled text block with title, optional subtitle, optional divider, and optional body. It specifies this is a composite UI element that pulls colors from the active theme and handles text wrapping/overflow. The description distinguishes it from sibling tools by explicitly mentioning it replaces composing from 4-6 'add_label' calls.

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 clear context for when to use this tool: for the 'most frequently rebuilt pattern in AI UI code' to avoid composing from multiple 'add_label' calls. It mentions an alternative approach (using 'add_label') but doesn't explicitly state when NOT to use this tool or compare it to other text-related sibling tools like 'cocos_add_label' or 'cocos_add_richtext'.

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