Create text overlay

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

Beyond the annotations, the description discloses that the tool produces a 'finished visual layer ready for setup_output', that the text is static, and that it can composite over a source TOP or output on transparent background. It mentions creating a self-contained container at parent_path, which implies node creation. It does not detail every side effect (e.g., naming collisions), but it covers the expected behavior well.

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 information-dense yet efficient. Each sentence serves a distinct purpose: function, use cases, and differentiation. No filler or repetition; it front-loads the primary action and then provides contextual guidance, making it easy for an agent to parse quickly.

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?

With 8 parameters, no output schema, and sparse annotations, the description covers the essential context: what the tool does, when to use it, and how it differs from similar tools. It omits potential error conditions or prerequisites, but given the clear semantics of the schema and the explicit 'static text' note, it is sufficiently complete for an agent to select and invoke the tool.

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 coverage is 100%, so the baseline is 3. The description adds meaning by explaining the optional source_path behavior ('Omit to get the text alone on a transparent background, ready to composite later') and clarifies the output as a Null TOP container. It also frames parameters like font size, color, and alignment within the compositing pipeline, which the schema alone doesn't fully capture.

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 opens with a specific action: 'Composite styled STATIC text over a visual (or on its own transparent background)', clearly identifying the tool as a text overlayer. It names the involved nodes (Text TOP, Composite TOP, Null) and explicitly differentiates from siblings like create_kinetic_text and create_text_crawl, leaving no ambiguity about its purpose.

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?

Explicit use cases are provided: 'For lyrics, titles, song names, or credits in a set.' It also gives explicit exclusions: 'The text does not move: for a single word that flashes/pulses/slides use create_kinetic_text, and for multi-line scrolling tickers/credits rolls/typewriter reveals use create_text_crawl.' This is textbook when-to-use vs alternatives guidance.

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