fit_text

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

Discloses much more than readOnlyHint=false: the result is an ESTIMATE lacking font metrics, a shape that cannot fit at min_size reports still_overflowing, and saves are atomic with a two-slot backup where backup=False skips rotation. These traits (estimation caveat, failure reporting, atomic save semantics) materially affect how an agent trusts and invokes the tool, and none contradict the annotation.

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?

Four dense sentences, each earning its place: purpose/mechanism, shape=None scope, estimation caveat with verification, and atomic/backup save behavior. The main purpose is front-loaded and there is no filler, even though the overall density is high.

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 mutating 5-parameter tool with an output schema present, the description covers the heuristic, the failure report (still_overflowing), scope selection, verification guidance, and save behavior. The only minor gaps (shape's type, slide reference convention) appear to be shared conventions across the sibling toolset, so little is left unknown for an agent making the call.

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, the description carries the load and meaningfully clarifies min_size (floor in pt), shape (None means every overflowing shape), and backup (False skips rotation). file_path and slide are left implicit, and shape's type is unspecified, but the otherwise-ambiguous parameters are compensated for.

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?

Opens with a specific verb+resource ('Shrink overflowing text to fit') and details the mechanism (largest uniform font scale via an average-glyph-width heuristic, rewriting run sizes, enabling normAutofit). This clearly separates it from sibling text tools like get_text, find_text, and search_and_replace, which read or edit text content rather than fit it.

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?

Provides clear when-to-use context: apply when text overflows, with shape=None extending the operation to every overflowing shape and min_size acting as the floor. It also advises a concrete verification step with export_slide_images due to the estimate heuristic. It stops short of naming sibling alternatives or stating when not to use it (e.g., when exact font metrics are required).

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