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

Annotations only cover the safety profile (non-read-only, non-idempotent, non-destructive). The description goes well beyond, disclosing the default new-paragraph behavior and the conditional paragraph break, text normalization (carriage returns to \n, control-character stripping), and the appended index range usable downstream.

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?

Purpose is front-loaded in the first sentence, then routing, defaults, return values, and normalization each earn their sentence. Dense but zero waste.

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?

No output schema exists, yet the description documents what is returned (insertedLength, textStartIndex/textEndIndex) and how to consume it, and covers the mutation's edge cases. Nothing needed to call it 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?

Schema coverage is 100%, so baseline is 3; the description adds real meaning the schema does not, notably how startNewParagraph interacts with a non-empty last paragraph and the role of \n in creating further paragraphs.

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+resource+scope (append text to the end of a Google Doc's body) and explicitly contrasts with the sibling insert_text. An agent can distinguish it from insert_text and format_text without opening a 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?

Explicitly names the alternative and the selecting condition: 'prefer this over insert_text whenever content should go at the end.' No prerequisite/authentication guidance, but the routing guidance is unambiguous.

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 declare readOnlyHint=false and openWorldHint=true, but the description goes further with behavior the annotations cannot convey: the loopback callback means the flow only works when the user's browser is on the machine running the server, and the server receives the result automatically. It also discloses that no change occurs when credentials already exist. This is exactly the kind of context that prevents misuse.

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 sentences, front-loaded with the action and the returned artifact, then the procedural steps. Nothing is wasted, though the final conditional clause is slightly buried after the procedural instructions rather than merged with the earlier force mention.

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?

Although there is no output schema, the description explains the return value (authUrl) and what must be done with it. For a two-optional-parameter auth flow with annotations covering the safety profile, an agent has everything needed to call it correctly and handle 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 coverage is 100% and both parameters carry their own descriptions, so the schema does the heavy lifting. The description reinforces force's semantics ("unless force is true") but says nothing about openBrowser, adding no meaning beyond the schema. 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?

"Start the Google OAuth sign-in" is a specific verb+resource and immediately separates this from sign_out and get_auth_status in the sibling list. The description also names the artifact it produces (authUrl), so an agent knows exactly what the tool does before 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?

It states the full workflow: show the URL, wait for user confirmation, then call get_auth_status. It also names the alternative condition explicitly ("If already signed in, nothing happens unless force is true"), which tells the agent when a call is a no-op and how to override it.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds value beyond them by explaining that a brand-new document is produced with a new title and that the response includes the new ID and URL, which compensates for the absence of an output schema.

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 compact sentences that are front-loaded with the core action, followed by return info and a use case. 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?

Covers what the tool does, roughly what is preserved, the return values, and a use case, which is sufficient for a simple two-parameter tool. The only minor gap is not stating that repeated calls yield distinct new documents (consistent with idempotentHint=false).

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%, and the schema already documents both parameters, including the accepted URL format for documentId. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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 (Create a copy) and resource (existing Google Doc) plus the scope of what is copied (content and formatting). It is clearly distinct from destructive or read tools, but it does not explicitly differentiate itself from the sibling create_document, which is a natural point of confusion.

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?

Gives clear usage context ('useful for templates or making a backup before large edits'), which tells an agent when this tool is appropriate. However, it names no alternatives or exclusions, so it does not explicitly contrast with create_document or get_document.

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 readOnly=false, destructive=false, idempotent=true, so safety is covered. The description adds substantive behavior beyond that: consecutive paragraphs merge into one list, leading tabs become nesting levels and are removed, which shifts later indexes while otherwise indexes are unchanged. Auth/permission and error behavior are not covered.

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 sentences, front-loaded with the core action, then the listType options and default, then the new-content workflow and index-shift caveat. Every clause carries information; 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?

For a non-destructive, idempotent mutation tool with no output schema, the definition covers purpose, options, workflow, and index side effects well. It does not mention permissions/scope requirements or what the call returns, leaving minor gaps.

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 baseline is 3. The description adds meaning beyond the schema: it explains the nested-file default for listType, the '1., a., i.' numbering forms, and—most importantly—that leading-tab characters in the target paragraphs drive nesting levels, which is not captured in any parameter description.

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 and resource: turning paragraphs in an index range of a Google Doc into list items. It names concrete variants (bulleted/numbered/checkbox) and is easily distinguished from siblings like format_text or set_paragraph_style, which don't create list structure.

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?

Gives clear context for use and a workflow: to build a list from new content, append/insert the items as newline-separated lines first, then call this with their range. It also points to get_document for obtaining indexes. No explicit exclusions or when-not-to-use against specific siblings, so slightly short of 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 indicate a non-read-only, non-idempotent mutation, and the description adds context by disclosing the exact return values (documentId, title, URL) and the plain-text-only behavior. It does not fully discuss authentication prerequisites or side effects on Drive, but the description meaningfully expands on what the annotations alone 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?

Three sentences carry the core create behavior, return values, formatting limitations, and sibling tool routing with no filler. The most important information is front-loaded, and each sentence earns its place.

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?

Despite having no output schema, the description discloses return values and the plain-text limitation, which are the main gaps an agent would need to know. It also covers what to use next for formatting and content additions, making it complete for a tool of this complexity.

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 title and initialContent with examples and constraints. The description mentions 'given title' and 'initial plain text,' but these largely mirror the existing parameter descriptions rather than adding significant new meaning 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 starts with a specific verb and resource: 'Create a new Google Docs document with the given title in the user’s Google Drive,' and further specifies optional initial content. It clearly distinguishes this tool from siblings like append_text, copy_document, and delete_document by stating what it does and what it returns.

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 routing guidance: it warns that formatting is not created from plain text and directs the agent to set_paragraph_style, format_text, or create_bulleted_list, plus find_text or get_document for indexes. It also explicitly says to use append_text for adding more content later, which is strong when-to-use-versus-alternatives 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 declare destructiveHint=true, but the description adds context annotations cannot convey: the deletion is reversible ('NOT permanently deleted'), the recovery window (30 days in Drive trash), and an accepted-input restriction (Docs files only). This is exactly the behavioral detail an agent needs before calling a destructive tool.

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 short sentences, front-loaded with the action and mechanism, then recovery behavior, then scope limits, then calling conditions. No redundant restatement of the title or 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?

For a single-parameter destructive tool with no output schema, the definition covers reversibility, recovery window, accepted input type, and invocation preconditions. Annotations carry the safety profile and the description fills in everything else needed 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 description coverage is 100% and the single documentId parameter is fully documented in the schema, including the URL-extraction hint. The description adds nothing further about the parameter, so the baseline 3 applies.

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?

Specific verb+resource ('Delete a Google Doc') with an immediate clarification of mechanism ('by moving it to the user's Google Drive trash'). The scope constraint 'Only Google Docs files are accepted' distinguishes it from sibling text/format tools like delete_text, and the trash semantics separate it from any hard-delete operation.

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?

Gives an explicit precondition ('Only call this when the user clearly asked to delete this specific document') and a when-not branch ('if it is ambiguous which document is meant, ask the user first'). It does not name sibling alternatives such as delete_text for removing content inside a doc, so it stops short of full alternative 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?

Annotations already flag destructiveHint=true, but the description adds substantial context beyond them: the expectedText mismatch guard (nothing deleted, current text returned), the un-deletable final newline, paragraph-merge on break deletion, whole-table-only deletion, index shifting, and version-history-only recovery.

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?

Long but front-loaded with the DESTRUCTIVE warning and endIndex exclusivity first. Every sentence carries operational information, though a few clauses could be tightened without losing meaning.

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?

Complete for a destructive mutation tool with no output schema: it discloses the guard's return behavior on mismatch, the index bounds invariant, and recovery limitations. Nothing an agent needs to call it safely 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 schema already documents all four parameters and their semantics. The description still adds value by explaining the guard behavior of expectedText (including the "\n" paragraph-break requirement) and echoing the inclusive/exclusive index semantics.

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 (delete), a precise resource (content in [startIndex, endIndex) of a Google Doc), and clarifies scope (endIndex exclusive). Clear differentiation from siblings like delete_document and replace_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?

Explicitly says to obtain indexes from get_document or find_text immediately before calling, and routes the 'delete every occurrence' case to replace_text with an empty replacementText. Covers both when-to-use and the alternative.

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 declare readOnlyHint and openWorldHint; the description adds substantive behavior beyond that: literal matching with no wildcards/regex, case-insensitivity unless matchCase is true, matches cannot span paragraphs or include the line break, and indexes are invalidated by subsequent edits. These are exactly the failure modes an agent would otherwise hit blindly.

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?

Purpose and return shape come first, then routing to sibling tools, then matching caveats and the edit-order rule. It is dense but every sentence carries actionable information 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?

There is no output schema, so the description correctly compensates by enumerating the return fields (startIndex/endIndex, paragraph style, table membership, context snippet). Combined with the literal-match and index-lifetime caveats, an agent has everything needed to call it and use the result 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?

Schema description coverage is 100%, so the baseline is 3; the description still adds meaning by explaining that matching is literal and case-insensitive unless matchCase is true, clarifying the semantics of that flag. It adds nothing further about maxResults, which the schema already covers via totalMatches.

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 ('Find every occurrence of a literal phrase in a Google Doc') and immediately delimits scope ('including text inside table cells'). It also enumerates what is returned, so the agent knows exactly what this tool produces versus sibling readers like get_document.

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 names the downstream consumers ('index-based tools such as format_text, delete_text, insert_link or insert_text'), which tells the agent when to reach for find_text instead of replace_text. It also gives an operational rule for multi-edit workflows: work from the last occurrence backwards.

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 cover the safety profile (idempotent, non-destructive, open-world), so the bar is lower, yet the description adds real value: only passed properties change, all other formatting is preserved, false removes a boolean style, and "Does not change text or indexes." That partial-update semantics is the key behavior an agent must know and is not in 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?

A single dense paragraph that front-loads the action, the range semantics, and the property list before moving to constraints and index sourcing. Every sentence carries information; it is slightly overloaded, which keeps it off a 5.

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 still covers mutation semantics, the at-least-one-property constraint, index sourcing, and that text/indexes are untouched. It omits what the call returns and error behavior for out-of-range indexes, but nothing critical for correct invocation 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 every parameter including units, ranges and hex format. The description largely restates this (fontSize in points, hex colors, exclusive endIndex), adding only marginal extra context, so the baseline of 3 applies.

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 ("Apply character formatting") plus resource and scope ("text in the index range [startIndex, endIndex) of a Google Doc"), and enumerates the exact properties it can set. This clearly distinguishes it from siblings like set_paragraph_style and delete_text without opening any 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?

Explicitly routes the agent to get_document or find_text for indexes and notes that append_text/insert_text return the range of new text, which is exactly the pre-condition an agent needs. It also states "At least one property is required." It does not explicitly name when NOT to use it (e.g., paragraph-level styling belongs to set_paragraph_style), so it stops short of full 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered by structured data. The description adds genuinely non-derived context: the check covers both sign-in state and Docs/Drive permissions, and 'Never returns tokens' is a useful privacy/safety guarantee an agent can rely on. It stops short of saying what it does return (e.g., account identity, granted scopes), which keeps it out of the top band.

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, zero filler: the first defines the check, the second routes usage and ends on the safety guarantee. The most decision-relevant content (what it checks) 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 zero-param status probe with no output schema, the description is nearly sufficient: it says what is verified and what will never be leaked. The one remaining gap is the shape of a successful response (status value, account, scopes), which matters when the agent must 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?

The tool takes zero parameters and the description introduces none, so there is nothing to mis-specify. With no parameters the baseline is 4; there is no schema detail the description could usefully add.

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 and resource ('Check whether this server is signed in to Google') and further specifies the scope of the check (permissions required for Google Docs and Google Drive). This clearly separates it from siblings like `authenticate` and `sign_out` without needing to open any 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?

Gives two explicit trigger conditions — after another tool fails with NOT_AUTHENTICATED or AUTH_EXPIRED, or after the user signs in via `authenticate` — and names the sibling to pair it with. Nothing about when to invoke it is left to inference.

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=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: truncation of long documents to maxTextLength, the valid insertion range 1..bodyEndIndex-1, and that the structure outline is on by default. It omits auth/permission requirements and rate limits.

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 sentences, front-loaded with what is returned and why it matters, and the truncation caveat placed last. Dense but no filler; slightly long clauses keep it from a 5.

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 carries the full return-value burden and does so completely: it documents the payload fields, the bodyEndIndex validity contract, and truncation limits. An agent has everything needed to call and consume this 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, but the description adds meaning beyond the schema: it explains that includeStructure is 'needed for index-based edits' and ties maxTextLength to actual truncation behavior. The documentId param is fully documented 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?

States a specific verb+resource ('Read a Google Doc') and enumerates exactly what is returned (title, URL, plain text, structure outline, bodyEndIndex). This sharply distinguishes it from sibling readers like list_documents and search_documents.

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?

Explicitly states when to use it: 'Use this before index-based edits such as insert_text, delete_text or format_text.' It names the concrete sibling tools and the precondition that selects this one, leaving nothing to inference.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds real context beyond them: only http/https/mailto schemes are accepted, the underlying text is unchanged, any existing link is replaced, and indexes are preserved after the operation.

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?

Front-loads the core operation, then follows with the replacement semantics, the new-text workflow, and the index sources. Every sentence carries distinct information 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?

For a 4-required-param mutation tool with no output schema, the description supplies the behavioral facts an agent needs: accepted schemes, replacement behavior, and the index-preservation guarantee that tells the caller no reindexing is required.

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 meaning beyond the schema: it explains the half-open range notation [startIndex, endIndex), the scheme restriction on url, and the invariant that indexes do not shift. This is more than the schema's field-level notes provide.

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 precise verb+resource: turn existing text in an index range of a Google Doc into a hyperlink. It names the exact range syntax and the url target, making it clearly distinguishable from siblings like format_text or insert_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?

Explicitly routes the agent: to link new text, first add it with insert_text or append_text (noting both return the range), then link that range. It also names get_document and find_text as the sources of valid indexes, so when-to-use and prerequisites are fully covered.

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 cover the safety profile (readOnly=false, idempotent=false, destructive=false), while the description adds the non-obvious side effect that inserting shifts every later index and mandates a re-read before subsequent edits. That is meaningful behavioral context beyond the structured fields.

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 tight clauses with zero filler: the action and effect come first, then the validity constraint, then the index-shift caveat. Nothing is repeated from the schema or annotations.

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 needed (the effect is described) and annotations covering the mutation profile, the description supplies the remaining essentials: placement constraints, index sourcing, and the shift side effect. An agent has everything required 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 a real constraint not in the schema: the index must fall inside an existing body paragraph and not inside a table/header/footer/footnote. It also points to where valid indexes come from, though it doesn't restate index bounds or documentId handling.

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+resource ('Insert a page break ... of a Google Doc') and immediately describes the effect ('content after it starts on a new page'), which distinguishes it from siblings like insert_text or insert_table.

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?

Gives explicit preconditions (index must be inside an existing body paragraph; not inside table, header, footer or footnote) and routes to the right helpers ('use its startIndex from get_document or find_text'). It also prescribes a required follow-up (re-read with get_document before further index-based edits).

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 supply the generic mutation profile (not read-only, not idempotent, open-world). The description adds non-obvious operational behavior beyond that: Google inserts a paragraph break so the table actually starts at index+1 (returned as tableStartIndex), every cell begins with an empty paragraph, and all later indexes shift after insertion.

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?

Front-loaded with the core action in sentence one, then behaviors, then the fill workflow. Dense but every clause carries actionable information; the cell-fill ordering note ('start from the LAST cell') is slightly beyond the core insert task but still earns its place given the index-shift 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?

For a destructive-free but index-shifting mutation with no output schema, the description covers the resulting offset behavior, the returned tableStartIndex, cell paragraph initialization, and the required follow-up calls. Nothing an agent needs to invoke and then use this 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?

Schema description coverage is already 100%, so the baseline is 3, but the description contributes real semantics the schema lacks: the index must fall inside an existing paragraph, must not be a table start or footnote, and the bodyEndIndex-1 convention for appending. Range details (1-100 rows, 1-20 cols) are left to 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?

States a specific verb and resource ('Insert an empty table ... at an index of a Google Doc') plus the key qualifier that the table is empty. This clearly distinguishes it from sibling mutations like insert_text, insert_page_break, and create_bulleted_list.

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?

Explicitly states placement constraints (index must be inside an existing paragraph, not at a table's start, not inside a footnote), names the workaround for appending (bodyEndIndex-1 from get_document), and directs the agent to get_document + insert_text for the follow-up fill step. When-to-use, when-not-to-use, and alternatives are all covered.

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?

Goes well beyond annotations by disclosing the index-shift side effect of every insertion, that inserted text inherits neighbouring style, that "\n" creates paragraphs, and the valid index boundary (1 .. bodyEndIndex-1). These are exactly the non-obvious behaviours an agent needs for a non-idempotent mutation.

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?

Front-loaded with the core action, then progressively adds index sourcing, edge cases, and routing to siblings. Dense but every sentence carries information; the index-shift warning is the only part that could be tightened.

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 3-parameter mutation tool with no output schema, the definition covers indexing rules, side effects, style inheritance, and alternatives completely; an agent has everything needed to invoke it correctly on the first try.

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 already 100%, so the baseline is 3; the description still adds real value by stating the body starts at index 1, the largest valid index is bodyEndIndex-1, how to obtain the index, and that paragraph startIndex can be used to insert at a paragraph start.

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 (insert) plus resource (text) plus precise location (at a specific index of a Google Doc), immediately distinguishing it from append_text and replace_text in the sibling list.

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?

Explicitly routes the agent: index comes from get_document or find_text, end-of-document insertion should use append_text, and rewording should use replace_text. It also gives the multi-edit workaround (work backwards or re-read).

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 and openWorldHint, so the safety profile is covered. The description adds ordering behavior, the optional name filter's semantics, the pagination contract (nextPageToken), and the returned field set — genuine context beyond the annotations, though it does not mention rate limits or Drive permission nuances.

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 tight sentences, front-loaded with the core action and scope, then filtering, then return shape, then the sibling routing. No filler and no repetition of the title.

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 usefully enumerates return fields and the pagination token, covers the filter option, and routes to search_documents for content search. An agent has everything needed to call it correctly on the first attempt.

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 and the schema already documents limit, search, and pageToken in detail, including the case-insensitive prefix-matching nuance. The description only restates the search-as-name-filter behavior, adding little beyond the structured data.

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 and resource ('List Google Docs'), plus scope ('the user can access in Google Drive') and ordering ('most recently modified first'). It also names the sibling it is not — search_documents — so an agent can distinguish the two without opening either 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?

Explicitly says to use search_documents when searching inside document content, which is the one plausible confusion for this tool. It also notes the `search` param filters names only, reinforcing when this tool applies versus the content-search alternative.

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 destructiveHint=true, openWorldHint=true, and idempotentHint=false, and the description corroborates it by explaining that an empty replacementText DELETES every match. It adds further behavior annotations do not carry: case-insensitive default matching, plain-text (non-regex) semantics, substring false-positive risk, the occurrencesChanged return value, and index shifting after length-changing replacements.

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 behavior and the biggest pitfall (short search strings, empty replacement = deletion) are front-loaded. The remaining sentences each carry a distinct fact — matching semantics, alternative tools, return value, index shifting — 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?

Given a destructive write tool with no output schema and fully documented params, the description covers the gaps that matter: what deletion means, matching rules, how to preview, what is returned, and the index-shift caveat. An agent has enough to invoke it 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?

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: an empty replacementText deletes matches, matchCase is false by default, searchText is literal plain text, and matching may hit substrings inside other words. This clarifies parameter interaction rather than restating field docs.

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 (replace) plus resource (text in a Google Doc) with explicit scope: ALL occurrences, throughout the entire document, in one operation. This clearly separates it from the sibling single-occurrence tools insert_text/delete_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?

Gives an explicit when-to-use condition for itself (bulk replacement) and names the alternatives: preview with find_text when the search text is short or ambiguous, and use insert_text/delete_text for a single occurrence. Also warns when NOT to trust the naive approach.

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 supply readOnlyHint and openWorldHint, but the description adds substantial behavioral context: trash/access filtering, word-prefix rather than substring matching (with a concrete 'Prop'/'FYP Proposal' example), Drive's asynchronous indexing lag, and differing result ordering per mode. It also discloses the returned fields and pagination token, which annotations cannot cover.

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?

Front-loads the core purpose in the first sentence, then uses a tight bulleted structure for mode-specific behavior, and closes with return fields plus sibling routing. Despite its length, every sentence conveys non-redundant, decision-relevant information.

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?

Although there is no output schema, the description enumerates the return fields (documentId, name, URL, createdTime, modifiedTime) and the nextPageToken pagination mechanism, covering what the output schema would otherwise have to provide. For a 4-parameter read tool with an enum, nothing an agent needs to invoke it 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?

Schema coverage is 100%, so the parameter definitions already carry baseline meaning. The description goes beyond that by explaining the semantics of each searchIn value (prefix-matching for name, full-text index for content, relevance ordering for both) and how pageToken pairs with the same query/searchIn — real added value over the schema's terse enum 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?

States a specific verb and resource ('Search the user's Google Drive for Google Docs by name and/or content') and bounds the result set (only accessible, non-trashed Docs; other file types never included). It explicitly differentiates itself from siblings find_text and list_documents by naming both.

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?

Gives explicit routing: use find_text to locate text inside one specific document, list_documents to list recent documents, and this tool for cross-Drive search. It also explains when each searchIn mode is appropriate and what each returns, so the alternative-selection problem is fully resolved.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds genuinely non-redundant behavior: whole paragraphs are aligned even if the range covers only part of one, and text/indexes are unchanged. This is useful context beyond the structured fields, though auth/permission needs are unaddressed.

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?

Front-loaded with the core action and range, followed by enum semantics, edge-case behavior, and index sourcing. 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?

For a 4-parameter mutation tool with no output schema, the definition covers effect, range semantics, enum meanings, whole-paragraph behavior, and index sourcing. Nothing an agent needs to call it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it defines the range as inclusive-exclusive '[startIndex, endIndex)' and glosses the enum values (START = left, END = right in left-to-right text). This supplements the terse schema enum label 'Paragraph alignment.'

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 (set) and resource (horizontal alignment of paragraphs overlapping an index range), immediately distinguishing it from siblings like format_text and set_paragraph_style. An agent can tell exactly what operation is performed 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?

It clearly directs the agent on where to obtain inputs ('Get paragraph indexes from get_document's structure outline or find_text'), naming concrete alternative sources. However, it never states when to use this tool versus sibling mutators like set_paragraph_style or format_text, so sibling routing is left implicit.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, so safety is covered; the description contributes beyond that by disclosing the non-obvious expansion behavior (whole paragraphs are restyled even for partial ranges) and the guarantee that text and indexes are unchanged. It does not mention revision IDs or response shape, but the key side effect is disclosed.

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 compact sentences, front-loaded with what is set and over what range, then the behavioral caveat, then usage and provenance of indexes. No filler or restatement of the title.

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 definition covers range semantics, side effects, and index sourcing adequately. The only thin spot is the return payload (e.g., revisionId) and no explicit preconditions such as required scopes, but nothing essential for correct invocation 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 adds genuine semantics the schema lacks: the inclusive/exclusive range boundary plus the paragraph-granularity expansion rule, which is exactly what an agent needs to predict the effect of a partly-covering range. The style and documentId parameters are left to 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?

Specific verb (set) plus resource (named paragraph style) with the full enum enumerated inline and the affected scope stated as 'every paragraph that overlaps [startIndex, endIndex)'. This clearly separates it from siblings like format_text and set_alignment, which operate on character/alignment attributes rather than named paragraph styles.

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?

Gives concrete usage intent ('turn a line into a heading or back into normal text') and tells the agent where to obtain the indexes (get_document structure outline or find_text), which is real routing guidance. It stops short of an explicit when-not clause naming format_text/set_alignment as the alternatives for non-paragraph styling.

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, idempotentHint=true and openWorldHint=true, but the description adds substance beyond them: exactly what is destroyed (locally stored OAuth tokens, revoked server access), the blast radius (every Google Docs tool fails afterward), and the recovery path (call `authenticate` again). That is high-value behavioral context an agent needs before firing a destructive, hard-to-undo action.

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 short sentences, front-loaded with the action and its effects, then the usage restriction. Every sentence carries distinct information with no padding or repetition of the title.

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 zero-parameter destructive tool with full annotation coverage, the description supplies everything an agent needs: effect, scope of damage, prerequisite for recovery, and a usage constraint. No output schema exists, and the description already explains the post-condition, so nothing further is required.

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 tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. The schema is empty with additionalProperties=false, making the no-argument contract unambiguous.

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 and resource: sign out, revoke this server's Google access, delete locally stored OAuth tokens. It is immediately distinguishable from the sibling `authenticate`, which is the inverse operation, and from `get_auth_status`.

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?

Explicitly bounds when to use it: 'Only use it when the user explicitly asks to sign out or switch accounts.' This is a clear when-to-use condition with an implied when-not (do not call it unprompted), leaving nothing to inference.

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