Modify Doc Text

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

Annotations already signal mutation and destructiveness, and the description adds useful context: a single operation can combine text insertion/replacement with formatting, and end_of_segment avoids index calculation errors. The segment_id warning adds a safeguard about where IDs must come from. The description doesn't enumerate every destructive consequence, but 'replace' plus destructiveHint covers the core risk.

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 four sentences with no filler. The main capability is front-loaded, followed by a practical tip and two targeted warnings. Every 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?

For a 21-parameter mutating tool, the description covers the main operations, a common failure mode, and the sensitive segment_id case, while the output schema handles return details. It does not explicitly explain deletion via empty-text replacement or all parameter combinations, but the schema covers those mechanics. Overall this is solid but not exhaustive.

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?

All 21 parameters have schema descriptions, so the baseline is 3. The description adds genuinely non-obvious guidance: end_of_segment=true avoids index calculation errors, and segment_id should only come from inspect_doc_structure output, not guessed values. This goes beyond what the schema property descriptions 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?

The description states a specific verb and resource: 'Modifies text in a Google Doc.' It clearly distinguishes the tool's capabilities by naming insert, replace, and formatting in a single operation, and the header/footer note helps separate it from update_doc_headers_footers.

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 routes ordinary header/footer text to update_doc_headers_footers and warns against passing guessed segment IDs. It also gives concrete when-to-use advice for end_of_segment=true, making the selection and invocation guidance direct.

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