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

Annotations already declare readOnly=false, destructive=true, openWorld=true, and idempotent=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it creates a separate object, preserves the user's exact wording, and warns against reusing an elementId. It does not explain the exact destructive scope, but annotations carry that burden.

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 three tight sentences with no waste. The core action is front-loaded, followed by the exact-wording constraint and the key alternative to update_text.

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 creation tool with a large nested options schema, the description covers the essential semantics: new separate object, preserve wording, and use update_text for edits. The schema is fully described, so parameter detail is not missing, but the description does not mention the returned new element ID or destructive/session caveats, which would improve completeness.

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 100%, so the schema already documents the parameters in detail. The description mentions the specified print area and existing text/font/style options, but it does not name parameters or explain placement, coordinateSpace, or the many option aliases. The baseline of 3 is appropriate because the schema does the heavy lifting.

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: create a separate new text object in a specified print area. It also explicitly distinguishes this from update_text, so an agent can tell whether to add a new object or edit an existing one.

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 gives explicit usage guidance: do not reuse an existing elementId, and use update_text to edit an existing object. This names the key alternative and the condition that selects it, leaving little ambiguity for the core add-vs-edit decision.

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