Get Doc as Markdown

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

Annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral context beyond that: it preserves formatting, includes comments by default, preserves anchor text, and exposes suggestion rendering behavior. These details meaningfully inform an agent about what the output will contain.

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 well-organized into three focused paragraphs, front-loads the core purpose, and uses the second sentence to differentiate from a sibling. Every sentence adds useful information without redundancy or unnecessary padding.

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?

The tool has a rich input schema and output schema, and the description covers the key behavioral decisions an agent needs: Markdown formatting, comment inclusion, comment modes, and suggestions rendering. No critical calling context is missing given the structured annotations and schema already present.

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 input schema already documents every parameter clearly. The description adds useful high-level context about comment anchor text and Markdown features, but it does not materially deepen the per-parameter semantics beyond what the schema already provides.

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 'Reads a Google Doc and returns it as clean Markdown' and enumerates the formatting features it preserves. It also explicitly contrasts itself with get_doc_content, making its identity and scope 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 explicitly names the sibling alternative get_doc_content and states the deciding difference: plain text versus Markdown-preserving output. It also explains comment behavior and modes, so an agent understands when this tool is appropriate and when another tool would be better.

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