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

The description reveals important behavior beyond the annotations: it names the underlying API calls (documents.create vs Drive conversion), explains how markdown becomes native Docs formatting, discloses the returned fields (id, name, mimeType), and states the file lands in My Drive root. This is rich behavioral context and is consistent with the annotations.

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 compact yet information-dense. The main action is front-loaded, and each sentence adds distinct value: the basic behavior, the no-markdown path, the markdown conversion path, and the location/scope limitation. There is no filler.

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?

Even without an output schema, the description explains the return value, the two creation paths, the markdown formatting behavior, and the file location side effect. It also notes what the server does not handle. For a two-parameter create tool, this is complete enough for an agent to call it correctly.

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, but the description adds real meaning: it clarifies that the no-markdown path accepts only a title, and it explains the conversion behavior and result shape of the markdown parameter. This goes beyond the schema's simple field descriptions.

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 and resource: 'Creates a new Google Doc and returns its documentId.' It clearly differentiates the two modes (empty vs markdown) and references insert_text/import_markdown as follow-up tools, helping an agent distinguish it from those siblings.

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?

It gives concrete usage context: without markdown the doc is created empty and content is added later via insert_text/import_markdown; with markdown, content is converted natively. It also warns that moving/sharing is outside this server's coverage. It does not explicitly enumerate when to prefer other creation-related siblings, but the guidance is sufficient for the main decision.

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

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

The description goes well beyond the annotations: it discloses that deletions are irreversible, that indexes shift after every delete, that deleting a trailing newline merges paragraphs, and that the tab's final newline cannot be deleted. These are critical behavioral details not captured by destructiveHint or readOnlyHint.

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 compact and front-loaded with the core operation, then packed with only high-value caveats. Every sentence contributes unique operational information, with no filler or repetition of schema content.

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 destructive mutation tool with no output schema, the description covers the full set of needed constraints: valid range contents, table boundary restriction, index refresh requirement, shift behavior, merge behavior, an exception, and irreversibility. An agent has enough information to invoke this tool correctly and safely.

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 already documents all five parameters with 100% coverage. The description adds useful context about start/end index semantics and indexing shifts, but it does not substantially clarify tab_id, segment_id, or document_id beyond what the schema already states. Baseline 3 is appropriate.

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 operation ('Deletes the content in [start_index, end_index)') and the resource type (text range), and adds concrete scoping details like inline images, whole tables, and the table-cell-boundary restriction. This makes it easy to distinguish from sibling edit tools like insert_text or replace_range.

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?

It gives explicit operational guidance: fetch fresh indexes from read_document_text first, index shifting behavior, the final-newline exception, and the no-undo warning. It does not explicitly name an alternative tool for delete-like operations, but the prerequisite and exclusions are clear enough for correct use.

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

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

Beyond the destructiveHint=true annotation, the description discloses that deleting a row/column removes ALL its content and that the content is unrecoverable. It also warns that deletions shift every later index in the document, requiring a re-read. This is exactly the kind of behavioral context the annotation alone does not provide.

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 dense but efficient; every sentence carries essential operational information: how the table is addressed, how insert actions behave, how delete actions are destructive, index defaults, and the re-read warning. It avoids fluff while front-loading the core purpose.

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's complexity — four actions, eight parameters, destructive behavior, and index-shifting side effects — the description covers everything needed to invoke it correctly: addressing, defaults, insertion direction, irreversibility, and the need to re-read after deletion. No output schema exists, but return values are not necessary for correct invocation here.

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%, but the description adds meaningful cross-parameter semantics: it explains that row_index/column_index identify the anchor cell, that insert_below and insert_right default to true, and that table_start_index comes specifically from read_document_text/get_document. This goes well beyond the individual property descriptions in the 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 a specific verb and resource: 'Inserts or deletes a row/column of an existing table.' This differentiates it from sibling insert_table, which creates new tables, by explicitly scoping to existing tables and enumerating the four supported actions.

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?

It provides clear procedural context: the table is addressed via table_start_index from read_document_text, indices are 0-based, and the agent is told to re-read before further edits after deletions. It does not explicitly name alternatives or state when not to use this tool, but the guidance is sufficiently clear to route an agent correctly.

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

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

The description goes well beyond the annotations by disclosing that Google Docs content is never modified, the only side effect is a local file when output_path is set, existing files are never overwritten unless overwrite=true, exports are capped at 10 MB, and comments/suggestions are excluded. It also describes the result contents (saved_to and bytes for binary exports), giving the agent a strong model of the tool's behavior.

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 dense but every sentence earns its place: format categories, the markdown use case, output_path behavior, overwrite rules, API limits, and side effects. It is front-loaded with the core purpose and then branches logically into format-specific details without any fluff.

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 tool with no output schema, the description is remarkably complete: it covers return behavior for text formats, file-writing behavior for binary formats, overwrite semantics, absolute path requirements, size limits, content exclusions, and side effects. An agent has everything needed to call this tool correctly and predict its results.

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 schema already documents every parameter. The description adds meaningful semantics beyond the schema, such as which formats are returned inline versus written to disk, that output_path must be absolute, and that binary exports report saved_to and bytes. This is more than a baseline 3 but not quite a 5 because the schema itself already carries good descriptions.

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 action ('Exports the document via Drive') and a specific resource (a Google Doc identified by document_id). It also distinguishes between text and binary export behaviors, and explicitly positions format=markdown as the way to read a doc as Markdown for a round trip with import_markdown, which differentiates it from sibling read tools.

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 clear context for when to use the tool, including the markdown round-trip use case and the requirement of output_path for binary formats. It does not explicitly list exclusions or name sibling alternatives like read_document_text, but the practical usage guidance is clear enough that an agent can select it appropriately.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it warns that the output is 'VERBOSE,' reveals the default behavior of include_tabs_content, and explains how suggestions_view_mode changes rendering. This gives the agent realistic expectations about payload size and output shape.

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 dense but efficiently structured: first the return payload, then the critical verbosity warning and sibling routing, then the parameter defaults. Every clause adds information, though the long em-dash sentence packs many items together and is slightly harder to parse than a short list would be.

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 no output schema, the description must carry the burden of explaining return values, and it does so in useful detail: field names, index semantics, tabs, headers/footers segment ids, and image ids for replace_image. It also signals the relationship to range tools. Minor gaps remain, such as not describing error conditions or how large the payload can be beyond 'VERBOSE,' but it is complete enough for an agent to call the tool and interpret the result.

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 baseline is 3. The description adds extra value by restating the defaults ('include_tabs_content=true (default)', 'suggestions_view_mode ... DEFAULT_FOR_CURRENT_ACCESS') and by explaining the semantic consequence of false for include_tabs_content ('first-tab legacy shape'). That is meaningful beyond the schema's field-level descriptions.

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 ('Returns') and a precise resource ('the raw Docs API document'), then enumerates exactly what that includes: title, documentId, revisionId, per-tab body, indexes, styles, tables, lists, inlineObjects, headers/footers, and named styles. It also differentiates itself from the sibling read_document_text by labeling itself as the verbose, index-map-producing variant, so an agent can tell them apart without inspecting schemas.

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 when-to-use guidance: this tool is 'the exact index map that range tools consume,' meaning it should be selected when structural indexes are needed. It also names the alternative directly: 'for reading content prefer read_document_text, which returns compact blocks with the same indexes.' This is clear, actionable sibling routing.

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

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

The description goes well beyond the annotations, which already flag destructiveHint=true and readOnlyHint=false. It details exactly what is lost (existing text, comment anchors, positioned objects, headers/footers, extra tabs), clarifies that comments survive but detach, and states the return value. This gives the agent a thorough understanding of the operation's consequences. No contradiction with annotations.

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 compact and every sentence earns its place: it leads with the destructive action, explains supported Markdown, enumerates what is lost, points to alternatives, and states the return value. There is no filler or redundant repetition of schema/annotation content.

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 destructive full-document replacement tool with no output schema, the description is remarkably complete. It explains the conversion mechanism, lists supported Markdown features, describes exactly what is lost, mentions the survival/detachment of comments, provides alternatives, and identifies the return value. Nothing critical for an agent to invoke the tool correctly is missing.

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 already provides 100% coverage for both parameters with clear descriptions. The tool description adds some context about supported Markdown features and the full replacement semantics, but it does not substantially enhance parameter understanding beyond the schema. Baseline 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 clearly states the tool's core action with a specific verb and resource: 'REPLACES the ENTIRE document content with the given Markdown'. It also distinguishes itself from siblings by referencing the Markdown round-trip writer paired with export_document and explicitly naming replace_range/style tools as the alternatives for surgical edits. An agent can immediately identify what this tool does and how it differs from other editing tools.

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 explicit guidance on when to use this tool versus alternatives: 'For surgical edits use replace_range/style tools instead.' It also implies the appropriate use case is full-document replacement with Markdown, especially in a round-trip with export_document. This is clear, contextual, and gives the agent a decision rule.

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

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

Annotations already mark this as a mutating, non-idempotent operation (`readOnlyHint: false`, `idempotentHint: false`), so the description's additional details are valuable beyond structured data. It explains that a break occupies one index position, how each kind behaves, and the constraint on insertion targets, which helps the agent predict side effects and plan subsequent operations.

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 sentences, front-loaded with the core behavior, and every sentence earns its place: position semantics, kind semantics, section style note, insertion constraints, and removal guidance. No filler or redundancy.

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 mutation tool with 5 parameters and no output schema, the description covers the essential operational details: how to specify position, what each kind does, where breaks are not allowed, and how to remove them. It lacks an explicit note about return values or invalid-index behavior, but these are not needed for correct invocation.

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, but the description adds meaningful nuance beyond the schema's terse `kind` description. It explains exactly what each enum value does and clarifies that omitting `index` appends at the end of the body. This enriches parameter understanding enough to score above baseline.

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 verb and resource ('Inserts a break') and immediately clarifies the three distinct kinds (`page`, `section_next_page`, `section_continuous`). This clearly differentiates it from sibling insertion tools like `insert_text`, `insert_table`, and `insert_image`, leaving no ambiguity about its function.

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 clear context for when to use the tool: insert at a specific index, append at end if omitted, and it explicitly states exclusions (cannot be inserted into headers, footers, footnotes, or table cells). It also cross-references `delete_range` for removal and `raw_request updateSectionStyle` for styling sections, providing useful routing hints, though it does not explicitly contrast with sibling insert tools.

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

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

Annotations only state readOnly=false and non-destructive; the description adds substantial behavioral detail: Google fetches the image, 50 MB/25 MP constraints, natural size capped to page width, aspect-ratio scaling when one dimension is given, and that the image occupies one index. It even explains deletion via delete_range, which goes beyond annotation coverage.

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 front-loaded with the main action and uses four dense but purposeful sentences. Constraints, defaults, return value, and deletion workflow each earn their place without redundancies or filler.

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 7-parameter tool with no output schema, the description covers what an agent needs: insertion behavior, required URL properties, size semantics, the returned objectId, and how to delete/replace. Remaining parameter details are already in the schema, so no critical context is missing.

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, but the description meaningfully enriches several parameters. It explains the width_pt/height_pt aspect-ratio behavior and natural-size default, clarifies 'no upload channel' for the uri, and states that a returned objectId is intended for replace_image — none of which are in the 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 opens with a specific verb and resource: 'Inserts an inline image fetched from a PUBLIC URL at an index', clearly distinguishing it from insert_text, insert_table, and insert_break. It also clarifies the end-of-body default when index is omitted, so the tool's core behavior is unambiguous.

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 clear preconditions and operating context: the URL must be publicly reachable by Google, within size/format limits, and there is no upload channel, so local files must be hosted first. It points to replace_image and delete_range for follow-up actions, though it does not explicitly state conditions for choosing insert_image over a sibling tool.

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

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

Annotations already provide readOnlyHint=false and idempotentHint=false, so the mutating behavior is known. The description adds useful context: the table is created empty, each cell holds its own paragraphs, and advanced styling requires raw_request. It does not disclose index-shifting effects on following content, but the insertion semantics and remaining annotations cover the main behavioral expectations.

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 main action is front-loaded in the first sentence, followed by a compact workflow sentence and a precise sentence listing unsupported operations and the raw_request escape hatch. Every sentence serves a purpose, and the length is appropriate for the tool's complexity.

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 mutation tool with six parameters and no output schema, the description covers the core behavior, the expected follow-up steps, and the boundary between typed tools and raw_request. The main weakness is the imprecise 'end of the body' wording given the existence of segment_id, and the absence of any mention of what the tool returns or whether existing indexes shift.

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 descriptions cover 100% of the six parameters, so the baseline is 3. The description adds workflow context but does not materially enrich parameter semantics beyond the schema; for example, index origin and segment_id behavior are already documented in the input schema. There is no additional format, default, or constraint information in the description that is not already present.

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 core operation: inserting an empty table with a given number of rows and columns at an index or appended at the end. It is distinguishable from siblings by the word 'inserts' and 'empty table', but the phrase 'end of the body' is slightly imprecise because segment_id can target header/footer/footnote segments, not just the document body. It also does not explicitly contrast with edit_table, though the semantics are clear.

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 a concrete follow-up workflow: use read_document_text to find the new table's range, then insert_text into each cell. It explicitly names the alternative for unsupported features (raw_request with mergeTableCells/updateTableCellStyle/pinTableHeaderRows), giving the agent clear when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses important side effects: every insert shifts later indexes, newlines create paragraphs, inserted text inherits style at the insertion point, and the call returns a batchUpdate reply with revisionId. This is exactly the behavioral context an agent needs.

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 carrying independent operational value: indexing, append semantics, formatting behavior, and shift ordering. The most important constraint (index source) is front-loaded.

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 mutation with five parameters and no output schema, the description covers invocation, index acquisition, ordering under repeated edits, and return value. The tab_id omission is acceptable because schema documents it and the description handles the more complex segment/index behavior.

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, but the description adds substantial meaning: UTF-16 code units, body starts at index 1, omit index to append, segment behavior, and newline handling. These details are not inferable from the schema alone.

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 precise verb and resource: 'Inserts plain text at an index' and immediately defines the indexing scheme. It distinguishes itself from sibling insert_* tools by restricting to plain text and from replace/delete tools through the insert-at-index semantics.

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?

It provides clear context: how to obtain indexes, append behavior, newline paragraph creation, and ordering advice for multiple edits. It does not explicitly state 'use replace_range instead when replacing' or otherwise enumerate exclusions, so it falls short of full when/when-not guidance.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable behavior beyond annotations: it specifies Drive API usage, requires a Drive OAuth scope, explains that include_deleted returns tombstones, and describes pagination with page_token. No contradiction with annotations.

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 front-loaded with the core purpose, then efficiently covers return shape, pagination, deleted handling, auth, and downstream usage in four concise sentences. Every sentence adds distinct value and there is no repetition of schema content.

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?

Since there is no output schema, the description compensates by enumerating the returned fields and behaviors. It covers pagination, deleted comments, authentication scope, and the relationship to manage_comment. For a read-only list tool with rich annotations, nothing essential is missing.

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 all four parameters. The description adds some context by explaining the tombstone semantics of include_deleted and that page_token is for pagination, but it does not significantly deepen parameter understanding beyond what the schema already states.

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 verb and resource: 'Lists the document's comment threads via the Drive API,' then enumerates exactly what is returned (ids, content, author, timestamps, resolved flag, quotedFileContent, replies). This clearly differentiates it from siblings like manage_comment or read_document_text by emphasizing it is read-only and Drive-specific.

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 states when to use it: to retrieve comment threads, with pagination and optional deleted-comment inclusion. It also provides routing guidance by saying 'Comment ids feed manage_comment,' and warns about the OAuth scope requirement. It does not explicitly say 'do not use for editing comments,' but the read-only framing and sibling relationship make the intended usage clear.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds meaningful context by stating that no content is returned, that the result is a nested tree, and that the Docs API cannot modify tab structure—which goes beyond the annotation hints. Slightly more detail about response shape or pagination would push it higher, but it is already strong.

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 compact and front-loaded: the core return value comes first, followed by practical usage guidance and a crucial limitation note. Every sentence adds value, and the structure is easy for an agent to parse.

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 single-parameter, read-only discovery tool with strong annotations and a clear description, nothing essential is missing. The agent learns what the tool returns, which fields to expect, how to use the output with sibling tools, and a key API limitation.

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 single parameter document_id is 100% covered by the input schema with a clear explanation of where to find the id. The description does not need to add parameter semantics, and it does not repeat or conflict with the schema. Baseline 3 is appropriate given full schema coverage.

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 action and resource: returns the document's tab tree without content, listing tabId, title, position index, and nested childTabs. This clearly distinguishes it from content-reading tools like read_document_text and from editing tools.

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?

It explicitly instructs to use tabId values to target specific tabs in read_document_text and every editing tool, establishing when to call this tool first. The NOTE also clarifies that tab creation/rename/delete/reorder is UI-only, telling the agent what this tool cannot do and preventing misuse.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses critical behaviors: delete permanently removes the comment and all replies, resolve is the reversible alternative, quoted_text cannot anchor to a live range and will appear at document level, and an OAuth Drive scope is required. This adds substantial context that the annotations alone do not provide.

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 dense but efficiently organized by action, with each clause carrying useful information. It avoids boilerplate and front-loads the core action semantics while including edge-case caveats like the non-public anchor format and permanence of delete.

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 multi-action mutation tool with no output schema, the description is remarkably complete: it covers every action, parameter requirements, side effects, reversibility, source of identifiers, and authentication scope. An agent has enough context to select the right action and invoke it correctly.

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?

Although schema coverage is 100%, the description adds meaningful parameter-level nuance: quoted_text behavior and limitations, action-specific meaning of content (optional closing reply for resolve/reopen, required for create/reply), and where document_id/comment_id come from. This goes well beyond the 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 explicitly states it manages comment threads via the Drive API and enumerates the five distinct actions (create, reply, resolve, reopen, delete). It names the specific resource (comments) and clearly differentiates each action's effect, so an agent can immediately understand what the tool does and how it differs from a read-only comments tool.

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 per-action guidance: what parameters each action requires, that resolve is reversible while delete is permanent, and that comment_id comes from list_comments. It does not explicitly say 'for read-only comment access use list_comments', but it does reference list_comments and clearly distinguishes action choices.

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

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

Annotations already flag the tool as non-read-only, destructive, and open-world, so the description doesn't need to repeat those safety traits. It adds useful behavioral context: the Bearer token is added automatically, the method defaults to GET, the path may carry a query string, and only docs.googleapis.com is reachable. These details meaningfully go beyond what annotations provide.

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 somewhat long because of the extensive list of example operations, but every part earns its place for an escape-hatch tool: the purpose is front-loaded, the example clarifies the expected shape, and constraints are stated compactly. It could be trimmed, but the density is justified.

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 tool with three parameters and no output schema, the description covers the critical invocation details: path format, supported methods, body semantics, authentication, and endpoint restriction. The only minor gap is that it doesn't describe what the tool returns, but that is not strictly required to select and invoke the tool correctly.

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 value beyond the schema by showing a concrete path with method and body, explaining that the path may carry a query string, and confirming that only docs.googleapis.com paths are valid. This helps an agent construct parameters correctly rather than merely knowing they exist.

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 action: directly calling any Google Docs API v1 path as an escape hatch. It explicitly frames the tool as covering requests the typed tools do not cover, which distinguishes it from the sibling tools. The scope is further narrowed to docs.googleapis.com paths, removing ambiguity.

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 a clear when-to-use signal: only for requests the typed tools don't cover. It also names representative use cases like batchUpdate operations with advanced table and document styles. Exclusion guidance is explicit: Drive endpoints are not reachable, so an agent won't try to use this tool for Drive operations.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: UTF-16 code-unit indexing, table cell layout, image placeholder syntax, and the stale-index warning after mutations. This is exactly the context an agent needs to interpret results safely.

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 dense but every clause earns its place, and the most important facts (content blocks and index coordinates) come first. The structure groups paragraphs, tables, and images cleanly before the usage warning.

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 no output schema available, the description fully carries the burden of explaining return values, and it does so: blocks, ranges, styles, bullets, tables, image placeholders, and tab limiting. It also includes the critical caveat about stale indexes, making the tool callable correctly without further research.

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, but the description adds meaningful param behavior: tab_id limits output to one tab and the returned coordinates are the ones accepted by edit tools. It does not repeat schema text verbatim and clarifies what changes when tab_id is omitted.

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 names a specific action ('Returns the document as compact readable blocks, per tab') and details the exact content shape: paragraph text, index ranges, styles, bullets, tables, and image placeholders. This clearly distinguishes it from sibling tools like get_document or export_document, which serve different retrieval purposes.

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?

It gives an explicit use directive: 'Call this before any range edit,' with a concrete reason that mutation shifts indexes. It does not explicitly name when-not-to-use it or route to an alternative, so it stops short of a full 5.

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

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

Annotations already mark the tool as destructive and not read-only, and the description adds valuable behavior beyond that: non-regex literal matching, global occurrence replacement, match_case defaulting to true, and the occurrencesChanged return semantics where 0 means not found. It also explains why this is safer than index-based replacement. No statement contradicts the annotations.

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 compact and front-loaded: the first sentence conveys the core operation and scope, and the remaining sentences add matching defaults, return semantics, and routing guidance. Every sentence earns its place with no filler.

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?

Even though there is no output schema, the description explains the meaningful return value and the not-found convention. It also covers tab scoping, case sensitivity, regex behavior, and how this tool relates to replace_range. This is sufficient for an agent to select and invoke it correctly.

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 baseline is 3. The description restates some schema concepts like 'literal string (no regex)' and 'match_case defaults to true', but it does not add new parameter-specific meaning beyond what the schema already documents.

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: it replaces every occurrence of a literal string across the whole document or selected tabs. It also names replace_range as a distinct alternative, so an agent can tell this tool apart from the closest sibling without opening the schema.

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 explicitly says when to use this tool vs replace_range: use replace_all_text for textual substitutions because it is not dependent on indexes, and use replace_range when position matters. It also clarifies scoping via tab_ids and the match_case default, leaving little ambiguity about invocation context.

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

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

Annotations mark destructiveHint=true and readOnlyHint=false; the description confirms destructive behavior ('replaces') and adds non-obvious traits: preserving size/position and center-cropping. It also clarifies URL rules. This adds value beyond the structured annotations without contradiction.

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?

Two sentences, front-loaded with the core behavior, then the essential operational details. Every clause earns its place; no filler or redundant restating of the schema.

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 no output schema, the description doesn't specify return values, but for a mutation tool that's often acceptable. It covers acquisition of the object id, URL constraints, and the transformation behavior. Slight omission is lack of error/edge-case notes (e.g., what if object id invalid), but overall it is sufficiently complete for an agent to call it correctly.

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% but the description enriches every meaningful parameter: it explains how to locate image_object_id in document output and links URI requirements to an existing sibling tool (insert_image). This goes beyond the schema's terse field definitions, giving the agent operational context.

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?

States a specific verb ('replaces'), resource ('existing image's contents'), and distinctive behavior (center-crop to keep size/position). Clearly distinguishes from insert_image and other mutation tools at a glance.

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 context on how to obtain image_object_id (via read_document_text or get_document) and references insert_image for URL constraints. While it doesn't explicitly say 'use this instead of insert_image for existing images', the purpose is unambiguous, so the usage guidance is adequate though not exhaustive.

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

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

The description adds substantial behavioral detail beyond annotations: the operation is a single atomic batchUpdate that protects against partial failure, new text inherits style at start_index, certain ranges are rejected by the API, and empty replacement behaves like delete_range. This is exactly the kind of context annotations cannot convey.

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?

Three dense, purposeful sentences. The core behavior is front-loaded, and each subsequent sentence adds behavioral constraints or prerequisites without any filler or redundancy.

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 tool with no output schema and six parameters, the description covers prerequisites, failure semantics, style behavior, and invalid ranges. It does not explicitly describe the return value, but for an edit operation this is not a critical omission given the rich behavioral context provided.

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 schema already documents all six parameters with 100% coverage, so the baseline is 3. The description adds valuable parameter-level meaning: range boundaries are half-open, indexes must be freshly fetched, and constraints around table cells and paragraph newlines affect valid start/end values.

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 action ('Replaces the content in [start_index, end_index) with new text'), identifies the exact resource, and clarifies edge behavior (empty replacement equals delete_range). This clearly differentiates it from siblings like insert_text or replace_all_text.

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 strong contextual guidance: fetch fresh indexes from read_document_text first, notes that indexes are stale after any prior edit, and lists API constraints on valid ranges. It does not explicitly contrast with insert_text or replace_all_text, but it is clear when this tool applies.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds the key behavioral fact that removal happens when remove=true and that nesting depends on leading tabs. It also clarifies the exclusive-preset/remove constraint, which is central to correct invocation. Not quite a 5 because it doesn't explicitly warn that applying a preset may overwrite existing formatting, but the annotations cover the destructive aspect.

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 compact and front-loaded with the main operation, then gives the preset values and the behavioral nuance about tabs and the required-argument constraint. Every sentence contributes useful information, though the preset list is a bit dense; that density is justified because the presets are enums that an agent needs to choose from.

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 mutation tool with no output schema, the description covers the required-argument rule, the range semantics, the preset choices, and nesting behavior. It doesn't describe error cases or what happens when the range contains non-paragraph elements, but the schema and annotations cover most invocation needs, making this slightly above average.

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 baseline is 3. The description adds the preset list and the semantic distinction between bulleted and numbered presets, and it explains that remove=true means 'removes bullets,' which is useful beyond the schema's one-liner. It does not add much detail about tab_id or index meaning, but those are adequately described in the 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 names a precise operation ('Turns the paragraphs overlapping [start_index, end_index) into a list, or removes their bullets') with a concrete resource and clear mode distinction. It distinguishes itself from style_paragraph by focusing specifically on bullet/numbering application and removal, so an agent can tell it apart from siblings.

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?

It explicitly states that exactly one of preset or remove is required, defines the paragraph-range behavior, and explains how to create sub-items via leading tabs. It also has a clear note about tab_id omission, which orients the agent toward list_tabs when needing to target a different tab.

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

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

Annotations already communicate that this is a write operation with destructive and idempotent traits. The description adds valuable context beyond those hints: only provided fields change, the range styles whole overlapping paragraphs, and a range inside one paragraph affects that entire paragraph. This enriches the agent's mental model without contradicting the annotations.

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 two compact sentences with no fluff. It front-loads the operation and range, packs parameters into a readable parenthetical list, and closes with the two most important behavioral nuances: partial updates and whole-paragraph styling.

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 15-parameter tool with no output schema, the description covers the subtle semantics: range overlap, single-paragraph handling, partial-field updates, and the at-least-one-field requirement. It doesn't describe return values or index conventions, but the schema and annotations carry much of that burden.

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 baseline is 3. The description adds meaning by explaining line_spacing units (100 = single, 200 = double), clarifying that headings feed the document outline, and noting that at least one formatting field is required—a constraint not encoded in the schema's required list.

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: applying paragraph formatting to every paragraph in a range. It enumerates the key formatting fields and explicitly notes this is how headings are made, making the tool's purpose unmistakable and distinct from character-level or bullet-focused siblings.

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 clearly implies when to use this tool for paragraph-level formatting and explains range-overlap behavior. However, it never names alternatives such as style_text for character formatting or set_paragraph_bullets, so an agent must infer the exclusion rather than being explicitly told when not to use this tool.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description reveals critical behaviors: partial-update masking, explicit false turning toggles off, empty link_url removing existing links, and index stability across calls. These details materially help an agent predict side effects and reuse the tool safely.

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 compact and front-loaded: the first sentence states the operation and enumerates formatting options; the following sentences each add a distinct behavioral constraint. No sentence is filler, and the density is justified by the tool's 16-parameter surface.

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, high-parameter mutation tool with no output schema, the description is remarkably complete: it covers all formatting fields, partial-update semantics, toggle behavior, link removal, index sourcing, and index stability. The only omission, the exact return value, is not essential for a write-oriented tool and is not promised by the annotations.

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 every parameter's format and meaning. The description adds valuable semantic context on top: the fields-mask behavior, the meaning of explicit false for boolean toggles, and the empty-string behavior for link_url. This goes beyond the baseline but is not exhaustive for all 16 parameters.

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 action ('Applies character formatting') on an explicit resource (a text range given by start/end indexes) and enumerates the exact formatting dimensions it affects. This clearly distinguishes it from sibling tools like style_paragraph, which targets paragraph-level formatting.

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 concrete usage guidance: obtain indexes from read_document_text, and multiple style calls can reuse the same coordinates because styling does not shift indexes. It also explains the partial-update semantics ('Only the provided fields change') and the requirement that at least one field be provided. It does not explicitly contrast this tool with style_paragraph or other siblings, but the character-range scope makes the intended use clear.

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