Read a Google Doc

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

Annotations already mark read-only and non-destructive, but the description adds meaningful behavioral context beyond that: the drive.file scope boundary, the create-or-pick prerequisite, and the specific Google error semantics. This is exactly the kind of operational detail 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?

The description is compact and front-loaded with the core purpose. Every sentence earns its place: access scope, parameter options, error handling, return value, and the read-only/free status. There is 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?

With only two optional parameters, no output schema, and read-only annotations, the description covers everything needed: input alternatives, access model, failure handling, and the plain-text return value. An agent can correctly select and invoke this tool without consulting other definitions.

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 both parameters at 100% coverage, so the baseline is 3. The description adds the otherwise-unstated relationship that the caller should pass either documentId or docUrl, while clarifying where each comes from, which is meaningful added value.

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 leads with a specific verb and resource ('Read the text of a Google Doc') and immediately scopes what 'reachable' means, distinguishing discovery via list_drive_files from reading. This clearly separates read_doc from update_doc and drive management siblings without requiring them to be named.

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 says a doc is readable only if Hermoso created it or the user handed it over via the picker, and tells agents to find existing docs with list_drive_files. It also gives actionable handling for a 'file not found' response: ask the user to pick it rather than retrying, which is explicit 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.